Skip to main content

Hevo MCP server

Connect AI agents to Hevo. Through Hevo's public APIs, an agent can list, inspect and manage Edge and Standard pipelines and Destinations: "which of my pipelines need attention?", "why is pipeline 12 failing?", "disable every pipeline loading into this Destination". It also manages Standard Models, Workflows, event types, schema mappings and transformations, and the team's users and OAuth accounts. Edge tools carry plain names (pipelines_read, list_pipelines); Standard tools carry a standard_ prefix (standard_pipelines_read, standard_list_pipelines), because the two products have separate APIs and separate ids.

This repository holds:

Part Where What it is
MCP server src/hevo_mcp_server/ The tools. Runs on your machine (stdio) or as a shared service (HTTP). Works with any MCP client.
Skill skills/hevo-pipelines/ Hevo know-how for the agent: safety rules, how to find out why a pipeline fails, how to create one. It uses the MCP server's tools; it never calls the API itself.
Plugins .claude-plugin/, .codex-plugin/ + .agents/plugins/ The server and the skill in one install for Claude Code and Codex.

The server stores no keys. It uses your own Hevo API key, so the agent can never do more than your Hevo role allows, and it is read-only unless you allow changes.

Contents: Before you start · Choose how to run it · 1. Plugin for your agent · 2. Run it yourself (stdio) · 3. Host it for your organization (HTTP) · Allowing changes · What the server reads and sends · Configuration reference · Tools · Troubleshooting · Development · License

Before you start

