Hevo MCP Server Security
On This Page
The Hevo MCP server runs on your machine and acts on your Hevo account with your API credentials, so it can do anything that your role allows. To keep your account safe, the server keeps your API credentials and the passwords of your Sources and Destinations out of the conversation with your agent. Your agent sees only the location of your key file and your secrets folder, never their content, and references to your secret files in place of passwords.
The server checks the data that Hevo returns before your agent receives it. It hides secrets and removes hidden text, and the server instructs the agent to treat the data as untrusted, so that the agent does not follow instructions in a Pipeline name or an error message. The server never returns the records that your Pipelines replicate, only the configuration and the metadata of your resources.
The following sections describe how the server handles your API credentials, your passwords, and your data, the limits of these controls, and the steps that you can take to protect your account.
API Credentials
The server uses your API credentials for every request to Hevo, so it can perform any action that your role allows. The server protects them in the following ways:
-
Kept on your machine: The server runs on your machine, and your API credentials go only from your machine to Hevo, over HTTPS.
-
Never shown to the agent: The
hevo_whoamitool shows the name of the key file that the server uses, but never your Access Key or your Secret Key. -
Not stored in the plugin or the settings of your agent: The server reads your API credentials only from your key file. The Hevo plugin contains no API credentials, and the server does not read them from environment variables, as the settings files of agents can be synced or shared.
-
Protected from other users: On macOS and Linux, the server does not use a key file that other users on the machine can read. On Windows, the server does not check who can read the file, so restrict it with the commands in the Saving your API Credentials section of the setup page for your agent. On macOS and Linux, the server also does not use a key file that is a symbolic link.
Although the server never shows your API credentials to the agent, an agent that can read files on your machine can open your key file. To prevent this in Claude Code, add the following rules to the ~/.claude/settings.json file:
{
"permissions": {
"deny": ["Read(~/.hevo/**)", "Bash(cat ~/.hevo/*)"]
}
}
Claude Code then blocks the agent from reading the files in the ~/.hevo folder with its Read tool or the cat command.
Do not paste your API credentials into a conversation with your agent. If you paste them by mistake, generate a new pair of API credentials and delete the existing pair. Read Rotating your API Credentials for the steps.
Passwords for Sources and Destinations
To create a Source or a Destination, Hevo first tests the connection to it, so the request must contain the password, token, or key for the connection. To keep it out of the conversation, save it in a secret file on your machine and give the agent the name of the file. The agent puts a reference to the file in the request, such as $secret_file:mysql-prod, and the server replaces the reference with the content of the file just before it sends the request to Hevo. The conversation, the approval prompt, and the logs of the server contain only the reference, and the server does not store the password.
Perform the following steps to save a password in a secret file:
-
Run the following command to create the secrets folder, which only you can access:
mkdir -p ~/.hevo/secrets && chmod 700 ~/.hevo/secretsOn Windows, first restrict the
.hevofolder with theicaclscommands in the Saving your API Credentials section of the setup page for your agent. The secrets folder gets the same access settings as the.hevofolder. Run the following command in PowerShell to create the secrets folder:New-Item -ItemType Directory -Force "$HOME\.hevo\secrets" | Out-Null -
Run the following command to save the password in a secret file, replacing
<name>with a name for the file, such asmysql-prod:read -rs PW && printf '%s' "$PW" > ~/.hevo/secrets/<name> && chmod 600 ~/.hevo/secrets/<name> && unset PWOn Windows, run the following commands in PowerShell instead:
$pw = Read-Host -AsSecureString "Password" [IO.File]::WriteAllText("$HOME\.hevo\secrets\<name>", [Net.NetworkCredential]::new('', $pw).Password) Remove-Variable pwSave the password only with the commands in this step. Other PowerShell commands, such as
Set-Contentor>, can add characters to the file that become part of the password, or save it in a format that the server cannot read.The name must start with a letter or a digit, and can be up to 128 characters long. It can contain only letters, digits, periods, underscores, and hyphens, and cannot contain two periods in a row.
-
Type the password, and press Enter. The command does not display the password as you type it.
-
Tell the agent the name of the file. For example, The password of the database is in the secret file mysql-prod.
After you approve the request, the agent creates the Source or the Destination, and the request in the conversation shows $secret_file:mysql-prod in place of the password.
The server reads secret files only from the secrets folder next to your key file, which is ~/.hevo/secrets by default. If you set the HEVO_KEYS_DIR environment variable, the secrets folder is in that folder. The hevo_whoami tool shows the folder as secrets_dir.
If the server cannot read the file, for example, because the file does not exist or is empty, or, on macOS and Linux, because the file is a symbolic link or other users on the machine can read it, the server sends nothing to Hevo, and the agent tells you what to correct.
The server applies the following rules to references:
-
Only in a secret field: The server accepts a reference only in a field that Hevo uses for a secret, such as
password,access_token, orclient_secret. It rejects a request with a reference in any other field, such as a host or a name. -
Always approved by you: Every request that contains a reference needs your approval, even a create request. The prompt shows the reference and the request body, so that you can check the host to which Hevo sends the secret.
-
Never stored: The server reads the value when it sends the request, and never stores, logs, or shows it.
If you paste a password into the conversation, change the password in your database or application, and then update it in the Source or Destination in Hevo.
Data that the Agent Receives
The server changes the data that it returns to the agent in the following ways:
-
Secrets are hidden: In every result, the server replaces the value of every field that is named as a secret, such as
password,private_key,client_secret, oraccess_token, with[redacted]. -
Hidden text is removed: The server removes control characters, terminal codes, and invisible Unicode characters from every value that Hevo returns. As a result, a Pipeline name or an error message cannot hide instructions from you.
-
Data from Hevo is treated as untrusted: The server instructs the agent never to follow instructions found in this data.
-
Pipeline records are not returned: The server returns only the configuration and the metadata of your resources, never the records that your Pipelines replicate.
Your agent sends the data that it receives to the provider of its AI model, as part of the conversation. This data includes the names and the configuration of your resources, with secrets hidden, and, when the agent lists your team users, their names and email addresses.
Limits of the Safety Controls
The scopes, the approval prompts, and the other controls of the server protect you from mistakes by the agent, and from instructions hidden in the data that the agent reads, such as a Pipeline name that asks the agent to delete everything. They cannot stop an agent that can read files and run commands on your machine from reading your key file and calling the Hevo API directly.
Do the following to limit the access of such an agent to your Hevo account:
-
Generate the API credentials as a user with the role that has the fewest permissions that the tasks need. The credentials can never do more than this role allows.
-
Block your agent from reading the
~/.hevofolder, as described in API Credentials. -
Keep the permission prompts of your agent turned on, so that the agent asks you before it reads a file or runs a command.
Tool Fingerprint
The tool fingerprint is a hash of the full definition of every tool that your agent receives. The hevo_whoami tool shows it as tools_sha256. It remains the same for a given version and configuration of the server, so a change in the fingerprint means that the tools were changed. You can monitor the fingerprint to detect a change in the tools.
Update Check
The hevo_whoami tool tells you when a newer version of the server is available. To find out, the server sends PyPI one request when you run the tool with a region, with no API credentials or account data. Each running server sends this request at most once a day, or once an hour if the previous request failed.
Revision History
Refer to the following table for the list of key updates made to this page:
| Date | Release | Description of Change |
|---|---|---|
| Nov-18-2026 | 2.54 | New document. |