The platform team's first remote version of uw-assessment worked on day one, and it is the mistake this page starts from. Its token check was short: verify the signature against the identity provider's key, check the issuer, read the scopes. To call the assessment service it forwarded the caller's token unchanged, because the service trusted the same identity provider. Two hops, one token, very little code.
In the second week a developer wired the claims assistant to the server in a hurry, using a token the assistant already held from the same identity provider, issued for the insurer's CRM. Right key, right issuer, scope uw.read: the server ran get_roof_assessment and forwarded the CRM token to the assessment service, which made the same checks and answered. A token minted for another application had walked through two systems that never agreed to accept it, and nobody noticed. With a stolen CRM token, the same path is an incident.
Two checks were missing, and the MCP specification requires both: the server must accept only tokens issued for it, and it must never pass the token it received to anyone else. Who gets access decided who each caller is and what each may do. This page makes those decisions travel safely, from the first refused request to the downstream call.
Where MCP authorization applies#
Normative (MCP specification 2026-07-28): authorization is optional; HTTP-based transports should conform to the authorization specification; stdio should not, and takes credentials from the environment. The example follows that split: UW_MCP_PRINCIPAL on stdio, a token on every Streamable HTTP request (Local and remote).
The roles come from OAuth. A protected MCP server is an "OAuth 2.1 resource server"; the MCP client is an "OAuth 2.1 client" acting on behalf of a resource owner; the authorization server issues access tokens and "may be hosted with the resource server or a separate entity". Here: the identity provider stand-in https://idp.insurer.example and the resource server https://mcp.uw.insurer.example.
The OAuth version needs a date. The specification cites the OAuth 2.1 Internet-Draft revision 13 (May 2025); on 2026-11-18 the IETF datatracker lists revision 17 (31 October 2026), still a draft, not an RFC.
Before AI. This is the Spring Security resource server you know: an issuer URI, a key set, an expected audience, @PreAuthorize per endpoint. MCP adds a standard way for an unknown client to discover where to get a token, and an explicit rule against forwarding the token you received.
The smallest primitive: a 401 that points to a document#
A client that knows nothing sends a request without a token; the refusal tells it where to learn the rest. Messages 1 to 4 of the example's recorded HTTP session (out/mcp_transcript_http.json, written by run_cases.py on 2026-11-18 in a scratch copy):
POST /mcp (host's MCP client, no Authorization header)
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/list
HTTP 401
WWW-Authenticate: Bearer resource_metadata="https://mcp.uw.insurer.example/.well-known/oauth-protected-resource", scope="uw.read"
GET /.well-known/oauth-protected-resource
HTTP 200
{"resource": "https://mcp.uw.insurer.example",
"authorization_servers": ["https://idp.insurer.example"],
"scopes_supported": ["uw.read", "support.read", "analytics.read"],
"bearer_methods_supported": ["header"],
"resource_name": "uw-assessment (synthetic)"}
The document is protected resource metadata: a small JSON file, defined by RFC 9728 (April 2025), in which a protected resource says what it is and which authorization servers issue tokens for it. Normative (MCP specification 2026-07-28): MCP servers MUST implement it and list at least one authorization server, and MUST make it findable through resource_metadata in the 401's WWW-Authenticate header or at a well-known URI; clients support both and prefer the header. Clients MUST treat the challenged scope as authoritative for the operation.
scopes_supported leaves out uw.recommend and uw.decide on purpose. The security best practices page counts publishing every scope there as a common mistake and recommends a minimal start with targeted challenges later (step-up, below).
From the challenge to a token#
Between that 401 and the first successful call, each step closes a specific attack.
Find the authorization server's own metadata. The client fetches the metadata of https://idp.insurer.example as RFC 8414 or OpenID Connect Discovery (clients MUST support both, in a fixed order). The document's issuer MUST be identical to the issuer used to build the URL, or the client MUST NOT use it, so a server cannot point the client at someone else's endpoints under a trusted name.
Register the client. The authorization server must know which client is asking. With Client ID Metadata Documents (CIMD), the client's client_id is an HTTPS URL pointing to a JSON document that describes the client. The client-registration page is plain about the older way: "Dynamic Client Registration is deprecated. New implementations should use Client ID Metadata Documents instead." The priority order and the checks are in the folded section below.
Client registration: pre-registration, CIMD, and the deprecated DCRThe priority order, what the authorization server checks, and credentials keyed by issuer
Normative (MCP specification 2026-07-28): clients that support every mechanism SHOULD try them in this order: pre-registered client information; Client ID Metadata Documents if the authorization server metadata has client_id_metadata_document_supported; Dynamic Client Registration (RFC 7591) if it has a registration_endpoint; and finally asking the user to enter client details.
A CIMD client_id MUST use https with a path, for example https://example.com/client.json. The document MUST contain at least client_id, client_name and redirect_uris, and its client_id MUST equal the URL exactly. The authorization server MUST validate that match and the redirect URIs in each request against the document; it may apply trust policies such as domain allowlists. Fetching documents from URLs a client chose is an SSRF risk the authorization server must consider.
Dynamic Client Registration stays for backwards compatibility; when used, clients MUST send application_type (native or web). Pre-registered credentials and persisted DCR credentials MUST be keyed by the authorization server's issuer and MUST NOT be reused with a different one. CIMD client ids are portable across authorization servers.
For an enterprise, CIMD turns a client identity into a URL the security team can allowlist by domain, instead of a registration that any client can create at runtime.
Send the person to sign in, with PKCE. The client opens the authorization endpoint in a browser. It MUST use PKCE (Proof Key for Code Exchange: the client sends a hash of a secret now and the secret later, so a stolen authorization code is useless), with S256 when technically capable, and MUST refuse to proceed if the metadata lacks code_challenge_methods_supported. It records the expected issuer and compares the iss in the response (RFC 9207).
Name the server the token is for. This is the parameter that would have saved the opening scene. A resource indicator is the resource parameter, defined by RFC 8707 (February 2020), in which the client tells the authorization server which protected resource the token is for. Normative (MCP specification 2026-07-28): clients MUST send it in both the authorization and the token request, with the MCP server's canonical URI (here https://mcp.uw.insurer.example), "regardless of whether authorization servers support it". The authorization server puts that URI in the token's audience, and the token now names its one legitimate recipient.
Use the token on every request. Authorization: Bearer <access-token> on every HTTP request, never in the query string. Revision 2026-07-28 has no sessions, so each POST proves itself. Workloads with no person skip the browser step; the extensions overview lists an official OAuth Client Credentials extension at stage Stable for that case.
Diagram: From a refused request to a downstream call · discovery, token, call, exchange
Time runs down the page. The host's MCP client first calls without a token and gets a 401 that points to the protected resource metadata. It reads that document, finds the authorization server, reads the server's own metadata, and sends the person to sign in with PKCE and the resource parameter. With the token, every POST is validated by the MCP server for its own audience and authorized per call. To reach the assessment service the server exchanges the caller's token for a separate one with the service as audience; it never forwards the token it received. The first half happens once per token; the second half on every call.
- Host's MCP client to MCP server: POST /mcp, no token. The client knows nothing yet about where tokens come from.
- MCP server to Host's MCP client: 401 · resource_metadata, scope uw.read. The challenge names the metadata document and the scope this operation needs.
- Host's MCP client to MCP server: GET protected resource metadata. RFC 9728 document: resource, authorization_servers, scopes_supported, bearer_methods_supported.
- Host's MCP client to Authorization server: GET authorization server metadata. RFC 8414 or OpenID Connect Discovery; the issuer in the document must equal the issuer used to build the URL.
- Person + browser to Authorization server: sign in · PKCE S256 · resource. The browser carries the authorization request: client id (a CIMD URL or pre-registered), code challenge, scope, and resource set to the MCP server's canonical URI.
- Authorization server to Host's MCP client: code + iss (compare issuer). The client compares iss with the issuer it recorded before redirecting, to stop mix-up attacks.
- Host's MCP client to Authorization server: token request · code_verifier · resource. The resource parameter is sent again; the code verifier proves the client started the flow.
- Authorization server to Host's MCP client: access token · aud = this MCP server. A token whose audience names one resource.
- Host's MCP client to MCP server: POST tools/call · Bearer token. On every request: signature, issuer, audience, expiry, revocation; then scope, principal type and tenant for this call.
- MCP server to Authorization server: token exchange · audience = service. RFC 8693: the server trades the caller's token for a separate one with the service as audience, one scope, short life. A stand-in in the example.
- MCP server to Assessment service: call with the exchanged token. Never the caller's token: the passthrough guard refuses it and the service would reject its audience.
- MCP server to Host's MCP client: 200 · PropertyAssessment. The result returns to the host; the audit event records who asked and why it was allowed.
Read the diagram top to bottom. The first half happens once per token lifetime; the second half on every call: validate for this audience, authorize the call, exchange the token before calling the assessment service. The example implements the second half and the 401 challenge; sign-in, PKCE and registration are described from the specification, not run here.
On every request: audience first, then everything else#
The access token is the credential the client presents on each request: a string representing an authorization issued to the client, with an issuer, a subject, an expiry and, here, an audience, the resource it was issued for (aud). Normative (MCP specification 2026-07-28): servers MUST validate tokens as OAuth 2.1 section 5.2 describes and MUST validate that the token was issued for them; invalid or expired tokens MUST receive HTTP 401. The two sentences that would have stopped the CRM token:
Normative (MCP specification 2026-07-28). "MCP servers MUST only accept tokens that are valid for use with their own resources." and "MCP servers MUST NOT accept or transit any other tokens."
The example's server makes the checks in a fixed order, in check_claims() in identity.py. The tokens are toy tokens: base64url JSON plus an HMAC-SHA256 signature from Python's standard library, with the key written in the source. They are not a JWT library, they are not secure, and the identity provider is a stand-in. What they show truthfully is the order and the meaning of the checks. Quoted:
def check_claims(claims: dict[str, Any] | None, now_s: int, expected_audience: str,
revoked_jtis: list[str] | tuple[str, ...] = (), revoked_scopes: dict[str, list[str]] | None = None,
signature_ok: bool = True) -> dict[str, Any]:
"""The checks on already-decoded claims, in order. Pure: the JavaScript lab ports this function.
Returns {valid, checks: [{check, passed, detail}], failed: first failed check or None,
effective_scopes}. After a failed signature the other checks are "skipped": the claims cannot
be trusted. Revoked scopes do not invalidate the token; they are removed from effective_scopes.
"""
checks: list[dict[str, Any]] = []
def add(name: str, passed: bool | None, detail: str) -> None:
checks.append({"check": name, "passed": passed, "detail": detail})
if not signature_ok or claims is None:
add("signature", False, "the signature does not match the issuer's key")
for name in ("issuer", "audience", "expiry", "revocation"):
add(name, None, "skipped: unsigned claims are not trusted")
return {"valid": False, "checks": checks, "failed": "signature", "effective_scopes": []}
add("signature", True, "HMAC-SHA256 matches (toy key)")
iss_ok = claims.get("iss") == ISSUER
add("issuer", iss_ok, f"iss is {claims.get('iss')}" + ("" if iss_ok else f"; expected {ISSUER}"))
aud_ok = claims.get("aud") == expected_audience
add("audience", aud_ok, f"aud is {claims.get('aud')}" + ("" if aud_ok else f"; this server is {expected_audience}"))
exp = claims.get("exp")
exp_ok = isinstance(exp, int) and now_s < exp
add("expiry", exp_ok, f"exp {exp}, now {now_s}" + ("" if exp_ok else ": expired"))
jti_ok = claims.get("jti") not in revoked_jtis
removed = sorted(set(scopes_of(claims)) & set((revoked_scopes or {}).get(claims.get("sub", ""), [])))
detail = "jti not revoked" if jti_ok else f"jti {claims.get('jti')} is revoked"
if jti_ok and removed:
detail += "; grant revoked for this subject: " + " ".join(removed)
add("revocation", jti_ok, detail)
failed = next((c["check"] for c in checks if c["passed"] is False), None)
effective = [s for s in scopes_of(claims) if s not in removed] if failed is None else []
return {"valid": failed is None, "checks": checks, "failed": failed, "effective_scopes": effective}
After a failed signature nothing else is evaluated, because unsigned claims are text anyone could write. A revoked scope does not kill the token; it leaves the effective scopes, so reads continue (case UW-M05, below). A scratch script ran validate() on six toy tokens in a scratch copy on 2026-11-18. The run proves each check fails for the right token only; it proves nothing about cryptographic strength.
valid valid=true signature=ok issuer=ok audience=ok expiry=ok revocation=ok effective=['uw.read', 'uw.recommend']
forged valid=false signature=FAIL issuer=skip audience=skip expiry=skip revocation=skip effective=[]
wrong audience valid=false signature=ok issuer=ok audience=FAIL expiry=ok revocation=ok effective=[]
expired valid=false signature=ok issuer=ok audience=ok expiry=FAIL revocation=ok effective=[]
revoked jti valid=false signature=ok issuer=ok audience=ok expiry=ok revocation=FAIL effective=[]
scope revoked valid=true signature=ok issuer=ok audience=ok expiry=ok revocation=ok effective=['uw.read']
The "wrong audience" row is the opening scene's CRM token, case UW-M04 (this site's own case). Over HTTP it gets 401 with error="invalid_token", error_description="audience check failed" and the resource_metadata pointer; nothing executes. The expired token, case UW-M06, gets the same 401 with "expiry check failed"; run_cases.py --case UW-M06 --verbose confirms zero tool calls ran and a new token works. The model here is a scripted stand-in, so these results show how the protocol and the controls work, not how good any model is. The lab runs the same checks in the browser, token by token.
| Token | First failing check | Answer |
|---|---|---|
| valid (underwriting agent, audience this server) | none | HTTP 200, the PropertyAssessment |
| expired | expiry | HTTP 401, WWW-Authenticate: Bearer error="invalid_token", nothing executes (UW-M06) |
wrong audience (https://crm.insurer.example) | audience | HTTP 401 invalid_token (UW-M04) |
missing scope (intake agent asks for record_recommendation) | none (the token is valid) | HTTP 403 insufficient_scope, scope uw.recommend, JSON-RPC error -31403 |
| revoked jti | revocation | HTTP 401 invalid_token |
| forwarded downstream (the caller's token at the assessment service) | audience | refused by the passthrough guard; the server exchanges it for a new token: audience https://assessment-svc.internal.example, scope assessment.read, actor svc:uw-assessment-mcp, 60-second life |
When the token is valid but not enough: 403 and step-up#
"Is this token good?" and "is it good for this call?" get different status codes, so the client knows what to do next. Normative (MCP specification 2026-07-28): 401 means authorization is required or the token is invalid; 403 means invalid scopes or insufficient permissions. When a call needs a scope the token lacks, the server SHOULD answer 403 Forbidden with WWW-Authenticate: Bearer error="insufficient_scope", scope="...", resource_metadata="...", naming all the scopes the operation needs in one challenge.
The example's HTTP session has exactly that answer, when the underwriting agent's client sends the decision call that injected text asked for (messages 11 and 12, quoted from the example's README):
HTTP 403
Content-Type: application/json
WWW-Authenticate: Bearer error="insufficient_scope", scope="uw.decide", resource_metadata="https://mcp.uw.insurer.example/.well-known/oauth-protected-resource", error_description="record_underwriter_decision needs scope uw.decide"
{"jsonrpc": "2.0", "id": 5, "error": {"code": -31403, "message": "insufficient_scope", "data": {"reason": "not_authorized", "check": "scope", "required_scopes": ["uw.decide"], "detail": "record_underwriter_decision needs scope uw.decide"}}}
The header is specified; the body is not, so the example chose a JSON-RPC error with code -31403 and says so in its README.
Normative: a client acting for a user SHOULD re-authorize with the union of the scopes it held and the newly challenged ones, and retry "no more than a few times"; a client using client credentials MAY step up or abort. This is step-up: asking the person for more authority when it is needed, instead of granting everything up front. The cockpit may ask the underwriter for uw.decide. The underwriting agent has nobody to ask, so its client stops; a granted uw.decide would still fail the principal type check on Who gets access.
Case UW-M05 revokes uw.recommend from the underwriting agent between two writes:
$ /opt/homebrew/bin/python3 run_cases.py --case UW-M05 --verbose
case result title key result
UW-M05 PASS A scope revoked between two calls first_write=ok
ok first_write: expected ok, actual ok
ok write_after_revocation: expected 403, actual 403
ok write_after_revocation_code: expected insufficient_scope, actual insufficient_scope
ok read_after_revocation: expected ok, actual ok
ok rows: expected 1, actual 1
1/1 cases match their expected block. (Scripted stand-in model: this shows the protocol and the controls, not model quality.)
The token was not reissued; the server decides every call afresh. A server that cached "this token may write" would have allowed the second write.
Consent: who agreed to what#
Consent is a person's recorded agreement that a specific client may act for them with specific scopes. A tiny example: the underwriter approves, once, that the client uw-cockpit may use uw.decide on their behalf.
Consent sits in three places. Normative (MCP specification 2026-07-28): the host must obtain explicit user consent before invoking any tool, and the specification adds that MCP itself cannot enforce this at the protocol level. In the OAuth flow, the authorization server shows a consent page naming the client. And an MCP server that proxies to a third-party authorization server with one static client id MUST keep per-client consent, or one client's consent can be replayed by another: the confused deputy attack on Threat model. In an enterprise, consent often moves from the person to the organization, which is what enterprise-managed authorization, below, provides.
Calling the assessment service: never pass the token through#
The call is authorized; now the server must reach the assessment service. The opening scene forwarded the same token. Token passthrough is an MCP server forwarding the token it received to another service. The security best practices page calls it "an anti-pattern where an MCP server accepts tokens from an MCP client without validating that the tokens were properly issued to the MCP server and passes them through to the downstream API". The specification forbids it:
Normative (MCP specification 2026-07-28). "The access token used at the upstream API is a separate token, issued by the upstream authorization server. The MCP server MUST NOT pass through the token it received from the MCP client."
For passthrough to work, the service must accept tokens issued for the MCP server. Then every such token is also a key to the service, so the server's per-call policy can be skipped by calling the service directly; the service's audit trail loses the hop; and a token stolen at either hop works at both. The best practices page names the risks: security control circumvention, accountability and audit trail issues, trust boundary issues, future compatibility.
Instead, the server obtains a second token for the second hop. A token exchange is a request in which a service trades a token it holds for a new token, with a different audience and usually less authority, issued by the authorization server under its policy. RFC 8693 (January 2020) standardizes it: grant type urn:ietf:params:oauth:grant-type:token-exchange, with a required subject_token and subject_token_type, and optional actor_token, resource, audience and scope. The example's stand-in, token_exchange() in identity.py:
def token_exchange(caller_claims: dict[str, Any], clock: SimClock, needed_scope: str) -> str:
"""Stand-in for a token exchange at the identity provider: a NEW token for the assessment service.
Audience: the assessment service. Subject: the original caller (so the service and the audit
trail still know on whose behalf). `actor`: this MCP server. Scope: only the one downstream
scope this call needs. Lifetime: 60 s. This example's shape, not a standard's field list.
"""
iat = clock.epoch_s()
claims = {"iss": ISSUER, "sub": caller_claims["sub"], "principal_type": caller_claims["principal_type"],
"client_id": caller_claims["client_id"], "aud": SERVICE_AUDIENCE, "actor": MCP_SERVER_ACTOR,
"scope": DOWNSTREAM_SCOPES[needed_scope], "business_unit": caller_claims["business_unit"],
"iat": iat, "exp": iat + DOWNSTREAM_TTL_S,
"jti": "jti-" + hex_id(f"exchange:{caller_claims['jti']}:{needed_scope}:{iat}", 8)}
if "role" in caller_claims:
claims["role"] = caller_claims["role"]
return sign(claims)
Before the outgoing call, ServiceGateway.call in mcp_server.py runs check_no_passthrough(), which refuses the caller's own token or any token whose audience is not the service. The same scratch script exchanged the valid token for get_roof_assessment and asked both the guard and the service:
token exchange for get_roof_assessment (scope uw.read):
{
"sub": "agent:underwriting-agent",
"aud": "https://assessment-svc.internal.example",
"actor": "svc:uw-assessment-mcp",
"scope": "assessment.read",
"iat": 1794992400,
"exp": 1794992460
}
guard, exchanged token : {'allowed': True, 'reason': 'a separate token issued for the assessment service'}
guard, caller's token : {'allowed': False, 'reason': "token_passthrough: the caller's token may not be forwarded"}
service accepts exchanged: True
service accepts caller's : False
The subject is still the underwriting agent (on whose behalf), the actor names the MCP server (who is calling), the scope covers one operation, and the life is 60 simulated seconds. run_cases.py --case UW-M04 --verbose checks the same on a real HTTP call: downstream_aud is the service, caller_token_forwarded: false. Two limits: the actor claim name is the example's own (RFC 8693's standard claim is act), and the MCP specification does not prescribe exchange; it requires a separate upstream token, and a service credential is the other way to get one (folded below).
The last lab view puts the two layers together: a valid, correctly audienced token, and "check at execution" switched off. The intake agent's write by name goes through. Token validation and per-call authorization are separate controls, and both are required.
| Principal (scopes) | get_roof_assessment | search_guidance | check_eligibility | get_assessment_status | get_assessment_stats | record_recommendation | record_underwriter_decision |
|---|---|---|---|---|---|---|---|
underwriter (uw.read uw.decide, user, cockpit) | L, allowed | L, allowed | L, allowed | refused: scope | refused: scope | refused: scope | L, allowed |
underwriting-agent (uw.read uw.recommend) | L, allowed | L, allowed | L, allowed | refused: scope | refused: scope | L, allowed | refused: scope |
intake-agent (uw.read) | L, allowed | L, allowed | L, allowed | refused: scope | refused: scope | refused: scope (UW-M03) | refused: scope |
audit-agent (audit.read) | refused: scope | refused: scope | refused: scope | refused: scope | refused: scope | refused: scope | refused: scope |
| unknown-agent (no valid token) | 401 | 401 | 401 | 401 | 401 | 401 | 401 |
The table is the recorded run with the check on (L = listed in tools/list). With it off, case UW-M03 returned HTTP 200 and wrote one row. Only the unknown agent's row is decided by token validation alone.
Gateways: an ecosystem pattern, not a protocol role#
An MCP gateway is a proxy that sits in front of one or more MCP servers and applies shared policy: token validation, routing, rate limits, logging, sometimes tool-list filtering. A tiny example: the platform team's gateway in front of uw-assessment, which rejects tokens with the wrong audience and counts calls per client id.
Ecosystem pattern: gateways are common, and the specification does not define them as a role. The Mcp-Method and Mcp-Name headers let infrastructure route and filter without parsing the body (Local and remote). Two consequences follow from the rules above: a gateway that validates and then forwards is bound by the passthrough rule too, and the server cannot hand its per-call decision to the gateway, because only the server sees that SUB-2001 belongs to commercial-east. This site's recommendation: let the gateway reject what any server would reject (no token, wrong audience, expired, over the rate limit) and keep the full authorization in the server. The trade-offs are folded below.
Enterprise-managed authorization#
Standard MCP authorization is per user and per server: each employee signs in and consents for each server, and offboarding means revoking each one. The MCP blog post introducing the extension (18 June 2026, "authorize once, inherit everywhere") adds no consistent policy for security teams, no central audit trail, and work and personal accounts mixing.
Enterprise-managed authorization is an official MCP extension, io.modelcontextprotocol/enterprise-managed-authorization, that "enables organizations to control MCP server access centrally through their existing identity provider (IdP)". The extensions overview lists it at stage Stable, keyed to revision 2026-07-28; like every extension it is opt-in. Four parties take part: the MCP client, the MCP server, the MCP server's own authorization server, and the enterprise identity provider used for single sign-on. The flow, from the extension's specification:
Diagram: Enterprise-managed authorization · the identity provider decides once, the MCP server still checks every call
Read left to right. The person signs in once at the enterprise identity provider. The client exchanges that sign-in for an ID-JAG, a grant addressed to the MCP server's authorization server; the identity provider applies its policy here and refuses servers the person may not use. The client presents the grant and receives an access token restricted to the MCP server, with no consent screen. The MCP server validates and authorizes every call as before.
- Enterprise IdP
- single sign-on: The person signs in to the MCP client with the enterprise identity provider; the client keeps the identity assertion.
- token exchange for an ID-JAG: RFC 8693 exchange with requested_token_type id-jag and audience the MCP server's authorization server. Group membership, roles and conditional access are evaluated.
- MCP server's authorization server
- jwt-bearer grant: The client presents the ID-JAG as assertion with grant type jwt-bearer. Validation steps are defined in the IETF draft (not read here).
- access token audience: MCP server: The issued token is restricted to the MCP server named by the grant's resource claim.
- MCP server
- every call checked as before: The extension changes how the token is obtained, not what the server checks.
- revoke at the IdP: The docs say revocation at the identity provider takes effect across all MCP clients. The identity provider sees issuance only, not MCP traffic.
- The person signs in to the MCP client through single sign-on; the client keeps the identity assertion (an OpenID Connect ID token or a SAML assertion).
- The client asks the identity provider, by RFC 8693 token exchange, for an Identity Assertion JWT Authorization Grant (ID-JAG):
requested_token_typeurn:ietf:params:oauth:token-type:id-jag, the ID token assubject_token,audienceset to the issuer of the MCP server's authorization server. - The identity provider applies its policy (groups, roles, conditional access) and returns the ID-JAG or an error.
- The client presents the ID-JAG to the MCP server's authorization server with grant type
urn:ietf:params:oauth:grant-type:jwt-bearer; no consent page. - That authorization server issues an access token that "MUST be audience-restricted to the MCP Server".
Two statuses must be kept apart. The MCP extension is Stable. The ID-JAG format it relies on is an IETF Internet-Draft, draft-ietf-oauth-identity-assertion-authz-grant, at revision 06 (31 October 2026), not an RFC. The extension defers required claims and validation steps to that draft, which was not read here, and the docs warn that "implementations track different draft revisions".
Enterprise-managed authorization: discovery, revocation, supportHow a client knows the extension is available, what the identity provider sees, and who reports support
The client discovers support through the MCP server's authorization server metadata: the field authorization_grant_profiles_supported contains urn:ietf:params:oauth:grant-profile:id-jag. It declares the extension in each request's clientCapabilities, under extensions, as "io.modelcontextprotocol/enterprise-managed-authorization": {}. The MCP server's authorization server validates the ID-JAG's signature against the identity provider's keys, its audience, issuer and expiry, maps claims to permissions, and uses the subject claim as the stable user identifier (the email claim only to link pre-existing accounts).
Revocation happens at the identity provider; the docs say it takes "effect immediately across all MCP clients". Read that with the access token's lifetime in mind: the specification's example uses a 300-second ID-JAG and an access token with expires_in 86400, labelled non-normative. A token already issued is valid at the MCP server until it expires unless the server also learns of the revocation, so short access-token lifetimes matter here too. The specification's security note adds that the identity provider sees token issuance only, not MCP traffic.
Support, as reported on 2026-11-18: the MCP blog names Okta as the first identity provider (calling it Cross App Access) and lists clients and servers adding support; the MCP docs keep a longer table of vendors with their own release labels, described as not comprehensive. Those lists were not re-checked on each vendor's site. The draft is informally called Cross-App Access (XAA).
For the insurer, policy moves: the enterprise identity provider decides "underwriters may use the cockpit with uw-assessment" once, and offboarding is one change. The server's own checks do not move.
One vendor's documented setup: Microsoft Entra#
Vendor feature (as documented on 2026-11-18): Microsoft's Entra Agent ID documentation has a page on securing an MCP server with Entra ID. It opens: "An MCP server is an OAuth 2.0 protected resource. Register the server as an API in Microsoft Entra ID, publish protected-resource metadata, and validate each access token before processing an MCP request." Its steps map one to one onto this page: metadata, an authorization server URL, validation with audience, 401 and 403, and a separate token downstream.
Entra's steps next to this page's stepsVendor documentation as read on 2026-11-18, row by row
| This page's step | Entra's documented step |
|---|---|
| Protected resource metadata | publish <server-url>/.well-known/oauth-protected-resource with resource (the Application ID URI, which must match the expected aud), authorization_servers, scopes_supported (example mcp.access), bearer_methods_supported ["header"] |
| Authorization server | https://login.microsoftonline.com/<tenant>/oauth21/2026-08 (tenant id, or common for any organization) |
| Audience and validation | validate signature, issuer, audience, lifetime, tenant, client and permissions; delegated scopes in scp, application permissions in roles |
| 401 and 403 | middleware returns 401 for a missing or invalid token; the policy returns 403 when a valid token lacks both the scope and the role |
| Downstream call | "Test each endpoint with a token issued for this downstream API, not the agent's inbound token." |
| Client registration | registered Agent ID, a local public client with PKCE, or a CIMD URL "when preregistration isn't practical" |
Three cautions from the same pages: the guidance supports Microsoft identity platform v2.0 access tokens only; Entra's CIMD support "is in public preview" and "isn't recommended for production workloads"; and the page links the MCP authorization specification at revision 2025-06-18. The pages do not name the authorized-party claim or the Agent ID relationship claims they ask servers to check, or say how the MCP server obtains its downstream token beyond "a token issued for this downstream API"; this page does not fill those gaps.
What the NSA's guidance adds#
The NSA published a Cybersecurity Information Sheet, "Model Context Protocol (MCP): Security Design Considerations for AI-Driven Automation" (https://media.defense.gov/2026/Jun/02/2003943289/-1/-1/0/CSI_MCP_SECURITY.PDF, archived copy read 2026-11-18; footer: May 2026, version 1.0). On authorization it notes that bearer tokens come without protocol-level lifecycle management (refresh, revocation, reuse control) and that many implementations omit authentication or role-based enforcement. It recommends separate trust zones, caution with dynamic tool discovery unless coupled with authorization checks, and logging every tool invocation with parameters and identities. It cites revision 2025-11-25, so date its protocol details; its operational advice still applies.
What goes wrong without these ideas#
Without the audience check, any token from the same identity provider works, including one issued to the CRM (UW-M04). Without the resource parameter, there is no audience to check. Without per-call scope checks, a revoked write keeps working until the token expires (UW-M05). Without the 401-versus-403 distinction, clients retry forbidden calls with fresh tokens. Without the passthrough rule, the service accepts every token issued for the MCP server, and the server's policy becomes optional. Without the issuer comparison and PKCE, the sign-in itself can be redirected or replayed.
In a coding agent. A company's remote code review server works likeuw-assessment: the coding agent's client gets a 401, reads the metadata, and obtains a token withresourceset to the review server, so it cannot be replayed at the deployment server.open_pull_requestanswers 403insufficient_scopeuntil the developer steps up. The review server calls the source host with its own token, never the developer's. Harness Engineering shows where the client and these servers sit in the agent's runtime.
What this is not. This page covers how tokens for MCP are obtained, bound and checked. Who should hold which permission (principals, delegation, RBAC and ABAC, tenants) is Who gets access. Scopes inside one application's tool loop are on Tools Engineering: safety. Attacks such as the confused deputy and SSRF through metadata URLs are on Threat model.
Security and governance notes#
Security note. A client running on a server fetches URLs other servers gave it (resource_metadata,authorization_servers); the best practices page warns these can point at internal targets such ashttp://169.254.169.254/and asks for HTTPS, blocked private and link-local ranges, and validated redirects. Store tokens securely, never log them (the example logs only thejti), and keep lifetimes short.
Governance note. Identity and security governance owns the authorization server's configuration (registered clients, trusted CIMD domains, scopes and who may hold them); the server maintainer owns the metadata and the per-call policy; the platform team owns the gateway. Log each step-up grant with a correlation id, as the best practices page recommends (Observability).
Checklist for Monday#
- Protected resource metadata is published; the 401 names it;
scopes_supportedis minimal. - Clients send
resourcein both requests, use PKCE withS256, and compare the issuer. - Every request: signature, issuer, audience, expiry, revocation. Every call: scopes and attributes.
- 401 means get a new token; 403 means step up if a person can grant it, or stop.
- No outgoing request carries the caller's token; a test asserts it (ADR-004 on Playbooks).
- Gateway and server checks come from one policy source; the server keeps the per-call decision.
Exercises#
- A client gets a token without the
resourceparameter because "our identity provider ignores it anyway". What does the specification say, and what breaks later? - A server receives a valid token for its own audience with scope
uw.read, forrecord_recommendation. Which status code, which header, and what should the underwriting agent's client do? - The assessment service team says: "accept the MCP server's audience too, it saves a token exchange". What do you lose?
AnswersOne line each
- Clients MUST send it regardless of support; without it the token carries no audience for this server, so it can be replayed at any service that trusts the same identity provider, and adding audience checks later breaks every client.
- 403 with
WWW-Authenticate: Bearer error="insufficient_scope", scope="uw.recommend", resource_metadata=...; the agent's client stops, since no person can grant it and retrying cannot help. - Every token issued for the MCP server becomes a key to the service, so the server's per-call policy can be bypassed, the service's audit loses the hop, and the specification's passthrough rule is broken in spirit and in letter.
Step-up in practiceUnion of scopes, retry limits, who can be asked, and what to log
Step-up looks small in the specification and is where clients misbehave. Three rules from the material read today shape it. The client treats the challenged scopes as authoritative for the operation. A client acting for a user re-authorizes with the union of what it held and what was challenged, so a person who granted uw.read this morning and uw.decide now does not lose uw.read. And the client retries "no more than a few times"; the specification gives no number. This site's recommendation: one step-up per operation; if the second attempt is still 403, show the person the reason from error_description and stop.
Who can be asked matters more than how. A person in the cockpit can be asked to grant uw.decide, because the person holds the role. The underwriting agent cannot be asked anything; a 403 for it is a design fact, not a transient fault. A client using client credentials MAY step up (request a token with more scopes, if its registration allows) or abort. Abort is the right default for workloads, because a workload that can raise its own privileges at runtime has privileges nobody reviewed.
Servers MUST account for scope hierarchies when they compute what to challenge. The example has none (and its README lists hierarchies as not implemented); a real platform with uw.write implying uw.recommend must challenge the narrowest scope that satisfies the call, or every step-up becomes a request for the broadest scope. Log each elevation with the correlation id, the scope granted and the person who granted it: an audit that shows a decision without showing how the decider obtained the authority is incomplete.
Gateway validation or per-server validation?What centralizing token checks buys, what it costs, and the split that holds up
A platform team running twenty MCP servers is tempted to validate tokens once, at the gateway, and let servers trust the gateway. The benefits are real: one JWKS cache, one revocation feed, one place to patch a validation bug, consistent 401s, rate limits per client id before any server spends a cycle.
The costs are structural. If servers trust the gateway, a request that reaches a server by another path (a misrouted internal call, a debug port, a compromised neighbor) arrives with no checks at all. If the gateway forwards the caller's token to the server, that token's audience must be the server, not the gateway, or the server is accepting a token not issued for it. If the gateway mints a new internal token, it has become an authorization server for the internal hop and needs the same care as one. And the gateway cannot make tenant decisions without the domain data, so the server still needs its own policy.
The split that holds up under those constraints: the gateway rejects early what any server would reject (missing, malformed, expired, wrong-audience tokens; over-limit clients; header-body mismatches), and every server validates the token again for its own audience and runs its full per-call authorization. Validating twice costs a signature check per hop. Not validating at the server costs the property this page is built on: a server accepts only tokens issued for it. Derive both layers' policies from one source, so the gateway never allows what the server refuses.
Token exchange or a service credential for the downstream call?Two ways to get the separate token the specification requires, and what each keeps
The specification requires a separate token for the upstream API and forbids passthrough. It does not say how to get the separate token. There are two common answers.
A service credential: the MCP server authenticates as itself (client credentials) and gets a token with the service as audience and the server as subject. Simple, cacheable, no per-call round trip to the identity provider. What it loses is the caller. The service sees every request as "the MCP server", so its own authorization can only trust the MCP server's decision, and its audit trail cannot say which agent or person asked. If the server has a bug, the service cannot catch it. This fits services that hold no per-caller data or that deliberately delegate all authorization to the MCP server.
Token exchange: the server trades the caller's token for a new one with the service as audience, the caller as subject and the server as actor, narrowed to one scope. The service can apply its own policy on the real caller, and both identities appear in its audit trail. The cost is one more call to the identity provider per downstream call (cacheable per caller and scope for the token's short life), an identity provider that supports RFC 8693 and has exchange policy configured, and claims design: the example's actor claim is its own, while RFC 8693 defines act. The example uses exchange because the assessment service is the domain data owner's system and should be able to refuse a call on its own.
A third answer is a mistake: impersonation, where the exchanged token makes the server indistinguishable from the caller. RFC 8693 describes impersonation as A receiving all the rights B has; it erases the hop the passthrough rule exists to keep visible.
Several identity providers, several tenantsIndependent authorization servers, credentials keyed by issuer, and multi-tenant issuers
Large insurers rarely have one identity provider. Acquisitions bring their own; partners sign in with theirs; a workforce provider and a customer provider coexist. The specification has rules for this. A protected resource metadata document may list several authorization servers; clients MUST treat them as independent and keep separate registration state for each. Pre-registered or dynamically registered client credentials MUST be keyed by the authorization server's issuer and MUST NOT be reused with a different one. CIMD client ids are portable across authorization servers, because each one resolves the same URL.
Multi-tenant issuers add a subtlety. Entra's documented authorization server URL takes a tenant id or common. A server that accepts common accepts tokens from any organization's tenant unless it also checks the tenant claim; Entra's own checklist includes "tenant" among the things to validate. The general rule: an issuer that serves many tenants needs an allowlist of tenants at the server, or the audience check alone admits everyone who can register an application.
For the server, every accepted issuer is a trust decision with an owner. This site's recommendation: list accepted issuers and tenants in configuration under identity governance's change control, map each issuer's claims to the server's principal model explicitly (one issuer's group claim is not another's role), and test that a token from an unlisted issuer gets 401 even when its signature, audience and scopes are otherwise perfect.
Why the issuer comparison matters even with PKCEMix-up attacks, the order of checks in the browser step, and what PKCE does not cover
A client that talks to several authorization servers can be tricked by one of them. In a mix-up attack, a malicious authorization server gets the client to send it an authorization code or token that an honest server issued. The security best practices page is explicit that "PKCE alone does not prevent this attack", and that resource indicators do not help when the attacker's server intercepts first. The mitigation is the issuer comparison: the client records the expected issuer before redirecting, and compares the iss in the authorization response with it.
The nuance from revision 2026-07-28: authorization servers SHOULD include iss in responses (RFC 9207) and, if they do, MUST advertise authorization_response_iss_parameter_supported: true. Clients MUST compare a present iss and MUST reject a missing one only when the server advertises support. On 2026-11-18, Entra's live common/oauth21/2026-08 discovery document advertised authorization_response_iss_parameter_supported: false, so a client talking to it relies on the other defences: exact redirect URIs, per-server registration state and the metadata issuer check.
The browser step also carries its own client-side rules from the best practices page: allow only https:// (and loopback http:// in development) for authorization URLs, reject javascript:, data:, file: and vbscript:, and never open a URL through a shell command. A local MCP client that opens whatever URL a server sends is a remote code execution waiting for the wrong server.
In one breath#
An HTTP MCP server is an OAuth resource server: its 401 points to protected resource metadata, and the client discovers the authorization server, registers, signs the person in with PKCE and names the server in resource. The server accepts only tokens issued for its own audience, checks scopes on every call, answers 401 for a bad token and 403 for a good token that is not enough, and never passes the caller's token downstream. Gateways and enterprise-managed authorization move checks and policy to shared places; the server's own decision stays on every call.
The tokens now say who is calling and for which server, and every hop carries its own. What tokens cannot stop is a caller with a perfectly valid token doing something it was manipulated into: text in a retrieved passage that asks for a decision, a tool description that changes after approval, a server that is not who it claims, a metadata URL aimed at an internal address. Those threats, each with the control and the layer that owns it, are Threat model.