1. Create a Hevo API key. Sign in to Hevo, open Account → API Keys (https://<region>.hevodata.com/account/api-keys), click + New API Key, then Download. The secret is shown only once. Save the downloaded file as ~/.hevo/hevo-key.json (C:\Users\<you>\.hevo\hevo-key.json on Windows), readable only by you (Key file has the commands for macOS, Linux and Windows): the server finds it there by name. The key works in the region of your Hevo account, which your agent asks you for once and passes on every call. If you can't see the API Keys page, ask a Team Administrator in your Hevo account.

The key acts with the permissions of the Hevo user who created it. Never paste the key or secret into a chat with your agent.

2. Know your region: the subdomain you sign in at (us.hevodata.com is us). The agent asks for it and names it on every call; nothing is configured. It can work in every other region too, with the same key: one API key covers all of Hevo's production regions.

Region Hevo URL
us https://us.hevodata.com
us-gcp https://us-gcp.hevodata.com (Standard Pipelines only)
us2 https://us2.hevodata.com
eu https://eu.hevodata.com
eu2 https://eu2.hevodata.com (Edge Pipelines only)
in https://in.hevodata.com
asia https://asia.hevodata.com
au https://au.hevodata.com

3. Install uv for options 1 and 2. It runs the server and downloads Python 3.12 for it if needed. The plugins install the server from this repository; the other clients install the hevo-mcp package from PyPI.

Choose how to run it

Option Best for You get
1. Plugin for your agent Claude Code, Codex MCP server + hevo-pipelines skill, one install, updates with the plugin
2. Run it yourself (stdio) Any MCP client, full control MCP server on your machine with your key
3. Host it for your organization (HTTP) Teams One shared server; each person connects with their own key

In options 1 and 2 the server runs on your own machine, and your key and data go only from your machine to Hevo's API.

1. Plugin for your agent

Each plugin starts the MCP server for you and adds the hevo-pipelines skill. Setup is one file:

What Where Meaning
Key file ~/.hevo/hevo-key.json The key file downloaded from Hevo, as it is (Key file)
Region Told to the agent The agent asks which region your account is in (the subdomain you sign in at) and names it on every call; nothing to configure
HEVO_MCP_DEFAULT_SCOPE Optional variable write or delete to allow changes (Allowing changes)
HEVO_KEYS_DIR Optional variable Another folder than ~/.hevo for the key file and the secrets/ folder

After installing, start a new session and ask: "run hevo_whoami for region us" (your region). It reports the key file in use and whether Hevo accepts it.

Claude Code

Save the key file, then:

/plugin marketplace add hevoio/hevo-mcp
/plugin install hevo-data@hevo-data

The skill is /hevo-data:hevo-pipelines; Claude also uses it on its own when you ask about Hevo. /plugin marketplace update hevo-data picks up new releases.

Codex

Set the same variables in the shell you start Codex from, then:

codex plugin marketplace add hevoio/hevo-mcp

Then install hevo-data from the hevo-data marketplace: run /plugins in the Codex CLI, or open Plugins in the ChatGPT desktop app, and start a new session. Codex runs the server from the matching release on PyPI and passes it only the variables listed in the plugin. Use the skill as $hevo-pipelines, or just ask about Hevo. codex plugin marketplace upgrade hevo-data picks up new releases.

Other agents run the server from the package: see the next section.

2. Run it yourself (stdio)

The agent starts the server as a local process and talks to it over standard input and output. There is no port and no URL. The key comes from the server's environment. Every client below runs the same command, which installs the server from PyPI (hevo-mcp):

uvx hevo-mcp==1.0.0                     # the release, with its dependencies resolved today
uvx --from hevo-mcp==1.0.0 -c https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt hevo-mcp
                                        # the release exactly as tested: every dependency pinned

The second form is what the plugins use and what the examples below show: -c points at the release's constraints.txt (in this repository at the v<version> tag), so every dependency is the version CI tested. The first form installs the same server with the dependencies resolved at install time; use it where raw.githubusercontent.com isn't reachable (a proxy that blocks it). Either way, hevo_whoami reports dependencies: as_tested or lists what differs, so you can tell which you have. Use another version for another release (in both places: hevo-mcp==<version> and the v<version> tag). From a local clone or a downloaded wheel, pin with the constraints.txt next to it: uvx --from /path/to/clone -c /path/to/clone/constraints.txt hevo-mcp.

Claude Code

claude mcp add -s user hevo \
  -- uvx --from hevo-mcp==1.0.0 -c https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt hevo-mcp

-s user makes it available in every folder; without it, only in the current project.

Codex (~/.codex/config.toml)

[mcp_servers.hevo]
command = "uvx"
args = ["--from", "hevo-mcp==1.0.0",
        "-c", "https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt", "hevo-mcp"]

Claude Desktop, Cursor, Windsurf and most other clients (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.gemini/settings.json, …)

{
  "mcpServers": {
    "hevo": {
      "command": "uvx",
      "args": ["--from", "hevo-mcp==1.0.0",
               "-c", "https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt", "hevo-mcp"]
    }
  }
}

VS Code (Command Palette → MCP: Open User Configuration, or .vscode/mcp.json for one project): the same entry under "servers" instead of "mcpServers", with "type": "stdio" added.

Claude Desktop doesn't use your shell's PATH: give the full path to uvx (which uvx). Restart the client after editing its config. To use the skill in a client without plugin support, point the agent at skills/hevo-pipelines/SKILL.md (for example as a Cursor rule or in your instructions file).

Regions. There is no default region. Every tool takes a region argument (us, us-gcp, us2, eu, eu2, in, asia, au: the subdomain you sign in at), the agent asks you once if it doesn't know it, and one server covers them all, so you can say "list my pipelines in eu". hevo_whoami without a region reports the setup; with one (region="eu") it checks the key there. Two regions carry one product: eu2 has Edge Pipelines only and us-gcp has Standard Pipelines only, so a Standard call in eu2 or an Edge call in us-gcp returns REGION_UNSUPPORTED instead of reaching Hevo. Team users and OAuth accounts answer in every region.

Key file

The key is one file, ~/.hevo/hevo-key.json (or hevo-key.json in HEVO_KEYS_DIR): the JSON you download from Settings → API Keys in Hevo, saved as it is. The key works in the region of your Hevo account, which the agent passes on every call. On macOS and Linux the server refuses a key file other users on the machine can read:

mkdir -p ~/.hevo && chmod 700 ~/.hevo
mv ~/Downloads/hevo-key.json ~/.hevo/hevo-key.json && chmod 600 ~/.hevo/hevo-key.json

On Windows ~ is your user profile folder, so the key file is C:\Users\<you>\.hevo\hevo-key.json (HEVO_KEYS_DIR takes a Windows path too, e.g. D:\keys\hevo). Windows has no chmod, and the server doesn't check who can read the file there, so restrict it yourself. In PowerShell:

New-Item -ItemType Directory -Force "$HOME\.hevo" | Out-Null
icacls "$HOME\.hevo" /inheritance:r /grant:r "${env:USERNAME}:(OI)(CI)F"
Move-Item "$HOME\Downloads\hevo-key.json" "$HOME\.hevo\hevo-key.json"
icacls "$HOME\.hevo\hevo-key.json" /inheritance:r /grant:r "${env:USERNAME}:F"

The first icacls leaves only you on the folder, so files created in it later (such as secrets\) are yours alone; the second does the same for the key file, which keeps the access list of the folder it was moved from. Run icacls "$HOME\.hevo\hevo-key.json" to check: it should list only your account. File Explorer won't name a folder .hevo directly; use PowerShell as above.

There is no way to pass the key as a variable: client config files are often synced or shared.

Keep the agent itself away from the key. The server never shows the key to the agent, but an agent with its own file tools could still open the key file. In Claude Code, deny that in ~/.claude/settings.json:

{ "permissions": { "deny": ["Read(~/.hevo/**)", "Bash(cat ~/.hevo/*)"] } }

Other agents have similar settings (allowed folders, or approval before reading files).

3. Host it for your organization (HTTP)

One server for many people. Nobody's key is stored on it: each person sends their own key with every request, so every call runs with exactly that person's Hevo permissions.

This mode is for self-hosting inside your own network and for testing. The bearer token is the person's Hevo API key, forwarded to Hevo: it is not an OAuth-protected MCP server in the sense of the MCP authorization spec (no RFC 9728 resource metadata, no token audience check), so don't expose it on the internet, and don't connect agents to it from outside your network. The scope comes from a header the client sends (X-Hevo-Scope), so it limits what a well-behaved client asks for, not what a hostile one can do with the key it already holds. Hevo's own hosted MCP (coming separately) uses OAuth sign-in with consent-derived scopes instead.

Run the server

# from a clone of this repository
uv sync
HEVO_MCP_ALLOWED_REGIONS=us \
  uv run hevo-mcp --transport http --host 0.0.0.0 --port 8000

# or straight from PyPI
HEVO_MCP_ALLOWED_REGIONS=us uvx --from hevo-mcp==1.0.0 -c https://raw.githubusercontent.com/hevoio/hevo-mcp/v1.0.0/constraints.txt hevo-mcp --transport http --host 0.0.0.0 --port 8000

Run it under your usual process manager (systemd, a container platform, …) as a non-root user, behind a load balancer that terminates TLS. Settings come from a config file, and the deployment-specific ones from environment variables (Configuration reference).

The MCP endpoint is <public URL>/mcp. GET /health-check answers without a key and without calling Hevo: {"status": "ok", "version": …, "endpoints": …, "regions": …}.

Server options (command line, or the environment variable):

Option Env var Default Meaning
--transport HEVO_MCP_TRANSPORT stdio http for a shared server
--host HEVO_MCP_HOST 127.0.0.1 Interface to listen on; 0.0.0.0 in a container
--port HEVO_MCP_PORT 8000 Port
--path /mcp MCP endpoint path
--config HEVO_MCP_CONFIG none Settings file (TOML), see config/hevo_mcp.toml
--allowed-hosts HEVO_MCP_ALLOWED_HOSTS none Comma-separated Host values to accept (others get 421)
--allowed-origins HEVO_MCP_ALLOWED_ORIGINS none Browser origins allowed to call (others get 403)
HEVO_MCP_PUBLIC_URL http://<host>:<port> Public base URL as people reach it
HEVO_MCP_ALLOWED_REGIONS any Regions this server serves, e.g. eu,eu2; others are refused

An HTTP server never reads a key file: every caller sends their own key in the Authorization header.

Connect a client

Each person needs the server URL and three headers:

Header Value
Authorization Bearer <base64 of api_key:api_secret>
X-Hevo-Region Their region, e.g. us (a call's region argument can name another one the server serves)
X-Hevo-Scope Optional. Omitted: read-only. write allows changes, delete also allows deletes

Build the token once (it is the key, so treat it as a secret):

# macOS / Linux
export HEVO_MCP_TOKEN=$(printf '%s:%s' "$KEY" "$SECRET" | base64 | tr -d '\n')   # KEY and SECRET from the key file
# Windows PowerShell
$env:HEVO_MCP_TOKEN = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("$KEY`:$SECRET"))

Claude Code

claude mcp add --transport http hevo https://mcp.example.com/mcp \
  --header "Authorization: Bearer $HEVO_MCP_TOKEN" --header "X-Hevo-Region: us"
# add --header "X-Hevo-Scope: write" to allow changes

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "hevo": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:HEVO_MCP_TOKEN}", "X-Hevo-Region": "us" }
    }
  }
}

