Where a gateway sits in the MCP authorization flow
The draft MCP specification defines authorization at the transport level for HTTP-based transports. A protected MCP server is an OAuth 2.1 resource server, the MCP client is an OAuth client acting for a resource owner, and a separate authorization server authenticates the user and issues the tokens 1. Authorization is optional, and the stdio transport is meant to take credentials from the environment instead 1.
Put a gateway in front of remote MCP servers and you have to decide which of those roles it plays. For the clients connecting to it, the gateway is the MCP server, so it is the resource server: it must publish protected resource metadata, challenge unauthenticated requests, and validate tokens. For each upstream server it is a client of something else, and that relationship needs its own credential. Most of the mistakes in this area come from collapsing those two relationships into one token.
The rest of this guide takes the flow in order: discovery, audience, scopes, the passthrough rule, upstream credentials, and the records worth keeping. It complements the credential-leak article and the gateway overview, and does not repeat their material. The spec text is a draft as read on 2026-11-18, so recheck normative wording before you encode it in policy.
What the client does before your gateway sees a token
A client that connects with no token gets a 401. The server must either put a resource_metadata URL in the WWW-Authenticate header or serve its metadata at a well-known URI, and clients must support both 2. That metadata is the OAuth 2.0 Protected Resource Metadata document from RFC 9728, which MCP servers must implement 1. In it, resource is required and scopes_supported is recommended; authorization_servers lists the issuers 3. The MCP document must include authorization_servers with at least one entry 2.
A minimal document for a gateway endpoint looks like this:
{
"resource": "https://mcp-gw.example.com/mcp",
"authorization_servers": ["https://auth.example.com"],
"scopes_supported": ["mcp:tools"]
}The resource value should be the exact URL clients connect to, and clients must not use a document whose resource does not match 4. That binding is what stops an attacker from publishing metadata that claims to describe your gateway. RFC 9728 derives the well-known location deterministically from the resource URL for that reason 3.
The client then fetches authorization server metadata, checks that the issuer equals the issuer used to build the URL, and refuses to continue if code_challenge_methods_supported is absent, because that means no PKCE 5. If your gateway lists several authorization servers, each is independent: clients keep separate registration state and tokens per server 2. Your gateway should do the same when it validates, keeping a per-issuer key set and never accepting an issuer not in its list.
Audience: the check that makes a token yours
Clients must send the RFC 8707 resource parameter in both the authorization and token requests, set to the MCP server's URL 5. This binds the token to its intended audience. The server side of that bargain is a MUST: MCP servers must validate that tokens presented to them were issued for them, and must reject tokens that do not name them in the audience claim or otherwise prove they are the intended recipient 5.
For a gateway, that check runs on every request, before routing, before any tool lookup. A sketch:
def authenticate(request, cfg):
token = bearer_token(request.headers) # Authorization header only
if token is None:
return challenge(401, scope="mcp:tools") # WWW-Authenticate + resource_metadata
claims = verify(token, issuers=cfg.issuers) # signature, exp, iss against a per-issuer key set
if cfg.resource not in as_list(claims["aud"]):
return challenge(401) # token was minted for someone else
granted = set(claims.get("scope", "").split())
if not granted >= required_scopes(request):
return challenge(403, error="insufficient_scope",
scope=" ".join(required_scopes(request) | granted))
return Principal(sub=claims["sub"], client=claims.get("client_id"), scopes=granted)If your authorization server issues opaque tokens, introspect them and apply the same audience rule to the introspection result; the principle does not depend on the token format. Whatever the format, compare the audience to your own resource identifier by exact match, not by prefix. A gateway that serves many upstream servers under one hostname should decide whether it has one audience for the whole gateway or one per upstream endpoint, and then publish metadata for each accordingly. One audience per gateway is simpler; per-upstream audiences narrow the damage if a token leaks.
Scopes, challenges and step-up
Servers should include a scope parameter in the WWW-Authenticate header to name what the current request needs. Clients must treat the challenged scopes as authoritative for the current operation, and when re-authorizing should include them alongside scopes already granted so permissions needed elsewhere are not lost 1. The selection order for a client is: scopes from the 401 challenge, else everything in scopes_supported, else no scope parameter at all 1. scopes_supported is meant to be the minimal set for basic functionality, with more requested incrementally 1.
A valid token that lacks a scope should get a 403 with an insufficient_scope challenge, which starts step-up authorization; clients should limit how often they retry 4. For a gateway, three consequences follow:
- Define scopes at a granularity you can enforce at the gateway: for example read-only tool classes versus tools that change state, rather than one scope for everything.
- Compute
required_scopesfrom the tool definition you have approved, not from what the client claims it is calling. - Record the scope set a call ran under. A step-up changes what a session can do; the log should show when.
Over-broad scopes are the usual finding in review, so keep the baseline small. The MCP best-practices page has a dedicated scope minimization section on this risk 6.
Token passthrough: why the gateway cannot just forward
The best-practices page defines token passthrough as an anti-pattern in which an MCP server accepts tokens from a client without validating that they were issued to it, and passes them through to the downstream API 6. The authorization spec states the rule for the upstream leg directly: if the MCP server calls upstream APIs it may act as an OAuth client to them, the token used there is a separate token issued by the upstream authorization server, and the server must not pass through the token it received from the MCP client 5.
For a gateway, that rules out the shortcut of copying the inbound Authorization header onto the upstream request. The shortcut feels harmless because it keeps the user's identity flowing. It breaks audience binding (the token was minted for the gateway, and now an upstream sees it), and it hands every upstream operator a credential that works against the gateway. A related failure: a gateway that logs or caches inbound tokens. The spec calls out tokens cached or logged on the server as a theft route, and asks for short-lived access tokens and refresh-token rotation for public clients 5. Strip the header from your own logs at the edge.
There is a second hazard if the gateway itself brokers upstream OAuth. A proxy that uses one static client ID with a third-party authorization server, lets clients register dynamically, and skips per-client consent is open to the confused deputy attack: a consent cookie from an earlier legitimate login lets an attacker's crafted request skip the consent screen and receive an authorization code 6. The required mitigation is a per-user registry of approved client IDs checked before the third-party flow, exact redirect URI matching and single-use, short-lived state values 6. Dynamic Client Registration is deprecated as of protocol version 2026-07-28, though the attack still applies to proxies that support it 6.
Per-user or shared upstream credentials
Once the gateway has validated the inbound token and refused to forward it, it needs something to present upstream. There are two shapes, and they trade identity fidelity against operational weight.
| Per-user upstream token | Shared service credential | |
|---|---|---|
| Who the upstream sees | The person | The gateway's service identity |
| Upstream's own permissions | Apply per person | Apply to everyone equally |
| Where identity is enforced | Upstream and gateway | Gateway only |
| Consent and consent records | Needed per user and client | One admin decision |
| Storage burden | Refresh tokens per user, rotated | One secret per server |
| Offboarding | Revoke the user's grant | Rotate the shared secret or remove the grant at the gateway |
| Fits | Mail, documents, tickets where data is user-specific | Internal tools, read-only data, automation with no human |
Per-user tokens are the right default when the upstream holds user-specific data, because the upstream's own access control stays in play and its logs name the person. The MCP tutorial lists user-specific data and the need to audit who performed which actions among the reasons authorization is strongly recommended 4. The cost is a token vault with refresh handling and the consent machinery from the previous section.
A shared credential is simpler, and sometimes the only option when an upstream accepts only an API key. The price is that the upstream cannot tell users apart, so every authorization decision rests on the gateway: which key may call which tool, with which arguments. Use read-only credentials where you can, and treat the gateway's grants as the access-control system of record. Do not mix the two silently. If a server is registered with a shared credential, the audit record should say so, so that a reviewer does not assume the upstream enforced per-person limits.
What INFRO's MCP gateway does with credentials
INFRO's MCP gateway uses the shared-credential shape. An admin registers each server once with its credential; agents then reach it with the INFRO gateway key they already use for model calls, and INFRO adds the server's credential from its vault on every call 7. Server header values are encrypted at rest and bound to the organization and the server; the console and management API show only header names, and replacing a credential is write-only 8. The server never sees the INFRO key, the agent's Authorization header or any X-INFRO-* header 8. INFRO never executes a tool 7.
Two limits matter for this topic. The gateway key is INFRO's own credential, not an MCP-spec OAuth access token, so the audience and step-up rules above describe what to ask of any OAuth-based layer, not a property of that key. And the security model page describes credential headers registered by an admin; it does not describe a per-user upstream OAuth exchange, so check the docs before assuming one. For approved tools, per-key grants and the call record, read the MCP gateway docs (opens in a new tab).
The audit evidence to keep
The records worth keeping are the ones that let you answer, months later, who caused a tool call and under what authority. For each call, keep:
- The principal: the
subfrom the validated token, or the gateway key and its owner. - The client: the OAuth
client_id, and for client ID metadata documents the document URL. - The issuer and the audience the token carried, to show the audience check passed.
- The scope set in force, and any step-up event with its old and new scope sets.
- The upstream server, the tool name and the approved definition version.
- The upstream credential mode: per-user or shared, and which credential identifier, never its value.
- The outcome, error code and latency, and sizes plus a hash of arguments rather than contents.
INFRO's call record is described as metadata-only by default: time, server, tool, outcome, error code, latency, argument and result sizes, a SHA-256 of the arguments, guardrail counts, and the key, project, environment and attribution; contents are kept only if an owner or admin opts in 8. The calls sit on the same trace as the agent's model calls 7. Separately, the audit log is an append-only record of administrative changes such as keys, connections, policies and membership, kept apart from request traces, and it can be read through the management API with the audit:read scope 9. Use it for "who widened access", and the call record for "who used it".
Never store the access or refresh tokens in these records. If you must correlate a token across systems, store a hash and the jti where the token carries one. Map the checks to your risk register using the OWASP GenAI Security Project, whose Top 10 for LLM applications now lives under the broader project 10.
A checklist before you put a gateway in front of remote MCP servers
- The gateway publishes RFC 9728 metadata with an exact
resourceand at least oneauthorization_serversentry. - Unauthenticated requests get a 401 with
resource_metadataand ascopehint. - Every request is checked for signature, expiry, issuer and an audience equal to the gateway's own resource.
- No inbound
Authorizationheader is copied upstream, and none is written to logs or caches. - Missing scope returns 403
insufficient_scope; step-up retries are bounded. - Each upstream server is marked per-user or shared, with the reason written down.
- Per-user flows keep a per-user registry of approved clients and exact redirect URI matching.
- The audit record carries principal, client, audience, scopes, tool and credential mode, and no token values.
- Access tokens are short-lived and refresh tokens rotate for public clients.
- Offboarding removes a person's grants at the gateway and, for per-user tokens, at the upstream.
