Skip to main content
This page explains how Tyk Gateway implements the OAuth 2.1 authorization model defined by the MCP specification. It covers inbound Bearer token authentication via the oauth2 security scheme, Protected Resource Metadata (PRM) discovery, RFC 8693 token exchange, and upstream OAuth. After reading this page you’ll be able to configure end-to-end OAuth 2.1 for any MCP proxy.

​
MCP Auth Model

MCP authorization operates on two distinct planes. Inbound authorization governs how MCP clients (AI agents, LLM frameworks, and applications) authenticate to Tyk Gateway. Tyk validates the credential on every request before it reaches your upstream MCP server. All authentication methods supported by Tyk apply here: Bearer tokens, API keys, JWT, and mutual TLS.
For OAuth 2.1 compliance, configure the oauth2 security scheme. It publishes the Protected Resource Metadata discovery document, enforces per-operation scopes, and enables RFC 8693 token exchange — all from a single scheme declaration. See OAuth 2.0 (External IdP).
Upstream authorization governs how Tyk authenticates to your upstream MCP server when that server requires an OAuth token. Tyk obtains the token from the authorization server using the client credentials flow and injects it into every proxied request. Your upstream receives a properly authorized request without any involvement from the original caller. The two planes are configured independently — Bearer tokens on the inbound side can be combined with client credentials on the upstream side.

​
Protected Resource Metadata

Protected Resource Metadata (PRM) is the standardized discovery mechanism defined in RFC 9728. It gives OAuth clients a machine-readable document describing a protected resource: which authorization servers can issue tokens for it, and which OAuth scopes it supports. The MCP specification recommends that every MCP server expose a PRM document so that clients can discover the correct authorization server before making their first request. Without it, clients must be pre-configured with authorization server URLs — an approach that becomes fragile as deployments grow and authorization infrastructure changes. Tyk serves the PRM document natively. When PRM is enabled on an MCP OAS definition, Tyk intercepts GET requests to the well-known path and serves the metadata document. The endpoint is unauthenticated by design — clients need it before they have a token.

​
The discovery flow

The WWW-Authenticate header Tyk sends on authentication failure is a standard Bearer challenge extended with the resource_metadata parameter defined in RFC 9728. Any OAuth 2.1-compliant client library handles this automatically.

​
Configuring PRM

PRM is configured within the oauth2 security scheme block in the Tyk Vendor Extension. The scheme name (idpAuth in the example below) must match the scheme declared with type: oauth2 in the OAS components.securitySchemes section — see OAuth 2.0 (External IdP) for the full scheme setup.
The PRM endpoint is served at {listen-path}/{wellKnownPath}. With the default path and a listen path of /weather-mcp/, the endpoint is available at /weather-mcp/.well-known/oauth-protected-resource.
If you have an existing PRM configuration at authentication.protectedResourceMetadata, Tyk Dashboard migrates it automatically to authentication.securitySchemes[name].protectedResourceMetadata on startup. No manual action is required. APIs that already have a scheme-level PRM block are not modified.

​
Scope enforcement

Scope enforcement checks that the bearer token carries the scopes required by the matched operation or MCP primitive — translating what the authorization server granted into access decisions at the gateway. Configure it under scopeCheck in the oauth2 scheme block:
The required scopes for each operation come from the security: array in your OAS definition. For MCP primitives, which have no OAS path entry, declare scopes in the Tyk Vendor Extension under middleware.mcpTools, middleware.mcpResources, or middleware.mcpPrompts:
When a request fails scope enforcement, Tyk returns 403 Forbidden with WWW-Authenticate: Bearer error="insufficient_scope". Scope enforcement runs after JWT signature validation — if the token is invalid, the request is rejected at the JWT auth step before scope check is reached. For per-operation and per-primitive exemptions (scopeCheck.enabled: false on individual operations or MCP primitives) and the full field reference, see OAuth 2.0 (External IdP).