VS Code (.vscode/mcp.json; prompts for the token once and stores it securely)

{
  "inputs": [{ "id": "hevo-token", "type": "promptString", "description": "Hevo MCP token", "password": true }],
  "servers": {
    "hevo": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:hevo-token}", "X-Hevo-Region": "us" }
    }
  }
}

Claude Desktop can't send custom headers to a remote server; bridge with mcp-remote:

{
  "mcpServers": {
    "hevo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.example.com/mcp",
               "--header", "Authorization:Bearer ${HEVO_MCP_TOKEN}", "--header", "X-Hevo-Region:us"],
      "env": { "HEVO_MCP_TOKEN": "<token>" }
    }
  }
}

Production checklist

  • TLS in front. The bearer token is a Hevo key: terminate HTTPS at your load balancer or ingress.

  • Pin regions. Set HEVO_MCP_ALLOWED_REGIONS to the regions this server serves, so a request for another region is refused instead of crossing regions. For data residency, run one server per region. The server warns regions_not_pinned at startup when it's unset.

  • Set HEVO_MCP_ALLOWED_HOSTS to the public hostname (DNS-rebinding protection; include the host your load balancer's health check uses).

  • Take data-losing endpoints out of reach if agents shouldn't resync or delete anything, even with approval: add them to [access] disabled_endpoints in the config file (an example is in config/hevo_mcp.toml). The server warns risky_endpoints_reachable at startup while a default scope above read leaves any of them callable.

  • Keep it off the open internet. Make the server reachable only from your network or VPN, or behind an IP allow-list at the load balancer. It refuses keys Hevo rejected and limits keys it hasn't seen accepted ([rate_limits] unverified_per_minute), but anyone who can reach it can make it call Hevo.

  • Several replicas need no sticky sessions: the server is stateless. Give them one shared HEVO_MCP_APPROVAL_KEY (a random secret of 32 or more characters; comma-separate keys to rotate, the first seals), so the answer to an approval prompt can reach any replica. Each replica remembers on its own which approvals it has used, so an approved answer could be replayed once on each other replica within its 10 minutes, by a client that already holds it and only for that exact call. A shared record of used approvals is on the list for the hosted server.

  • Timeouts: load balancer idle timeout at least 450 s (an Edge pipeline create can take minutes); give the orchestrator a stop grace period longer than HEVO_MCP_SHUTDOWN_GRACE (450 s).

  • Logs are JSON lines on standard error, the audit records among them. Optionally ship them to Coralogix (CORALOGIX_* below). Logs never contain keys, request bodies or results.

  • After each deploy, check it with a test key (read-only, nothing is written):

    HEVO_MCP_TOKEN=<base64 key:secret> uv run python scripts/smoke_check.py https://mcp.example.com/mcp --region us
    

Allowing changes

The server is read-only by default. A call that would change something returns READ_ONLY with a hint, and nothing reaches Hevo.

Scope The agent can Set with (local, options 1 and 2) Set with (HTTP, per connection)
read (default) List and inspect
write Also create, update, pause, resume, run, resync HEVO_MCP_DEFAULT_SCOPE=write X-Hevo-Scope: write
delete Also delete pipelines and Destinations HEVO_MCP_DEFAULT_SCOPE=delete X-Hevo-Scope: delete

Your Hevo role still applies on top: a scope only limits, it never grants.

Approval

Within the scope, some calls also need your approval, every time. The server shows the change in your MCP client and sends nothing to Hevo until you approve. The model can't answer the prompt: the answer comes from your MCP client's own UI, so use a client you trust. No scope, setting or tool argument skips it.

Every prompt has the same shape. The first line names the change, the resource and the region (Claude Code shows only that line until you open the prompt), then one line says what happens, then who may approve. The exact request follows under "Technical details": method, path and endpoint, the query, the fields that say where a Source or Destination connects (host, account, URL) on their own line in full, and the body, never with a secret value (passwords are references or [redacted]). When the request uses a secret file, the last line says which file goes into which field and to which host, so you can check the host is yours.

Delete Edge Pipeline 352 in the us region?

Deletes this Pipeline. The tables in the Destination are not deleted. This action cannot be undone.

Approve only if you asked your agent for this change. Your agent cannot approve it for you.

Technical details: DELETE /api/v2/pipelines/352 (delete_pipeline)
Needs approval Doesn't
Every delete Creating a pipeline, Destination or Model, unless the body carries a secret reference; setting a Standard pipeline's or Model's status to ACTIVE
Configuration changes: Destination, Source, pipeline settings, objects, mappings, transformations, Models Reads
Destructive actions: cancel a job, disable or pause, skip, resync, restart, reset, move a position
Runs that ingest or load data, which count toward your Events quota: sync now, run now, load now
Enabling an Edge pipeline or resuming an object; inviting users, changing roles, removing users or OAuth accounts
Any request whose body carries a secret reference ($secret_file:<name>), whatever the endpoint

list_endpoints and get_schema show needs_approval for each endpoint, and the full list is in endpoint_overrides.json (writes need approval unless marked never).

Bulk actions get one prompt. "Pause these 40 objects" is one call with batch (a list of targets, one path_params each; body and query shared, at most 100 per call, or the writes-per-minute limit on a shared HTTP server, 20 by default): you see one prompt listing every target, approve once, and the server makes one request per target and reports each result. The first line of the prompt gives the count ("Disable Edge Pipeline (40 targets) in the us region?") and a "Targets" list names every one. The approval covers exactly that set of targets and nothing else.

The prompt uses MCP elicitation, so the client must support it (Claude Code does). MCP 2026-07-28 clients get it on every transport, including a shared stateless HTTP server. Older clients get it over stdio; over HTTP they can't receive it, so those calls return APPROVAL_UNAVAILABLE. In the prompt, Accept makes the change; Decline, dismissing it, or picking Reject and accepting stops it, and the call returns APPROVAL_DECLINED; if nobody answers within 10 minutes, APPROVAL_TIMEOUT. In each case nothing reaches Hevo. Claude Code in print mode, which includes its VS Code extension, declines prompts without showing them: make changes from an interactive claude session. Every decision is logged with the call (approval in the tool_call and audit records).

Passwords for new Sources and Destinations

Creating a Source or Destination needs its real password, token or key: Hevo tests the connection before it saves anything. Don't type it into the chat. Save it as a file in ~/.hevo/secrets/ (readable only by you) and tell the agent the file's name; the agent writes "password": "$secret_file:<name>" in the request, and the server swaps in the file's contents just before calling Hevo. The conversation, the approval prompt and the logs only ever see the reference, and nothing is stored.

The file holds the plain value, nothing else: no quotes, no password= prefix, no JSON wrapper. A password is one line; a service-account JSON or a PEM private key is saved as is, over several lines. Whitespace before and after the value (the final newline an editor adds, a pasted space) is ignored.

mkdir -p ~/.hevo/secrets && chmod 700 ~/.hevo/secrets
read -rs PW && printf '%s' "$PW" > ~/.hevo/secrets/mysql-prod && chmod 600 ~/.hevo/secrets/mysql-prod

On Windows (PowerShell), after restricting .hevo as in Key file, so the new folder and file are yours alone:

New-Item -ItemType Directory -Force "$HOME\.hevo\secrets" | Out-Null
$pw = Read-Host -AsSecureString "Value"
[IO.File]::WriteAllText("$HOME\.hevo\secrets\mysql-prod", [Net.NetworkCredential]::new('', $pw).Password)
Remove-Variable pw

WriteAllText saves plain UTF-8 with no byte-order mark; Set-Content and > in Windows PowerShell 5.1 add a byte-order mark, which would become part of the value, or write UTF-16, which the server can't read.

Names are bare file names, never paths, and only this folder is read: a request can never pick up your other credentials (cloud keys, tokens, variables). The folder is secrets/ next to the key file, so with HEVO_KEYS_DIR set it moves along (hevo_whoami shows it as secrets_dir).

Three rules keep a reference from leaking a secret:

  • A reference is accepted only in a field that holds a secret (password, *_token, client_secret, api_key, ...): where Hevo stores it as a secret and where results come back [redacted]. In any other field (a host, a name) the call is refused, so the value can't be echoed back or sent to a host.
  • Every request that carries a reference asks for your approval, even a create, which otherwise doesn't. The prompt shows the reference and the whole request, so you see which secret goes to which host before Hevo's connection test sends it. A prompt-injected "create a Destination at attacker.example" can't send your password unseen.
  • The value is read when the call is made and is never stored, logged or shown in an error.

A reference that can't be read (missing or empty file, one other users can read, a variable without the prefix) returns SECRET_UNAVAILABLE with the reason, and nothing is sent to Hevo. References work on a local server (plugin or package); a shared HTTP server can't read your files, so there they also return SECRET_UNAVAILABLE.

What the server reads and where it sends data

A local server (the plugins, and uvx hevo-mcp) reads these and nothing else:

  • The key file, ~/.hevo/hevo-key.json or $HEVO_KEYS_DIR/hevo-key.json, for your Hevo API key.
  • Secret files in the secrets/ folder next to it, and only the one file a request names with $secret_file:<name>, only after you approved that request.
  • The config file, if you pass one (--config or HEVO_MCP_CONFIG), and the variables listed in the configuration reference.

It writes nothing to disk: no cache, no history, no log file. Logs go to standard error, where your MCP client shows them, with keys and secrets redacted.

It sends data to exactly two places:

  • Hevo's API in the region you name, over HTTPS: asia, au, eu, eu2, in, us, us-gcp or us2.hevodata.com, under /api/v2/ (Edge) and /api/public/v2.0/ (Standard pipelines, team users and OAuth accounts). Every request carries your key, and only what the tool call needs. The server knows only these hosts and can't be pointed at another. It never calls an endpoint that returns pipeline records, so your pipeline data stays in your Hevo region. What Hevo returns goes to your agent and so to its model provider: pipeline and object names, configuration with secrets redacted, and, from the account endpoints, your team members' names and email addresses.
  • PyPI, for the update notice in hevo_whoami: one anonymous GET of https://pypi.org/pypi/hevo-mcp/json, at most once a day, never with your key or any other data. Off with [updates] enabled = false in the config file.

There is no telemetry, no analytics and no crash reporting. A shared HTTP server (section 3) reads no key file and no secret files; it can additionally ship its logs to Coralogix if its operator configures that.

What the agent sees

  • Secrets are redacted. In every result, a value under a key that names a secret (password, secret_key, private_key, client_secret, *_token, ...) comes back as [redacted].
  • Hidden text is removed. Terminal escape sequences, control characters and invisible or direction-changing Unicode are stripped from every string Hevo returns, so nothing in a pipeline name or error message can hide instructions from you or rewrite your terminal.
  • Hevo's data is marked as untrusted. The server tells the agent never to follow instructions found in it.
  • Tool descriptions are screened. They come from Hevo's published API specs; the build fails if the text has hidden characters, instruction-like phrases or links outside known hosts.
  • The tool set is fingerprinted. hevo_whoami and /health-check show tools_sha256, a hash of every tool's name, description and schema, and the server logs it at start (tool_catalog). It stays the same for a given release and configuration, so a change means the tools were altered: alert on it, or pin it in clients that support pinning.

What these controls protect against

The scope, the approval prompts, the guards and the cleaning stop mistakes by the model and calls steered by text it read (a pipeline name or error message that says "delete everything"): nothing risky reaches Hevo through this server without you seeing it first. They are not a boundary against an agent that is hostile and has file access on the same machine. Such an agent could read ~/.hevo/hevo-key.json, call Hevo's API itself and skip this server entirely; the server can't prevent that, and neither can any local MCP server. So:

  • Create the API key from a Hevo user with the least role that does the job; the key can never do more.
  • Keep the agent out of the key and secrets folders (Key file shows the Claude Code deny rule), and prefer agents that ask before reading files or running commands.
  • The real boundary is a key Hevo itself limits (a read-only or scoped API key); until Hevo offers one, the role on the key is the limit.

Configuration reference

On your machine (stdio; options 1 and 2), everything a user can set:

Variable Meaning
HEVO_KEYS_DIR Folder with the key file hevo-key.json and the secrets/ folder (Key file, Passwords); default ~/.hevo
HEVO_MCP_DEFAULT_SCOPE read (default), write or delete (Allowing changes)
HEVO_MCP_LOG_LEVEL DEBUG or WARNING instead of INFO, when support asks for a verbose log

The region is not a setting: the agent asks you and names it on every call. The key is never read from a variable.

Settings. Every other setting has a built-in default and is changed in a TOML file (--config or HEVO_MCP_CONFIG); config/hevo_mcp.toml lists all of them with their defaults, and a typo or a bad value stops the server at startup with the key named. A plugin or package install needs none of them. The few that say which deployment a hosted server is also have an environment variable. Precedence: defaults < config file < environment variable < command-line option.

File key Environment variable Default Meaning
[access] default_scope HEVO_MCP_DEFAULT_SCOPE read Scope for stdio, and for HTTP connections without X-Hevo-Scope
[access] disabled_endpoints none Endpoint or tool-group names to hide and refuse
[access] allowed_regions HEVO_MCP_ALLOWED_REGIONS any Regions an HTTP server serves; others are refused
[rate_limits] unverified_per_minute 60 Calls per minute, per replica and per client address, for API keys Hevo hasn't accepted yet. A key Hevo rejects is then refused for a minute without asking Hevo again. Stops floods of made-up keys without letting one source lock everyone out; 0 disables
[rate_limits] reads_per_minute 60 HTTP only: read calls per minute per caller, per replica; 0 disables. A local (stdio) server has one caller and no limit
[rate_limits] writes_per_minute 20 HTTP only: write and delete calls per minute per caller, per replica
[timeouts] connect_seconds 15 Connecting to Hevo
[timeouts] read_seconds 60 One Hevo read request
[timeouts] write_seconds 420 One Hevo write (a pipeline create tests both connections)
[timeouts] read_deadline_seconds 90 A whole read tool call, retries and fetch_all pages included
[progress] interval_seconds 10 Progress notifications while waiting on Hevo; 0 turns them off
[limits] max_rows 5000 fetch_all stops here and returns truncated with next_cursor
[limits] max_pages 200 Page cap for fetch_all
[limits] max_result_bytes 1000000 Larger results come back as RESULT_TOO_LARGE
[http] max_body_bytes HEVO_MCP_MAX_BODY_BYTES 1000000 Larger HTTP request bodies get 413
[http] allowed_hosts HEVO_MCP_ALLOWED_HOSTS none Host header values to accept
[http] allowed_origins HEVO_MCP_ALLOWED_ORIGINS none Browser origins allowed to call
[http] shutdown_grace_seconds HEVO_MCP_SHUTDOWN_GRACE 450 Wait for in-flight calls on SIGTERM
[hevo_pool] max_connections 100 Outbound connections to Hevo per replica
[hevo_pool] max_keepalive_connections 20 Idle connections kept open
[updates] enabled true hevo_whoami says when a newer release exists. One anonymous request to PyPI, at most once a day, never with your key
[updates] url PyPI's hevo-mcp page (JSON) Where releases are listed

Hosted server only (environment):

Variable Meaning
HEVO_MCP_TRANSPORT, HEVO_MCP_HOST, HEVO_MCP_PORT, HEVO_MCP_PUBLIC_URL, HEVO_MCP_CONFIG How and where the server runs (Run the server)
HEVO_MCP_APPROVAL_KEY Shared key that seals approval prompts, for several replicas of an HTTP server; each process makes its own when unset
CORALOGIX_PRIVATE_KEY Ship logs to your Coralogix account. With CORALOGIX_DOMAIN (default coralogix.com) or CORALOGIX_LOGS_URL, CORALOGIX_APPLICATION, CORALOGIX_SUBSYSTEM

No key or secret is stored in this repository. Everything sensitive comes from your environment, a file path you choose, or (HTTP) each request's headers.

Tools

  • One tool per product, resource and kind, for example pipelines_read, pipelines_write, pipelines_destructive, destinations_delete, metadata_read (Edge), standard_pipelines_read, standard_models_write (Standard) and accounts_write (shared). Each takes name (the endpoint), path_params, query, body, and on paginated lists fetch_all. 86 endpoints in 22 tools: 28 from the Edge API v2, 49 Standard pipeline, object, event-type, mapping, transformation, Destination, Model and Workflow endpoints from the Public API v2.0, and its 9 account endpoints (team users and OAuth accounts, which both products share). Writes that lose or re-ingest data (resync, cancel a job, restart an object, move a position) are in the *_destructive tools, not the *_write ones, so a client-side "always allow" on a write tool never covers them and each tool's destructiveHint is accurate.
  • Bodies are checked before anything else sees them. A request body is validated against the endpoint's schema (required keys, types, enums); a bad one returns INVALID_BODY with the problems, and you are never asked to approve a request Hevo would reject.
  • list_endpoints and get_schema to discover endpoints, their parameters and their consequences (get_schema adds the response schema only with include_response: true).
  • hevo_whoami to check the connection.
  • Left out on purpose: any endpoint that returns pipeline records (the two Standard transformation-sample endpoints). The server returns only configuration and metadata, so pipeline data stays in the customer's region wherever the server runs. This is a data-protection decision (GDPR data residency): Hevo promises customers that their pipeline data never leaves the region they choose. Every endpoint in endpoint_overrides.json is classified (records: true means excluded) and the build fails for an unclassified one, so a spec sync can't ship one unreviewed. Don't add such an endpoint without a data-residency review.

Resources: hevo://regions (regions and their API hosts) and the hevo-pipelines skill, skill://hevo-pipelines/SKILL.md with its manifest skill://hevo-pipelines/_manifest. The skill is the same file the plugins install, shipped inside the package, so a client connected only by URL (a hosted server) can load or attach it. Its key rules (approval before every change, how to diagnose a failing pipeline) are also in the instructions the server sends every client.

Errors come back as {"error": CODE, "message": ..., "hint": ...} with a request_id that also appears in the server's log.

Troubleshooting

Message What to do
No Hevo API key file at ... Save the downloaded key as ~/.hevo/hevo-key.json (Key file); the message names the exact path it looked at
No region given / Send the X-Hevo-Region header Tell the agent your region (the subdomain you sign in at); over HTTP, send the header
UPSTREAM_UNAUTHORIZED Wrong Access Key or Secret Key, a deleted key, or a key from another region
UPSTREAM_FORBIDDEN The Hevo role of the user who created the key doesn't allow this action
REGION_UNSUPPORTED That region doesn't carry this product: eu2 has Edge Pipelines only, us-gcp Standard Pipelines only. Name the region that holds them
RESULT_TOO_LARGE One answer is over 1 MB: page with limit and the cursor. fetch_all stops under the cap on its own and hands back the rows so far with the next cursor
INVALID_ARGUMENTS with a query or body problem The query named a parameter the endpoint doesn't have (a misspelt filter would otherwise return everything), or a body was sent to an endpoint that takes none
READ_ONLY Allow changes (Allowing changes)
APPROVAL_UNAVAILABLE Your MCP client can't show approval prompts; use one that supports elicitation (Approval)
This Hevo MCP endpoint serves region … You connected to a server for another region
HTTP 401 when connecting Missing or malformed Authorization: Bearer <base64 key:secret> header
HTTP 421 The Host header isn't in HEVO_MCP_ALLOWED_HOSTS
The client shows no Hevo tools Check uv is installed and on the client's PATH (Claude Desktop: use the full path), then restart the client

The server writes its logs to standard error, which MCP clients show in their MCP logs.

Development

See CONTRIBUTING.md for the layout, branch names and how a pull request is merged.

uv sync                                  # install with dev dependencies
uv run pytest                            # tests (a mocked Hevo API; no key needed)
uvx ruff check .                         # lint
uv build                                 # wheel and source package in dist/
  • The tools are generated from Hevo's OpenAPI specs. python build_manifest.py --fetch pulls the current specs from Hevo's API docs into openapi/, python build_manifest.py rebuilds src/hevo_mcp_server/manifest/, and endpoint_overrides.json adds what a spec can't say (a consequence, destructive, a better name). CI fails if the committed manifest doesn't match the specs.
  • The skill lives here. skills/hevo-pipelines/SKILL.md is the source of truth; it uses the MCP tools only, never Hevo's API directly. A test fails if it names an endpoint or tool that doesn't exist.
  • Live checks (scripts/smoke_check.py, read-only) run a running server's tools against Hevo with a production key in HEVO_MCP_TOKEN, in one of Hevo's public regions. Run by hand after a deploy; CI never calls Hevo.
  • This repository's CI needs no secrets. Hevo maintainers bring the catalog up to date with the published API specs and open pull requests here for review.
  • scripts/package_check.py installs a built wheel and runs it over stdio as a customer would.
  • Plugins. One server and one skill folder feed both plugin manifests (Claude Code, Codex). tests/test_plugin_manifests.py fails if their version, server command or settings drift apart; claude plugin validate . checks the Claude manifest.
  • Dependencies. constraints.txt pins every dependency at its uv.lock version; the plugins and the documented uvx commands install with it, and a copy ships inside the package so hevo_whoami can report whether an install matches it. After changing dependencies (uv lock), run uv run python scripts/set_version.py --constraints; a test fails while it's stale.
  • Releasing. uv run python scripts/set_version.py <version> sets the new version in pyproject.toml, every plugin manifest and every install-from-tag reference, and updates uv.lock and constraints.txt (--check only reports). Commit, merge, then tag the merged commit v<version> and push the tag: the plugins install from that tag, and Codex and the stdio instructions install that version from PyPI, and hevo_whoami tells older installs a newer version is available. Every release needs a new version: uv caches the server by version. Pushing the tag runs .github/workflows/release.yml: it builds the wheel and the source package, signs where they came from (GitHub artifact attestations), publishes them with SHA256SUMS as a GitHub release, and then, after an approval in the pypi environment, uploads the package to PyPI with trusted publishing (no token stored). A version on PyPI can never be replaced.

License

MIT License. See LICENSE and NOTICE. The license covers this code; it doesn't grant use of the Hevo name or logo beyond describing where the software comes from.

Metadata

Release files for hevo-mcp 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hevo-mcp 1.0.0
File Size Uploaded Provenance Actions
hevo_mcp-1.0.0.tar.gz 378.8 kB With provenance Details for hevo_mcp-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hevo-mcp 1.0.0
File Interpreter ABI Platform Actions
hevo_mcp-1.0.0-py3-none-any.whl Python 3 none any Details for hevo_mcp-1.0.0-py3-none-any.whl

Total release size: 668.5 kB

Release files / hevo_mcp-1.0.0.tar.gz

Download URL hevo_mcp-1.0.0.tar.gz
Size 378.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7e3cfdd494ce2b5f0341b172dc065aa08e591c32df6a2d18a78f29d1fa3c855b
BLAKE2b-256 checksum
How to use checksums
e4f52bbc7b75100474f3659a0044fce7efe497ff6231a096103932505bd4744f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / hevo_mcp-1.0.0-py3-none-any.whl

Download URL hevo_mcp-1.0.0-py3-none-any.whl
Size 289.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
919685ea8be7d19a975a756c58d142370b89065912610584f578c76d95fd9ac9
BLAKE2b-256 checksum
How to use checksums
54e87ab2912bf080b2142ac51fe6ca6428519c808d662b3f4874b81cc45ddc52
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for hevo-mcp 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hevo_mcp-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page