Deploying so nothing bypasses the gateway
The MCP gateway checks every call that passes through it: the agent’s token and DPoP proof, tool scope, rate limits, payload inspection, intent policy and approval holds. It cannot check a call that goes around it. An agent that knows your MCP server’s URL, and holds a key the server accepts, can call the server directly, and the gateway never sees that call.
Closing that path is a deployment task on the MCP server’s side, and it comes down to one rule:
Your MCP server accepts a call only when it carries a valid AtmanID agent token for its own audience.
AtmanID mints that token only for calls it has authorised, so a call without one did not come through the gateway.
1. Turn on the agent token for the server
In MCP Gateway → Settings → Upstream identity, set the server to Token exchange and give it an audience: a string that names this server, for example https://mcp.example.com/github. On every call it forwards, the gateway then sends a short-lived token that AtmanID signs for that audience only, in the x-atmanid-agent-token header. Telling your MCP server which agent is calling lists the claims.
Before you change the server, point a test server at the echo endpoint the dialog shows and call a tool through the gateway. You will see a real token and whether it verifies.
Once your server verifies the token (step 2), tick Require the token in the same dialog. The gateway then also sends the token as Authorization: Bearer <token>, and refuses the call itself if it cannot issue one, so a call never reaches your server without its credential. The row in MCP Gateway → Settings reads Token Exchange (Required).
2. Make the server require it
Change the MCP server, or a proxy directly in front of it, so that every tool call is refused (HTTP 401) unless all of these hold. Read the token from Authorization: Bearer once the server is set to require it, or from x-atmanid-agent-token, which carries the same token in both modes.
| Check | Refuse when |
|---|---|
| The token is present | it is missing |
Signature verifies against your tenant’s key set (…/token-exchange/<tenant id>/jwks) |
it does not, or the kid is unknown after you refresh the key set |
Header typ is atmanid-agent+jwt and ver is 1 |
anything else |
iss is your tenant’s issuer (the key set URL without /jwks) |
another issuer, including another AtmanID tenant |
aud is this server’s audience |
it names a different server |
exp is in the future |
it has expired (tokens live 5 minutes) |
The tool being called is listed in scope |
the agent is not granted that tool |
Use a maintained JWT library (for example jose in Node.js or PyJWT in Python) and pin the algorithm to ES256. Cache the key set by kid, and fetch it again when a token carries a kid you do not have. Keys rotate every 90 days, and the previous key stays published until every token it signed has expired.
The gateway reuses a token for the same agent and server across calls for up to its 5-minute life, so do not refuse a jti you have already seen. Use jti to tie your server’s log lines to AtmanID’s audit trail. Replay is limited by the short life and the audience: a token that leaks from this server’s logs is useless at any other server and stops working within five minutes. Keep the header out of your logs anyway.
Leave the tool listing readable. The check above is for tool calls: POST …/tools/<tool>, or a tools/call message for a standard MCP server. AtmanID reads each server’s tool list (GET …/tools, or initialize and tools/list) every hour without a token, to catch a tool whose name, description or schema changed after you approved it. If your server refuses that read, change detection stops for that server. The listing reveals what tools exist, but it can’t run one.
Log every refusal, including the reason. A request that arrives without a valid token is either a misconfiguration or an attempt to go around the gateway, and you want to see both.
3. Remove every other way in
The token check is worth nothing while the server still accepts something else.
- Retire the credentials agents could hold. Revoke any static API key, shared secret or personal token that the server accepted before. Agents don’t need one: the gateway authenticates them with their AtmanID token, and that token never reaches your server.
- Don’t treat network position as the control. AtmanID’s gateway reaches your server over the public internet, from outbound addresses AtmanID does not publish, so an IP allowlist can’t tell gateway traffic from other traffic. The token is the control. Keep the server’s own surface small: serve only the MCP endpoints over HTTPS, nothing else on that host.
- Keep the URL out of agents’ configuration. Agents call the server’s gateway endpoint —
https://<your AtmanID host>/v1/mcp/<server id>/mcpfor an MCP client (connect a client), or…/v1/mcp/<server id>/tools/<tool>— never the server itself. The server’s own URL belongs in the gateway settings only. - Know your DIRECT servers. The DIRECT gateway mode is a break-glass lever: the gateway answers with a redirect to the server and runs none of its checks. A server that requires the token refuses those redirected calls, because they carry no token. That is the safe outcome. To break glass on such a server, its owner has to relax the server’s own check, which is a deliberate act on their side and leaves a record there.
If you run your own API gateway
When Envoy, Kong or another gateway asks AtmanID for the decision, your gateway is the enforcement point, so the same rule applies to it. Your MCP servers must be reachable only through that gateway, by network policy or by a credential that only the gateway holds. The decision API does not hand out the agent token yet; it will carry one in a later version.
What happens when something fails
The gateway is in the call path. If it cannot decide, it does not let the call through.
| Failure | What the agent sees |
|---|---|
| AtmanID unreachable, or the agent’s token, DPoP proof or tenant cannot be checked | The call fails. There is no path to the server that skips the checks. |
| Intent policy returns an outcome the gateway does not recognise | Refused. An unknown outcome never counts as an allow. |
| A hold is not approved in time | Refused (INTENT_HITL_TIMEOUT), or allowed and reported under a shadow intent mode |
| The MCP server is unreachable, or its URL fails the outbound safety check | 502 UPSTREAM_UNAVAILABLE |
| AtmanID cannot issue the agent token, and Require the token is on | Refused by the gateway: 502 UPSTREAM_UNAVAILABLE, recorded as a denial. Nothing is sent to your server. |
| AtmanID cannot issue the agent token, and Require the token is off | The call is forwarded without the token, and the failure is logged. A server that checks for the token (step 2) refuses it. |
The last two rows are why both halves matter. Your server’s check (step 2) refuses anything that did not come through the gateway, and Require the token makes the gateway refuse rather than send a call without its credential. With both on, a failure on either side ends in a refusal, never an unauthenticated call.
If you put AtmanID’s decision API behind your own gateway, configure that gateway to fail closed too. The Envoy and Kong examples do: Envoy with failure_mode_allow: false, Kong by refusing anything but allow.
Local (stdio) servers
Many MCP servers run as a local process that a desktop or IDE client starts from its config file and talks to over stdin and stdout. That traffic never crosses a network, so the gateway does not see it and cannot govern it today.
- Host anything that doesn’t need local files. Run the server over HTTP — the standard MCP protocol (Streamable HTTP) or AtmanID’s tool API — register it in AtmanID with that protocol, and require the token as above. Most servers that talk to a SaaS API (GitHub, Jira, Slack, a database) can move this way, and vendors’ hosted servers can sit behind the gateway as they are (hosted servers).
- Treat what stays local as ungoverned. A filesystem or shell server has to run on the machine it works on. Give it the narrowest access the operating system allows (a single directory, a user without admin rights). Don’t give it credentials for systems you govern through the gateway: an agent that can reach a system both ways will use the way with no checks.
- Coming: a local wrapper that the client config starts in place of the server. It asks AtmanID’s decision API before each tool call, so local servers get the same policy and audit trail as the gateway, failing closed for servers you mark sensitive. Until then, local servers are outside what AtmanID enforces.
Record which local servers are in use
AtmanID cannot govern a local server, but it can keep a list of where each one is configured. POST $ATMANID_BASE_URL/api/v1/mcp/local-servers/report takes what a scan of one device found: every MCP server that the device’s client config files declare. It is meant to be called by atmanid-mcp-scan, a scanner in AtmanID’s @atmanid/mcp-stdio package, which reads the config files of Claude Desktop, Claude Code, Cursor, VS Code and Windsurf and sends this report. The package is not yet published to npm, so for now the report can also be sent by your own tooling.
Call it with an API key that has the mcp:report scope. The key’s creator must be allowed to manage MCP servers (an agent engineer or a super admin), and that is checked each time the key is used.
curl -s -X POST "$ATMANID_BASE_URL/api/v1/mcp/local-servers/report" \ -H "Authorization: Bearer $ATMANID_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "schema_version": 1, "device": { "name": "ada-macbook", "platform": "darwin" }, "servers": [{ "client": "claude-desktop", "config_path": "~/Library/Application Support/Claude/claude_desktop_config.json", "name": "files", "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/ada/docs"], "env_keys": [], "wrapped": false, "fingerprint": "v1:f303341cca83f42a201a482a22e274500d615ed86d0afe279fdb9d57fca6447f" }] }'What AtmanID records:
- One MCP server per distinct server. Servers are told apart by a fingerprint: SHA-256 over the command’s file name and its arguments for a local server, or over the URL for an
httpone. AtmanID recomputes it and ignores an entry whose reported fingerprint differs. A new server is created with governance status discovered, scope local, owner Unassigned and risk Medium, and audited asMCP_LOCAL_SERVER_DISCOVERED. A server already known has its last-seen time refreshed. - One sighting per device, client and config file, with the device name, the operating-system user if sent, whether the config starts the AtmanID wrapper in front of the server (
wrapped), the API key that reported it, and when it was first and last seen. - No secrets. The report carries the names of environment variables, never their values, and AtmanID masks argument values that look like credentials before storing them, whatever the sender did. The URL of an
httpserver is stored as sent, because an approved server is proxied to it, and masked wherever it is shown. A field the schema does not name is refused.
The response counts what the report did: servers_new, servers_seen, sightings, unwrapped (local servers seen without the wrapper) and mismatched (entries ignored for a wrong fingerprint). A report holds at most 200 servers. Set name_prefix to "[Test] " while trying it out, so every server it creates is easy to find and remove.
The report does not change what is enforced. A discovered server is not granted to any agent; it is approved through the same flow as any other server. Calls that an agent makes to a local server still never pass through the gateway, so the limitation above stands. What the report adds is the inventory the checklist below asks for: which local servers exist, on which devices, and which of them run without the wrapper.
Checklist
- Every server registered in AtmanID is set to Token exchange, with its own audience
- Every server refuses a tool call without a valid token for its audience, and logs the refusal (the tool listing stays readable)
- Require the token is on for every server that verifies it
- Static keys that agents could have held are revoked
- Agents’ configuration names only gateway URLs
- No server is in DIRECT mode unless that is a deliberate, current exception
- Your own API gateway, if you use one, fails closed and is the only route to its servers
- Local stdio servers are listed, and anything that can be hosted has moved behind the gateway
© AtmanID · Privacy