MCP Gateway — enforcement modes, rate limits, and DLP inspection
MCP Bearer-token flow covers how an agent gets a scoped token to call an MCP tool. This guide covers what happens after the agent has that token — every call transits the MCP Gateway, which is where AtmanID actually enforces policy, rather than trusting the downstream MCP server to enforce it correctly on its own.
Why a gateway, not just an issued token
A Bearer token with the right scope is only as good as the server that checks it. A misconfigured or third-party MCP server can skip validation, honor the token but ignore its scope, or simply not tell you what data an agent sent it. The gateway closes that gap by sitting inline: every agent → MCP call is validated, scope-checked, rate-limited, and inspected by AtmanID before it reaches the destination server — so enforcement lives on infrastructure you control, not on someone else’s.
Go to MCP Gateway in the Agents section of the dashboard: the Events view shows every call, what the gateway decided and why, with a drill-down into any individual event; the Settings view holds each server’s mode and rate limit and your DLP rules.
- Who is callingThe agent’s AtmanID token and its proof of possession; the agent is active and in your organisation.
- Which server and toolWith the recommended settings: the server is approved, with a named owner, and the tool is one its owner approved and has not changed since.
- Is it allowedThe tool is in the agent’s grant; the agent is within its rate limits.
- What it carriesThe payload is inspected for credentials, payment cards and government identifiers — decoded as well as raw — and for data another server just handed the agent.
- Should it happenYour intent policies decide: allow, deny, or hold the call for a person to approve.
Any stage can refuse the call, with its reason. In shadow mode a would-be refusal is recorded and the call goes on, so you can see what a policy would do before it does it.
The three enforcement modes
Every MCP server has a gateway_mode, and it governs scope enforcement, rate limiting, and DLP inspection uniformly — one lever, not three separate switches:
- SHADOW (default for new servers) — the gateway runs the full validation chain, but its own checks never block. If a call would have been denied, the outcome is logged as
WOULD_DENYwith the reason, and the call goes on to intent policy, which applies its own mode (below). This is how you find out what a policy change would actually affect before it affects anyone. - ENFORCE — the same checks now actually block. A scope mismatch, a rate-limit breach, or a flagged payload returns a real denial instead of a logged one.
- DIRECT — bypasses the gateway entirely. This is a break-glass lever only, not something exposed as a UI toggle, and every server running in DIRECT mode is a standing exception worth knowing you have.
Promoting a server from SHADOW to ENFORCE is done from the server’s row in MCP Gateway → Settings, and it shows you a promotion-safety preview first — a summary of what the shadow log would have denied, scoped to the specific reasons gateway_mode governs, so you’re not flipping the switch blind.
Gateway mode and intent mode are independent
Gateway enforcement (scope, rate limits, inspection) and intent enforcement (your allow, deny and require-approval policies) are two separate settings. A gateway in SHADOW never switches off intent enforcement: a call the gateway only logs is still refused, or held for approval, if its server’s intent mode is ENFORCE and a policy says so.
Enforcement settings
Each check that can block has a setting in MCP Gateway → Settings → Enforcement Settings, with a description and a Recommended marker. Identity admins, tenant owners and CISOs change them there, and every change is audited and takes effect within 30 seconds. New organisations start with the recommended checks on: credentials blocked in every mode, extended secret inspection, holding tools with suspicious descriptions or unapproved changes, approved servers only, response redaction, blocking sensitive data moving between servers, and strictest-match policy resolution. Enforcing intent policy for every agent starts off, because calls that match no policy are denied; turn it on once your policies are in place. Once it is on, you can exempt a single agent without SDK integration for up to 30 days, with a reason, under that setting: its calls are still checked and would-be refusals recorded, but not blocked, and the exemption ends on its own. Granting and ending one are audited.
Rate limiting
Two limits apply, both configurable per tenant:
- A global per-agent limit — total calls per minute across every MCP server the agent talks to, closing the gap where an agent under any single server’s threshold could still fan out across many servers and overwhelm downstream systems in aggregate.
- A per-(agent, server) limit — a tighter cap on one specific server, when you want a stricter ceiling than the tenant default for a particular integration.
The tenant-wide default is shown, and changed, in MCP Gateway → Settings; individual servers can override it. A limit breach in ENFORCE mode returns a real rate-limit denial; in SHADOW mode it’s logged as a would-deny and the call still goes through.
DLP inspection
Every request payload — and every response coming back from the MCP server — is scanned by built-in checks in three classes: credentials and secrets (cloud access keys, private keys, tokens, and API keys for common developer, payment and AI services), payment card numbers (checksum-validated, not just pattern-matched) and government identifiers. The scan reads the payload decoded as well as raw, so a value wrapped in a common encoding is still seen. A match is recorded as a flag on the event; in ENFORCE mode a flagged request is blocked outright rather than merely logged.
Extended inspection starts in warn mode: its findings are recorded on events (filter Events by Flagged only to see them) but only block once Block secrets found by extended inspection is on in MCP Gateway → Settings → Enforcement Settings. Separately, Block credentials in every mode refuses any request carrying a credential even when the server’s gateway mode is SHADOW — a secret leaving through an agent is not something to soak-test. Personal data keeps following the gateway mode.
Response inspection matters as much as request inspection: a compromised or misconfigured MCP server could otherwise leak a secret back through the gateway in its reply with no record of it. Both directions run through the same checks. By the time a reply arrives its tool call has already run, so a finding in a response is recorded on the event for investigation, and for servers that handle personal data the values can be redacted before the agent reads them (below).
Adding your own rules
The built-in checks can’t be edited or turned off — they’re the floor, not a starting point you’re expected to customize away. On top of them, you can author your own tenant-specific DLP rules from the DLP Rules card in MCP Gateway → Settings: a rule is either a literal substring match or a regular expression, and it adds a new flag alongside the built-in ones. Regex rules run on a linear-time (RE2-style) engine, so no pattern can backtrack catastrophically; a pattern is checked at save time and rejected if it uses features that engine doesn’t support, such as lookarounds or backreferences. A rule you add can’t itself become a denial-of-service vector.
Data that moves between servers
Each call can look harmless on its own while two calls together leak data: read a customer record from one tool, then send it out through another. When a server’s response hands an agent personal data or a credential, the agent is marked for a period afterwards, and a call it then makes to a different server is flagged Data From Another Server (TAINTED_SESSION) on the event. The flag is recorded only until Block sensitive data moving between servers is on; then it blocks like any inspection flag, following the server’s gateway mode.
Personal data in responses
A server’s owner can mark it as handling personal data (MCP Gateway → Settings → Personal data → Redact). The gateway then replaces government identifiers and valid payment card numbers in that server’s responses with a [REDACTED:…] marker before the agent reads them — JSON responses stay valid JSON. Each event records how many values were found, never the values. Redaction starts in warn mode: until Redact personal data in responses is on, the gateway counts what it would redact and passes the response through unchanged, so you can check the counts in Events first.
Telling your MCP server which agent is calling
By default the gateway forwards a call with no credential: the agent’s AtmanID token never leaves AtmanID, so your server can’t tell agents apart. To let it, open MCP Gateway → Settings → Upstream identity and choose Token exchange, with the audience your server expects. For each call the gateway then sends a short-lived token that AtmanID signs for that server only, in the x-atmanid-agent-token header. It is sent in addition to whatever your server uses today, so you can verify it before you rely on it. Once your server verifies it, tick Require the token: the gateway then also sends it as Authorization: Bearer <token>, and refuses a call it cannot issue a token for instead of forwarding it without one.
The token is a JWT (ES256). Your server should check:
| Check | Value |
|---|---|
Header typ |
atmanid-agent+jwt |
| Signature | against the key set at https://<your AtmanID host>/api/agents/token-exchange/<tenant id>/jwks (the dialog shows the exact URL) |
iss |
the same URL without /jwks |
aud |
the audience you configured |
exp |
not passed; tokens live 5 minutes |
ver |
1 |
The claims tell your server who is calling. sub and act.sub are the agent, and scope lists the tools the agent is granted on your server. jti identifies the token in your logs. The gateway reuses a token for the same agent and server across calls for up to its 5-minute life, so don’t refuse a jti you have seen before. If the server’s owner opts in, act also names the person the agent acts for, as act.act.sub: "user:<id>". That is off by default, so no personal data reaches your server unless you ask for it.
To see a real token before you change your server, point a test server’s upstream URL at https://<your AtmanID host>/api/agents/token-exchange/<tenant id>/echo, set it to Token exchange, and call a tool through the gateway. The response says whether the token verified, where it arrived (sent_in), and its header and claims.
To make the gateway the only way to reach your server, require this token and refuse everything else: see Deploying so nothing bypasses the gateway.
Signing keys rotate every 90 days. The previous key stays in the key set until every token it signed has expired, so cache the key set by kid and refresh it when you see an unknown one. Every token issued is recorded in the audit trail as MCP upstream token issued.
The tool list agents see
An agent that asks an MCP server for its tools reads whatever the server says today — including a description that changed after you approved it, or one written to instruct the model (“ignore your previous instructions”, “don’t tell the user”, “read ~/.ssh first”). Agents that ask the gateway instead (GET /v1/mcp/{serverId}/tools) get the approved inventory: the name, description and schema the server’s owner approved, never a pending change, and only the tools the agent’s token may call.
Every description is also scanned for instructions aimed at the model and for invisible characters. Findings are shown to the owner on the server’s Tool Inventory and recorded in the audit trail. With Hold tools with suspicious descriptions on, a flagged new tool is held for the owner instead of being trusted automatically, and a flagged tool nobody has reviewed is left out of the tool list; a tool the owner approved after seeing the findings is listed.
Intent policy: what an intent is, and how a decision is made
An intent is what the agent is trying to do, as a name such as repo:delete or crm:export. For a gateway call it is the tool’s bound intent (or the tool name when none is bound), and the resource is extracted from the call’s arguments. An intent policy matches intent and resource patterns (* wildcards), optionally argument conditions and budgets, and says ALLOW, DENY or REQUIRE_HITL.
A decision is made in this order:
- The agent’s own state — a suspended or deprovisioned agent is denied before any policy is read; runtime holds (an ITDR alert, configuration drift) only ever add a human.
- Matching policies — agent-specific policies before tenant-wide ones, then by priority. By default the first match decides. With Strictest matching policy wins on, the strictest matching policy decides (DENY over REQUIRE_HITL over ALLOW), so an older broad ALLOW cannot mask a newer DENY; until then, a case where the two would differ is logged.
- No match — denied (default-deny), and the gap is raised for review.
- Risk threshold — an ALLOW from a policy with a risk threshold becomes REQUIRE_HITL when the agent’s risk level (Low, Medium, High or Critical) reaches it. It only ever adds a human, never relaxes a decision; it applies once Hold high-risk agents at a policy’s risk threshold is on, and is logged until then.
- Approval — a REQUIRE_HITL holds the call for a person. A policy can name its approver (an active user’s email), who can then decide its holds alongside agent-oversight roles. A just-in-time session approved in advance can satisfy a hold.
- Owner risk and budgets — an agent whose owner has a high-risk sign-in is held, and an ALLOW that would exceed a policy’s daily budget takes that policy’s action instead.
The policy simulator (Agent Policies → Policy Simulator) resolves matching policies the same way — first match, or the strictest when Strictest matching policy wins is on — and shows when a stricter policy also matches. It reports the policy decision; the agent-specific steps after it (risk threshold, owner risk, budgets) depend on live state and are applied only at enforcement.
Querying the audit trail
Every gateway transit — allowed, denied, would-deny, or bypassed — writes an event, whether or not the DLP scan found anything. If you need to answer “what did this agent actually call, and what did we do about it,” the event log (MCP Gateway → Events in the dashboard) is a single place to look rather than reconstructing the answer from the downstream MCP server’s own logs, which you may not control. Request payloads are hashed by default rather than stored in full — full-payload capture is an explicit opt-in per server, not the default, so investigating an incident doesn’t require storing sensitive data you didn’t need to keep.
© AtmanID · Privacy