Enforce AtmanID decisions in your own API gateway (Envoy, Kong)
The AtmanID MCP gateway sits between your agents and your MCP servers. If you already run Envoy, Kong or another API gateway there, you don’t need a second proxy: your gateway asks AtmanID for the decision on each tool call and enforces it. The decision is the one the AtmanID gateway makes — agent token and DPoP proof, server governance, tool scope, rate limits, payload inspection, Intent policy and approval holds — and every decision is recorded in MCP Gateway → Events, marked “via” your gateway.
Before you start
- Mint an API key on the API Keys page with the scope Authorize MCP Calls (
mcp:authorize). Only someone who can manage MCP servers can create it, and the key answers only for agents of your own tenant. - Register the MCP server in AtmanID as usual. Its ID is what your gateway sends as the server. Its gateway mode applies: under Shadow every call is allowed and the would-be refusal is reported (
would_deny); under Enforce (or Direct) the decision is enforced. - Your agents get their tokens from AtmanID exactly as for the AtmanID gateway (token flow).
The decision API
POST /api/v1/mcp/authorize, with Authorization: Bearer <your API key>:
{ "ver": 1, "server_id": "mcp-github", "tool": "create_pull_request", "arguments": { "repo": "acme/web", "title": "Fix login" }, "agent_credential": { "authorization": "DPoP eyJ…", "dpop": "eyJ…", "htm": "POST", "htu": "https://gw.example.com/mcp/mcp-github/tools/create_pull_request", "workload": "eyJ…" }, "caller": { "gateway": "kong-prod-eu" }}agent_credential is what the agent sent you: its Authorization and DPoP headers, and the method and full URL of its request — the DPoP proof is bound to those. workload is its Workload-Identity-Token header, the signed identity of the workload it runs on, or null (or an empty string) when it sent none; AtmanID checks it against the workloads the agent is registered to run as. That check refuses nothing yet: its result is recorded on the decision in MCP Gateway → Events, not returned in this answer. Leave the field out only if your gateway cannot forward that header: the call is then not checked for its workload. The answer is always HTTP 200:
{ "ver": 1, "decision": "allow", "decision_id": "6f1c…", "reason": null, "message": null, "mode": "enforce", "would_deny": null, "hold": null, "retry_after_seconds": null, "flags": [] }decision |
What your gateway does |
|---|---|
allow |
Forward the call. Under Shadow, would_deny says what would have refused it. |
deny |
Refuse it. reason is the code (for example INSUFFICIENT_SCOPE, INSPECTION_FLAGGED, INTENT_DENY); a rate refusal carries retry_after_seconds. |
hold |
Refuse it for now: a person must approve it. hold.poll tells you when. |
HTTP 503 means AtmanID could not decide. Refuse the call — never treat it as allowed.
Holds
A hold is answered at once. Poll GET /api/v1/mcp/authorize/holds/{id} (same API key): pending, then approved, rejected or expired. Once it is approved, send the same call to /api/v1/mcp/authorize again: it is allowed once, while the approval is valid. Changed arguments are a new call and are held again; an approval that was already used reads used.
Envoy
Use Envoy’s ext_authz filter in HTTP service mode with /api/v1/mcp/ext-authz as the path prefix. Envoy then sends each agent request’s method, path, Authorization header and body to AtmanID and lets it through only on HTTP 200. Every other answer is a 403 carrying x-atmanid-decision (deny, hold, unavailable or invalid).
Because Envoy forwards the agent’s own Authorization header, your API key travels in x-atmanid-api-key. The agent’s path must end in /{server_id}/tools/{tool}, or in /{server_id}/mcp for a standard MCP server (any prefix before it is fine), and x-atmanid-origin is your gateway’s public origin, so AtmanID can rebuild the URL the agent’s DPoP proof is bound to.
Standard MCP servers. When the path ends in /{server_id}/mcp, Envoy must send the body (with_request_body), and AtmanID reads it as an MCP message:
- A
tools/callis decided like any tool call: itsnameis the tool, itsargumentsthe arguments. initialize,ping,tools/listand notifications are allowed when the agent’s token is valid for the server.- Any other method (resources, prompts) is refused, with
x-atmanid-reason: MCP_METHOD_NOT_GOVERNED. The gateway governs tools only.
A tool list fetched through Envoy comes from the server itself, unfiltered. Calling a tool that changed since approval is still held. For a list that shows only approved tools, agents use the AtmanID gateway’s own endpoint (connect a client).
http_filters: - name: envoy.filters.http.ext_authz typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz failure_mode_allow: false # required: if AtmanID is unreachable, refuse with_request_body: max_request_bytes: 1048576 allow_partial_message: false # a cut body cannot be inspected allowed_headers: patterns: - exact: dpop # Authorization, method, path and host are always sent - exact: workload-identity-token # the agent's workload identity, for the workload check http_service: server_uri: uri: https://ATMANID_HOST cluster: atmanid timeout: 2s path_prefix: /api/v1/mcp/ext-authz authorization_request: headers_to_add: - key: x-atmanid-api-key value: "atman_…" # from your secret store - key: x-atmanid-origin value: https://gw.example.com - key: x-atmanid-gateway value: envoy-prod authorization_response: allowed_upstream_headers: patterns: - prefix: x-atmanid-decision allowed_client_headers: patterns: - prefix: x-atmanid- - exact: retry-after - name: envoy.filters.http.routerThe atmanid cluster is an ordinary TLS cluster for your AtmanID host (set sni to it). Envoy forwards the agent’s Host header with the check; if your AtmanID URL needs its own host name, override it in headers_to_add.
Kong
Kong calls the JSON API from a pre-function plugin in the access phase (the key and URL come from the environment; declare them with Kong’s nginx_main_env):
local http = require "resty.http"local cjson = require "cjson.safe"
return function() local path = kong.request.get_path() local server, tool = path:match("/([^/]+)/tools/([^/]+)$") if not server then return end
local args = cjson.decode(kong.request.get_raw_body() or "{}") or {} local workload = kong.request.get_header("workload-identity-token") if workload == nil or workload == "" then workload = cjson.null end local res = http.new():request_uri(os.getenv("ATMANID_URL") .. "/api/v1/mcp/authorize", { method = "POST", headers = { ["Authorization"] = "Bearer " .. os.getenv("ATMANID_API_KEY"), ["Content-Type"] = "application/json" }, body = cjson.encode({ ver = 1, server_id = server, tool = tool, arguments = args, agent_credential = { authorization = kong.request.get_header("authorization") or "", dpop = kong.request.get_header("dpop"), htm = kong.request.get_method(), htu = "https://gw.example.com" .. path, workload = workload, }, caller = { gateway = "kong-prod" }, }), })
-- Fail closed: no answer, a 503, or anything but "allow" refuses the call. local d = res and res.status == 200 and cjson.decode(res.body) if not d or d.decision ~= "allow" then return kong.response.exit(403, { decision = d and d.decision or "unavailable", reason = d and d.reason, hold = d and d.hold }) endendWhat you see in AtmanID
Every decision is a row in MCP Gateway → Events, with “via kong-prod” (your caller.gateway) under the decision; hover it for the decision_id your gateway received. Refusals, holds and approvals work exactly as for the AtmanID gateway — approvers see held calls on the same queue.
© AtmanID · Privacy