MCP Gateway OAuth: Resource Binding, Discovery and Step-Up
Implement MCP gateway OAuth with protected-resource metadata, canonical resource indicators, audience validation, PKCE and bounded step-up retries.
An MCP gateway should request and accept tokens for the canonical MCP server resource, not for a generic ecosystem audience. The HTTP authorization flow uses protected-resource metadata for discovery, the OAuth resource parameter in authorization and token requests, and audience validation at the protected server.
These are transport-access controls within a broader MCP gateway. Exact tool authorization still needs policy over the tool name, arguments and current business state.
Implement discovery defensively
The MCP authorization specification requires protected MCP servers to publish metadata described by RFC 9728. A 401 response can point the client to resource_metadata; clients also support the well-known URI form.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="files:read"
{
"resource": "https://mcp.example.com",
"authorization_servers": ["https://auth.example.com"],
"scopes_supported": ["files:read"]
}
Apply an authorization-server trust policy. A server-controlled metadata document must not redirect enterprise clients to any issuer on the internet. Bound redirects, response sizes, content types, cache lifetime and network destinations.
Keep the resource value stable
RFC 8707 defines resource indicators. MCP clients include resource in both authorization and token requests. Use the most specific canonical server URI that identifies the intended protected resource and handle scheme, host and trailing-slash normalization consistently.
Test these cases:
| Case | Expected result |
|---|---|
| token audience is another MCP server | 401 |
| resource parameter omitted | authorization request rejected or incompatible flow surfaced |
| query string contains access token | reject and prevent logging |
| metadata issuer is not trusted for tenant | discovery rejected |
| uppercase host normalizes to approved host | deterministic result |
| fragment appears in resource URI | reject |
The MCP server must validate its own token. A gateway validation does not justify accepting trusted identity headers over an unauthenticated upstream connection.
Bound step-up behavior
When a request lacks scope, the server can return 403 with insufficient_scope, a required scope and resource metadata. A client acting for a user may repeat authorization with the new scopes. Limit retries and record attempted upgrades; otherwise a bad server or configuration can create a consent loop.
Scope step-up grants access. It should not silently satisfy a business approval. A payments:submit token does not prove that a finance approver accepted a particular supplier, amount and destination.
Protect credentials
Use Authorization headers, never URI query parameters. Apply PKCE to authorization-code clients as required by the MCP specification and current OAuth security practice. Keep refresh and upstream tokens in a credential broker rather than model memory, tool arguments or action receipts. RFC 9700 provides current OAuth security guidance, while DPoP defines one sender-constrained token mechanism.
The MCP security controls article turns this into tests. OAuth scopes versus business authority explains the next authorization layer. Review Intelliger's MCP authorization article for the product viewpoint.
Protocol versions change. This draft is reviewed against the MCP 2025-11-25 specification and should be rechecked against the deployed client and server versions before publication.
OAuth implementation questions
What is the canonical MCP resource?
Use the URI that identifies the protected server under the deployed routing model. A path may distinguish servers on one host. Standardize scheme and host casing, port handling and trailing slash behavior, then publish the value in protected-resource metadata. Client, authorization server, gateway and resource server must agree. Do not derive audience from an untrusted Host header behind a proxy.
Can one token cover several MCP servers?
The safest default is one intended resource. A broad token increases the impact of theft and confused-deputy behavior. If an authorization server supports a compound resource model, verify how every server validates audience and how scopes remain isolated. A gateway should not transform a multi-resource token into implicit permission for every admitted server.
How should metadata be cached?
Honor validated cache controls within a maximum allowed age and key the cache by canonical resource and tenant trust policy. Record the retrieved issuer set and metadata digest. During outage, follow an explicit risk-class rule. Do not keep using changed authorization-server metadata indefinitely because discovery happens outside the main request path.
What redirect URIs are safe for local clients?
Follow the MCP and OAuth rules for exact redirect validation and localhost handling. Prefer loopback addresses and ephemeral ports where the client profile supports them. Do not accept wildcard hosts or open redirects. Test malicious sibling domains, encoded path changes and a callback initiated from another browser session.
When should scope step-up stop?
Limit retries per resource and operation, preserve the requested scope history and stop on repeated insufficient_scope. A server can be misconfigured or hostile. The client should not keep prompting the user or accumulating scopes. Business approval remains separate, so a successful step-up does not authorize a payment or production action.
What should be recorded for an OAuth failure?
Record resource, issuer, client identifier, requested scope set, error class and correlation ID without token values or authorization codes. Separate discovery, authorization-server and resource-server failures. This lets operators distinguish an unknown issuer from a wrong audience or insufficient scope without exposing credentials in searchable logs.
Test discovery through the same proxies, paths and tenant routing used in production. A correct metadata document at the host root does not help if the deployed MCP endpoint needs a path-specific resource, a reverse proxy rewrites the canonical URI, or one region serves stale issuer metadata. Capture the WWW-Authenticate response and the authorization and token requests. Confirm that the same resource value survives the complete flow and appears as the audience the protected server validates.
Repeat after a gateway or DNS migration. Canonical resource changes can strand clients or tempt operators to accept both old and new audiences indefinitely. Set a bounded transition and test that the old audience stops working when it ends.