​
Upstream OAuth

When the upstream MCP server requires OAuth, Tyk handles token acquisition transparently. It acts as an OAuth client — obtaining a token from the upstream’s authorization server using the client credentials flow and attaching it to every proxied request. The original MCP client never needs to supply upstream credentials. Tyk caches acquired tokens and refreshes them before they expire, so the upstream sees a consistent stream of valid credentials without a token request on every MCP call.
Upstream OAuth is available in Tyk Enterprise Edition only.

​
Client credentials flow

Client credentials is the OAuth flow for machine-to-machine communication — no user is involved, Tyk acts as the client. OAuth 2.1 retains this flow specifically for server-to-server scenarios.

​
Configuring upstream OAuth

Upstream OAuth is configured in the upstream.authentication section of the API definition:

​
Token exchange

The MCP authorization specification requires that an MCP server MUST NOT pass through the token it received from the MCP client when making requests to upstream APIs. The upstream token must be a separate token issued by the upstream authorization server. Token exchange (RFC 8693) is how Tyk satisfies this requirement while preserving the caller’s identity. Tyk presents the validated inbound token to an authorization server and receives a backend-scoped token in return. The inbound agent token never reaches the upstream. This matters for MCP because:
  • Spec compliance — The MCP spec explicitly forbids passing through the inbound token. Token exchange satisfies this requirement while maintaining a traceable delegation chain.
  • Audience compliance — MCP servers must validate that tokens were issued specifically for them as the intended audience (RFC 8707). Token exchange produces a token audienced to the upstream service without requiring clients to request multiple tokens.
  • Separation of trust — The AI agent’s credential stays scoped to the gateway trust domain; the upstream receives a narrowly-scoped credential appropriate to its own.
Token exchange is Enterprise Edition only and is configured within the oauth2 security scheme. For full configuration details — including provider setup, caching, and per-primitive overrides — see Token exchange.
Do not configure upstream.authentication.oauth alongside token exchange. They serve the same purpose — authenticating Tyk to the upstream — and configuring both produces a conflict. Use token exchange when you want to propagate a delegated credential derived from the inbound token. Use upstream.authentication.oauth when Tyk should authenticate with its own static client credentials independent of who the original caller was.

​
Composing features

Each feature on this page is independent. The example below uses all of them, but you can enable any subset depending on your requirements. JWT authentication validates the inbound token’s signature. In Tyk 5.14.0 this is required alongside the oauth2 scheme because the oauth2 scheme reads token claims but does not verify the signature itself. It is the baseline for everything else. PRM enables dynamic discovery — clients that arrive without a token learn where to obtain one. Enable it if your MCP clients are OAuth 2.1-compliant and should discover the authorization server automatically. Omit it if your clients are pre-configured with the authorization server URL. Scope enforcement (scopeCheck) checks that the token carries the scopes required by the matched operation or MCP primitive. Use it when the IdP owns access decisions — the authorization server grants specific scopes and Tyk enforces them at the gateway. If you prefer Tyk’s policy engine to control primitive access (a platform-owned model where keys are issued with policy-level permissions), omit scopeCheck and rely on policies instead. The two approaches are mutually exclusive per primitive: using both creates conflicting ownership of access decisions. Token exchange replaces the inbound agent token with an upstream-scoped token before forwarding. The MCP specification requires that the upstream never receives the original token — token exchange is how you satisfy that requirement while preserving the delegation chain. If you are using Upstream OAuth with static client credentials instead, token exchange can be omitted. PRM and scope enforcement are particularly complementary. PRM advertises which scopes clients need to request; scopeCheck enforces at runtime that the presented token actually carries them. When autoDeriveScopes is enabled, both are driven by the same security: declarations in your OAS definition — so the scopes a client is told to request and the scopes Tyk enforces are derived from the same source and can’t drift out of sync. Enabling PRM without scopeCheck means scopes are advertised but not enforced at the gateway. Enabling scopeCheck without PRM means enforcement works, but clients need to know the required scopes upfront rather than discovering them dynamically. Common configurations:

​
The complete OAuth 2.1 flow

The end-to-end flow has two phases. The authorization server appears in both — first when the MCP client obtains its agent token, then when Tyk exchanges it for an upstream-scoped token. Phase 1 — Discovery
  1. The MCP client makes a request to the MCP endpoint without a token.
  2. Tyk returns 401 Unauthorized with a WWW-Authenticate header pointing to the PRM well-known URL.
  3. The client fetches the PRM document and learns which authorization server to use and which scopes are supported.
  4. The client authenticates to the authorization server (authorization code flow, device flow, etc.) and receives an agent-scoped access token.
Phase 2 — Authenticated request
  1. The client sends the request with Authorization: Bearer <agent-token>.
  2. Tyk validates the token signature (JWT auth) and enforces scopes (oauth2 scheme).
  3. Tyk POSTs an RFC 8693 token exchange to the authorization server, presenting the agent token as subject_token and requesting a token audienced to the upstream MCP server.
  4. The authorization server returns an upstream-scoped access token.
  5. Tyk replaces the Authorization header with the exchanged token and forwards the request to the upstream MCP server.
  6. The upstream responds; Tyk returns the response to the client.
The agent’s original token never reaches the upstream MCP server. The MCP client and the upstream each receive a token issued specifically for their trust boundary.

​
A complete configuration example

The following configuration for a weather MCP proxy enables all four features — PRM discovery, JWT signature validation, scope enforcement, and RFC 8693 token exchange:
In this configuration:
  • MCP clients that arrive without a token receive a 401 with a WWW-Authenticate header pointing to the PRM document.
  • Clients that follow the discovery flow obtain a token from https://auth.example.com using the authorizationCode flow and present it as a Bearer token.
  • Tyk validates the token signature via the jwtAuth scheme (JWKS endpoint), then scopeCheck enforces that the token carries tools:read before the request proceeds.
  • Tyk exchanges the validated agent token for an upstream-scoped token audienced to https://weather-mcp.example.com. The original agent token never reaches the upstream MCP server.
In Tyk 5.14.0, the oauth2 scheme does not validate JWT signatures itself. The jwtAuth scheme in this example handles signature validation — configure JWT authentication on the API alongside the oauth2 scheme so that inbound tokens are verified before scope enforcement runs.
For the static client credentials variant — where Tyk authenticates to the upstream with its own credentials independent of the inbound token — see Upstream OAuth.

​
Per-primitive configuration

The complete example above configures each feature at the API level, applying uniformly to all primitives. Both scope enforcement and token exchange support per-primitive overrides when individual tools need different access requirements or different upstream credentials.

​
Multiple exchange providers

The providers array accepts multiple entries. Tyk selects the matching provider at request time by comparing the inbound token’s iss claim against each provider’s issuers list. This lets you handle tokens from different authorization servers — for example, your own IdP and a partner’s — routing each to the appropriate token endpoint and default target:
If no provider matches the inbound token’s issuer, the exchange step fails and Tyk returns an error before the request reaches the upstream.

​
Per-primitive scope and exchange overrides

The defaultTarget in each provider applies uniformly to every primitive. When individual tools need a different audience, a narrower set of scopes, or stricter scope enforcement than the API-level default, configure overrides directly on the primitive in the middleware.mcpTools map:
  • get-forecast requires tools:read. Scope enforcement rejects tokens that don’t carry that claim. The exchange uses the provider’s defaultTarget audience and scopes unchanged.
  • delete-station requires both tools:write and admin:stations. The exchange override requests a token audienced specifically to https://station-admin.example.com — a narrower credential than the standard weather MCP token — carrying only the admin:stations scope.
For the full scopeCheck and exchange field reference, see MCP middleware.