At 10:00 on a Wednesday, security operations suspends one grant. Precedent DOC-PREC-W-03 moved under legal hold this morning, and until the records team sorts out what may be read, the underwriting agent should not search precedents at all. The change is one line in the tool server's grant list: wl-underwriting-agent:find_similar_decisions, revoked.
At 10:02 a platform engineer opens a ticket. The underwriting agent's host still lists find_similar_decisions among its tools. The engineer's conclusion: "the revocation did not work".
The revocation worked. The agent's token still carries the scope uw.read, so the tool server still lists the tool when the agent's client asks what it may see. But when the agent application sends the call, the tool server checks the grant again and answers 403: "grant revoked for wl-underwriting-agent:find_similar_decisions (checked on every call, not only at discovery)". The list was a description. The call was a decision.
Many teams build the opposite design first: remove revoked tools from the list and trust that a client cannot call a tool it was not shown. That server looks correct on the dashboard and executes the call. This page is about the gap between "the caller can see the tool" and "the caller may use it on this record, now", and the identity rules MCP adds around it.
What an MCP server has to decide#
MCP, the Model Context Protocol, is an open protocol through which an AI application (the host) connects to servers that offer tools, resources and prompts. A tiny example: the underwriting agent's host connects to the insurer's tool server and sees a tool named get_roof_assessment.
An MCP server is the program that offers those capabilities and runs them when a client calls. Here it is the insurer's underwriting tool server, reached at https://mcp.uw.insurer.example. It is the place where a model's suggestion becomes a real read or a real write.
Tool discovery is the step in which a client asks a server which tools exist, with tools/list, and the server answers with names, descriptions and argument schemas. A tiny example: the intake agent's client asks and receives three tool names.
A shared MCP server answers the questions of any API on every call: who is calling, for whom, which tool, which record, allowed now? Two facts make it harder. Many different callers share it. And a model, which anything it has read can steer, writes the text that chooses the tool.
Before AI. An OpenAPI document lists every endpoint of a Spring service, and nobody believes the listing authorizes anything: the filter chain and@PreAuthorizedecide each request.tools/listis the same kind of listing. MCP adds a standard way for unknown clients to find where tokens come from, and an explicit rule against forwarding the token you received.
The MCP protocol itself, its transports, catalogs and governance in depth, is taught on MCP Engineering. This page keeps to identity and authorization, and to how they connect with the rest of this site.
Two transports, two trust models#
The MCP specification separates local servers from remote ones, and the authorization rules follow that split.
A local server runs on the user's machine as a child process of the host and talks over standard input and output (stdio). Standard (MCP specification 2026-07-28, read 2026-11-18): "Authorization is OPTIONAL for MCP implementations." When it is supported, "Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment." Implementations using an HTTP-based transport "SHOULD conform to this specification".
Stdio trust is the trust model that follows from that sentence: a stdio server has no network listener and no token; it runs with the operating system rights of the user who started it, and whatever credentials it reads from its environment. A tiny example: a developer runs a local copy of a document tool; it can read every file the developer can read.
The boundary is therefore the operating system account, not the protocol. The process can do anything that account can do, so the questions are the ones you would ask about any program you install: who wrote it, what it can reach, and which credentials sit in its environment. Standard (MCP security best practices, read 2026-11-18): a client that offers one-click local server setup MUST show the exact command without truncation, flag it as potentially dangerous, require explicit approval and allow cancel, and SHOULD run servers sandboxed with minimal privileges; developers of local servers SHOULD use stdio, so that only the MCP client can reach the server, or restrict HTTP access with a token or Unix domain sockets.
A remote server listens on HTTP and is shared by many callers. Nothing about the network tells it who is calling, so every request carries an access token, and the server is an OAuth resource server.
In our insurance example. The underwriting tool server is remote on purpose. A local copy would need database credentials on every laptop that runs it; the remote server holds no database credential either, and reaches data only through the domain services, each of which decides again.
The smallest primitive: one call, two answers#
The example's mcp_matrix.py models the auth-centred part of a tool server: a catalog of six tools, five callers, and two functions. It is a teaching model, not an MCP server; it speaks no JSON-RPC and validates no tokens (its callers are already verified subjects, built the way Tokens shows). The protocol-level example, with real HTTP messages, lives on MCP Engineering.
discover decides what a caller sees, by scope, principal type and required client. execute decides a call, and re-checks everything whether or not the tool was listed. Quoted from mcp_matrix.py, function execute:
def execute(subject: dict[str, Any], tool_name: str, args: dict[str, Any], *, revoked: list[str] | None = None,
now: int = START_EPOCH_S, catalog: list[dict[str, Any]] = CATALOG) -> dict[str, Any]:
"""tools/call: re-check everything, listed or not. Returns {tool, listed, allowed, status, check, rule, reason}."""
tool = next((t for t in catalog if t["name"] == tool_name), None)
listed = tool_name in discover(subject, catalog)
base = {"tool": tool_name, "listed": listed}
if tool is None:
return {**base, "allowed": False, "status": 404, "check": "tool", "rule": None, "reason": "unknown tool"}
key = str(subject.get("principal_id")) + ":" + tool_name
if key in (revoked or []):
return {**base, "allowed": False, "status": 403, "check": "grant", "rule": None,
"reason": "grant revoked for " + key + " (checked on every call, not only at discovery)"}
if tool["scope"] not in (subject.get("scopes") or []):
return {**base, "allowed": False, "status": 403, "check": "scope", "rule": None,
"reason": "insufficient_scope: " + tool["scope"] + " required"}
d = pdp.decide(subject, tool["action"], resource_of(tool, args), {"now": now})
return {**base, "allowed": d["allow"], "status": d["status"], "check": "pdp", "rule": d["rule"], "reason": d["reason"]}
Four checks in a fixed order: the tool exists, the grant is not revoked, the token carries the tool's coarse scope, and then the policy decision point decides on the resource named by the arguments. The last step is the one that knows records. A scope says "may read underwriting data in general"; only the decision point knows that SUB-2001 belongs to commercial-east.
A short script (in a scratch copy of examples/uw-auth, run on 2026-11-18) asks both functions about the intake agent, whose token carries only uw.read:
import mcp_matrix as m
from clock import START_EPOCH_S as NOW
ro = m.subjects(NOW)["read_only_agent"]
print("intake agent sees:", m.discover(ro))
for tool, args in [("record_recommendation", {"submission_id": "SUB-1004"}),
("get_roof_assessment", {"submission_id": "SUB-1004"})]:
r = m.execute(ro, tool, args, now=NOW)
print(tool, "listed", r["listed"], "allowed", r["allowed"], r["status"], r["check"], r["rule"], "|", r["reason"])
intake agent sees: ['get_roof_assessment', 'search_guidance', 'find_similar_decisions']
record_recommendation listed False allowed False 403 scope None | insufficient_scope: uw.recommend required
get_roof_assessment listed True allowed False 403 pdp R-AZ-05 | reading an assessment needs a delegated task
Read the two refusals side by side. The first tool was hidden and is refused at the scope check: a hidden tool called by name gains nothing. The second tool was listed and is still refused, by rule R-AZ-05, because reading a roof assessment needs a delegated task and the intake agent has none. Discovery said yes; execution said no. Both outcomes are correct, and neither could have come from the list alone. The run proves the order of the checks; it does not prove the policy is complete. The same lesson over real HTTP, case UW-M03, is on MCP Engineering: who gets access.
Diagram: Two moments, two answers · discovery describes, execution decides
Read left to right. Discovery answers tools/list from the caller's scopes and type; the result is cached and has no arguments. The call arrives later with a tool name and arguments, listed or not. The tool server checks the grant, the scope, then asks the PDP about the record the arguments name. Only the right-hand lane protects data: a hidden tool called by name and a revoked grant are both refused there.
- Discovery (tools/list)
- filter by scope, type and client: The server computes which tools this caller sees, from the token's scopes, its principal type and the client it came through.
- cached list, no arguments: The list is computed once and cached; it cannot say which record or until when.
- Execution (tools/call)
- grant revoked?: Per-caller, per-tool grants are checked on every call, not only at discovery.
- scope in token?: The coarse permission name must be in the validated token, or the call is refused before any record is read.
- PDP on the record from the arguments: The tool server builds the resource from the arguments and the system of record; the policy decision point decides on it.
- Outcome
- allowed, or refused with a reason: Each call returns a status, the check that decided and the rule, and is written to the audit trail without the token.
Remote MCP: the token must name this server#
For a remote server, the specification builds on OAuth, which OAuth and OIDC explains. The MCP-specific parts are about one thing: making sure a token works at exactly one server.
Protected resource metadata is a small JSON document, defined by RFC 9728, in which a protected resource says what it is and which authorization servers issue tokens for it. A tiny example: https://mcp.uw.insurer.example/.well-known/oauth-protected-resource names https://idp.insurer.example as its authorization server. Standard (MCP specification 2026-07-28): MCP servers MUST implement it, and MCP clients MUST use it for authorization server discovery. A client that knows nothing sends a request, receives a 401 whose WWW-Authenticate header points at the document, reads it, and then fetches the authorization server's own metadata.
A resource indicator is the resource parameter of RFC 8707, with which a client tells the authorization server which resource the token is for. A tiny example: resource=https://mcp.uw.insurer.example in both the authorization request and the token request. Standard (MCP specification 2026-07-28): clients MUST include it in both requests, with the server's canonical URI, and "MUST send this parameter regardless of whether authorization servers support it". The token's audience then names one server.
On every request, the server checks that audience. Standard (MCP specification 2026-07-28): "MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2." Invalid or expired tokens MUST receive HTTP 401. And two sentences that carry most of this page:
Standard (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."
A valid token that is not enough gets a different answer. Standard: for a call that needs more scope, the server SHOULD respond with 403 Forbidden and WWW-Authenticate: Bearer error="insufficient_scope", the needed scope, the resource_metadata URI and an optional error_description. A client acting for a user SHOULD then step up: re-authorize with the union of the scopes it had and the challenged ones, and retry "no more than a few times". A client acting on its own behalf MAY step up or abort. Written from the specification read today (not run here), the intake agent's call by name looks like this on the wire:
POST /mcp HTTP/1.1 (the intake agent's MCP client)
Host: mcp.uw.insurer.example
Authorization: Bearer <access token: aud https://mcp.uw.insurer.example, scope uw.read>
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="uw.recommend", resource_metadata="https://mcp.uw.insurer.example/.well-known/oauth-protected-resource", error_description="record_recommendation needs scope uw.recommend"
The intake agent's client should stop: no person stands behind it who could grant uw.recommend. The full walk from the first 401 to a working token, with registration, PKCE and the issuer check, is on MCP Engineering: authorization.
Common confusion. 401 means "bring a valid token"; 403 means "your token is valid and this is still not allowed"; another unit's record is answered as not found, so its existence stays hidden (Authorization).
In the insurance example: who may call what#
The lab below is the example's matrix: five callers, six tools, and for each cell two answers, listed by discovery and allowed at execution. Select a cell to see who sends the call, which check decided and why. The agent here is a scripted stand-in, so these results show how the access controls work, not how good any model is.
The recorded matrix ("scope" means refused by the tool server's scope check before any record is read):
| Caller | get_roof_assessment | search_guidance | find_similar_decisions | record_recommendation | record_underwriter_decision | read_audit_log |
|---|---|---|---|---|---|---|
| Broker (portal) | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope |
| Intake agent (read-only) | listed, refused 403 R-AZ-05 | listed, allowed | listed, refused 403 R-AZ-06 | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope |
| Underwriting agent (run-7f3a) | listed, allowed | listed, allowed | listed, allowed | listed, allowed | hidden, refused 403 scope | hidden, refused 403 scope |
| Underwriter via cockpit | listed, allowed | listed, allowed | listed, allowed | hidden, refused 403 R-AZ-08 | listed, allowed | hidden, refused 403 scope |
| Auditor | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope | hidden, refused 403 scope | listed, allowed |
Read it by columns as well as rows. record_underwriter_decision has exactly one "allowed", and it is a person: the underwriter, through the cockpit. record_recommendation has exactly one too, and it is the agent. The underwriter's token carries uw.recommend (so the underwriter can delegate it to the agent), and the decision point still refuses a person writing a recommendation, rule R-AZ-08. The model recommends; a person decides, and the matrix makes that sentence checkable.
The broker sees nothing: brokers use the portal's API (Enforcement), never the internal tool server.
Argument-dependent policy: the same tool, three records#
A tool name is not enough to decide. record_recommendation is allowed for the underwriting agent, but on which submission? The agent of run run-7f3a acts for underwriter u-uw-w1 with a task that names SUB-1004. The same script continues:
ag = m.subjects(NOW)["underwriting_agent"]
for args in [{"submission_id": "SUB-1004", "recommendation": "refer"},
{"submission_id": "SUB-1007", "recommendation": "refer"},
{"submission_id": "SUB-2001", "recommendation": "approve"}]:
r = m.execute(ag, "record_recommendation", args, now=NOW)
print("record_recommendation", args["submission_id"], r["status"], r["rule"], "|", r["reason"])
r = m.execute(ag, "record_underwriter_decision", {"submission_id": "SUB-1004", "decision": "approve"}, now=NOW)
print("record_underwriter_decision (agent)", r["listed"], r["status"], r["check"], "|", r["reason"])
record_recommendation SUB-1004 200 R-AZ-08 | agent records a recommendation for SUB-1004 inside its delegated task
record_recommendation SUB-1007 403 R-AZ-08 | submission SUB-1007 is outside the delegated task (task names SUB-1004)
record_recommendation SUB-2001 404 R-AZ-08 | record belongs to another business unit: not found (existence not revealed)
record_underwriter_decision (agent) False 403 scope | insufficient_scope: uw.decide required
Three calls to one tool, three answers, all decided by the arguments. SUB-1007 is in the agent's own unit but outside its task: 403. SUB-2001 is in another unit: 404, so the agent learns nothing about whether it exists. This is argument-dependent policy: the tool server builds the resource from the call's arguments and the system of record (resource_of in mcp_matrix.py), and the decision point decides on that resource.
The last line is the decision tool. The agent never sees it and is refused at the scope check. The example adds a second wall: with uw.decide granted to the agent by mistake, rule R-AZ-09 still refuses, because a decision needs a person with role underwriter, assigned to the submission, through svc-cockpit-bff, after step-up (test_negative.py, class Dod5NoProtectedWriteByAgent). This site's recommendation: put the principal type into the rule for every irreversible write, so that a mistaken scope grant cannot hand a person's decision to a workload. Who may change that rule over time is on MCP Engineering: governance.
The cockpit condition matters for people too. The lab's offcockpit preset has the underwriter call from a script instead of through the cockpit backend.
| Caller | Tool | Discovery | Execution | Rule and reason |
|---|---|---|---|---|
| Underwriter via cockpit | record_underwriter_decision | listed | allowed | R-AZ-09: assigned underwriter decides through the cockpit after step-up |
| Underwriter from a script | record_underwriter_decision | hidden | refused 403 | R-AZ-09: decisions are accepted only through svc-cockpit-bff |
Same person, same role, same assignment. The cockpit shows the evidence, the recommendation and the step-up prompt; a script shows none of them.
Revocation is checked on every call#
Back to the opening. The revoked preset revokes one grant, wl-underwriting-agent:find_similar_decisions, and starts on that cell.
| Caller | Tool | Grant | Discovery | Execution |
|---|---|---|---|---|
| Underwriting agent (run-7f3a) | find_similar_decisions | active | listed | allowed (R-AZ-06, inside unit commercial-west) |
| Underwriting agent (run-7f3a) | find_similar_decisions | revoked | listed | refused 403: grant revoked (checked on every call, not only at discovery) |
This site's own case UW-A21 checks the three properties together: a hidden tool called by name is refused at the scope check, a revoked grant is refused although the tool is still listed, and the auditor's attempt to write is refused 403. Run in the scratch copy:
$ /opt/homebrew/bin/python3 run_cases.py --case UW-A21 --verbose
case result title first check
UW-A21 PASS MCP: discovery is not authorization hidden_tool={"listed": false, "allowed": false, "...
ok hidden_tool: expected {"listed": false, "allowed": false, "check": "scope"}, actual {"listed": false, "allowed": false, "check": "scope"}
ok revoked_grant: expected {"listed": true, "allowed": false, "check": "grant"}, actual {"listed": true, "allowed": false, "check": "grant"}
ok auditor_write: expected {"allowed": false, "status": 403}, actual {"allowed": false, "status": 403}
1/1 cases match their expected block. (Scripted stand-in agent: this shows the access controls, not model quality.)
The revoked tool stays listed because the example's discovery filters by scope, and the token still carries uw.read. A real server should also hide it, so the model stops proposing it; hiding is a convenience, and the execution check is the control. Revoking the token itself is a different, slower lever, with the revocation window Tokens describes.
Production pitfall. A server that caches "this caller may use these tools" for the life of a token keeps a revoked grant working until the token expires. Decide each call afresh, or cache decisions only for seconds and invalidate the cache on every grant change (Operations).
Never pass the token through#
The call is allowed; now the tool server must reach the assessment service, which holds the roof reports. The tempting shortcut is to forward the token it received.
Token passthrough is an MCP server forwarding a token it received from a client to another service. A tiny example: the tool server sends the agent's token, audience https://mcp.uw.insurer.example, on to the assessment service. Standard (MCP security best practices, read 2026-11-18): token passthrough is "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 authorization specification's security considerations forbid it:
Standard (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 assessment service would have to accept tokens issued for the tool server. Every such token becomes a key to the service: a holder could skip the tool server's per-call policy, the service's audit would lose the hop, and a stolen token would work at both. The example's guard, check_no_passthrough in mcp_matrix.py, refuses both forms, and the last line of the script asks it three times:
MCP = "https://mcp.uw.insurer.example"
SVC = "https://assessment-svc.internal.example"
print(m.check_no_passthrough(MCP, MCP, same_token=True))
print(m.check_no_passthrough(MCP, MCP, same_token=False))
print(m.check_no_passthrough(SVC, MCP, same_token=False))
{'allowed': False, 'reason': "token passthrough: the caller's token may not be forwarded"}
{'allowed': False, 'reason': 'the downstream token must be issued for the downstream audience'}
{'allowed': True, 'reason': 'a separate token issued for https://assessment-svc.internal.example'}
The specification requires a separate token and does not say how to obtain it. Two ways exist. Pattern: the tool server authenticates as itself with client credentials, which is simple and loses the caller. Pattern: token exchange (RFC 8693), in which the tool server trades the caller's token for a new one with the downstream audience, the caller as subject and itself as actor; the assessment service can then decide on the real caller. Token exchange itself is explained on OAuth and OIDC. This site's recommendation: use exchange where the downstream service owns the data and should be able to refuse on its own; use the service's own credential only where the downstream holds no per-caller data.
User delegation through the tool server#
The underwriting agent is a workload with its own identity, wl-underwriting-agent. When it works on SUB-1004 it acts for a person, u-uw-w1, and the tool server must know both. In the example the agent's token comes from a token exchange: the underwriter's token is the subject, the agent's own token is the actor, the audience is https://mcp.uw.insurer.example, and the scope is narrowed to uw.read uw.recommend. A request for uw.decide is refused with invalid_scope, and a request aimed at the LLM gateway with invalid_target (this site's own case UW-A22).
The tool server sees a subject (the person), an actor (the agent) and a task (run-7f3a, SUB-1004, four actions, an expiry), and decides on all three, never on the agent's identity alone. Delegation chains, task tokens and approvals are the subject of Agents.
Diagram: One tool call for run-7f3a · a token for this server, a separate token for the next hop
Time runs down the page. The model writes the call; the agent application sends it with a delegated token whose audience is the tool server. The tool server validates the audience, checks grant and scope, and asks the PDP about SUB-1004 inside the task. To read the roof report it obtains a separate token for the assessment service. The caller's token never travels on.
- Agent application to MCP tool server: tools/call get_roof_assessment SUB-1004. Bearer token with audience the tool server, subject the person, actor the agent.
- MCP tool server: audience, grant, scope. A token for any other audience gets 401; a revoked grant or missing scope gets 403.
- MCP tool server to PDP: assessment.read on SUB-1004?. The resource comes from the arguments and the system of record.
- PDP to MCP tool server: allow 200 (R-AZ-05). Inside the delegated task. SUB-2001 would get 404 without revealing it exists.
- MCP tool server to Token service: separate token for the assessment service. The caller's token is never forwarded; the downstream hop gets its own token.
- Token service to MCP tool server: token: aud assessment service. Narrow, short-lived, for one audience.
- MCP tool server to Assessment service: read roof report. The service validates its own audience and can apply its own policy.
- Assessment service to MCP tool server: assessment. The result returns to the agent as data; a person later decides.
The confused deputy#
A confused deputy is a program with authority that is tricked into using it for someone who lacks that authority. The classic shape predates AI: a compiler allowed to write a billing file, asked by a user to write its output "to the billing file". An MCP deployment has three versions of it.
The first is the one the specification spells out. Standard (MCP security best practices): an MCP proxy server that uses one static client id at a third-party authorization server is vulnerable when it also lets clients register dynamically, the third-party server sets a consent cookie, and the proxy keeps no per-client consent. Such proxies MUST keep a registry of approved client_id values per user and check it before starting the third-party flow, show a consent page naming the client, its scopes and its redirect_uri, and match redirect URIs exactly.
The second is token passthrough, above: a downstream service that accepts a token never meant for it becomes the deputy.
The third is the agent itself. The underwriting agent holds real authority: it may store recommendations for SUB-1004. Injected text in a retrieved passage (series case UW-005) asks it to record a decision and to recommend for SUB-2001. The agent's client sends both calls, and the tool server refuses both, by scope and by unit (steps 6 and 7 of agent.py). The deputy is the agent, and the tool server is the place that can tell "the agent asked" from "the agent may". Each attack, its control and the layer that owns it are on MCP Engineering: threat model.
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. Enterprises want one place for the decision.
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)". A tiny example: the insurer's identity provider decides once that underwriters may use the cockpit with the underwriting tool server, and an underwriter who leaves loses that access in one place.
The flow, in short: the person signs in to the MCP client through single sign-on; the client asks the identity provider, by RFC 8693 token exchange, for an Identity Assertion JWT Authorization Grant (ID-JAG) aimed at the MCP server's authorization server; the identity provider evaluates its policy and returns the grant or an error; the client presents the grant to the MCP server's authorization server with the JWT bearer grant type, without sending the person to a consent page; that server issues an access token audience-restricted to the MCP server.
Two statuses must be kept apart, and this page states both. Standard (MCP extensions overview, read 2026-11-18): the extension is at stage Stable, keyed to protocol revision 2026-07-28; like every extension it is opt-in and "never active by default". Standard (IETF draft, read 2026-11-18): the ID-JAG it relies on is defined in draft-ietf-oauth-identity-assertion-authz-grant, an Internet-Draft at revision 06 (31 October 2026), not an RFC. The extension's documentation warns that "Implementations track different draft revisions".
The decision "may this person use this server through this client" moves to the identity provider. The tool server's own checks do not move: audience on every request, grant, scope and record on every call. Discovery fields and reported vendor support are on MCP Engineering: authorization.
Diagram: Who requires what · standard, pattern, this site's recommendation
Rows are the three kinds of claim this page keeps apart. Columns are where the rule bites: who the caller is, what happens on each call, and the next hop. Read down a column: the standard fixes the floor, a pattern is an optional way to build on it, and the recommendation is advice, never the standard.
- Standard
- stdio: environment HTTP: OAuth, audience: stdio should not follow the authorization specification; HTTP servers publish protected resource metadata and accept only tokens for their own audience.
- 403 insufficient_scope, step-up: A valid token without the needed scope gets 403 with the scopes the operation needs; user clients re-authorize with the union.
- no token passthrough: The upstream token is a separate token; the server must not pass through the one it received.
- Pattern
- enterprise IdP decides centrally: Stable MCP extension built on the ID-JAG IETF draft; opt-in.
- gateway rejects the obvious: No protocol role; validates and rate-limits before servers, never replaces their decision.
- token exchange or service credential: Two ways to get the separate downstream token; exchange keeps the caller visible.
- This site's recommendation
- short tokens, named principal types: Keep MCP access tokens short-lived and put the principal type into rules for irreversible writes.
- grant + PDP on every call: Per-tool grants and a decision on the record from the arguments, every call.
- exchange where the service owns data: Use token exchange when the downstream should be able to refuse on its own.
What goes wrong without these ideas#
Without the execution check, a revoked grant keeps working while the dashboard looks right: the opening's other design. Without argument-dependent policy, an agent tasked with SUB-1004 writes for SUB-1007. Without audience validation, a token issued for another application works here; without the passthrough rule, the tool server's policy becomes optional downstream. Without the principal-type condition, one mistaken scope grant lets an agent record a person's decision.
In a coding agent. A coding agent uses a code review server and a repository server, both remote MCP servers. Its token names the review server as audience, so it cannot be replayed at the repository server. open_pull_request is listed for it, and the server still checks the repository and the branch on every call; merging is not a tool it can call at all. A person with merge rights reviews and merges (Coding agents).
Choosing a design#
| Situation | Simplest credible design | Grow when | Alternatives |
|---|---|---|---|
| One developer, a local tool on their own files | stdio server, credentials from the environment, the operating system account as the boundary | the tool needs shared data or a shared credential | a sandboxed local server with restricted file and network access |
| One remote server, a few internal agents | OAuth resource server: protected resource metadata, audience check per request, scope plus decision point per call, separate downstream token | several servers, several teams, people leaving and joining often | a single service credential downstream where no per-caller data exists |
| Many servers behind a platform team | the above per server, plus a gateway that rejects what any server would reject (no token, wrong audience, over the rate limit) | servers need different identity providers or tenants | per-server validation only, with a shared library |
| Enterprise workforce using many servers | enterprise-managed authorization at the identity provider; servers keep their own per-call checks | partners or other organizations sign in | standard per-user consent per server |
This site's recommendation: whatever the row, the per-call decision on the record stays in the tool server or the domain service behind it. A gateway, an identity provider or a discovery filter can narrow who reaches the server; none of them knows which unit SUB-2001 belongs to.
Standard, pattern, recommendation: what each claim is#
| Claim | Kind | Source |
|---|---|---|
| stdio implementations should not follow the authorization specification and retrieve credentials from the environment | Standard | MCP specification 2026-07-28 |
HTTP servers implement protected resource metadata; clients send resource; servers validate audience; no passthrough | Standard | MCP specification 2026-07-28 |
403 insufficient_scope with the needed scopes; step-up by scope union | Standard (SHOULD) | MCP specification 2026-07-28 |
| per-client consent in proxies with a static client id | Standard (MUST, best practices page) | MCP security best practices |
| enterprise-managed authorization | Standard: Stable extension, relying on an IETF Internet-Draft | MCP extensions; IETF datatracker |
filtering tools/list by the caller's authorization | Standard allows it (MAY); using it as the only control is a mistake | MCP tools page |
| a gateway in front of MCP servers | Pattern (no protocol role) | ecosystem practice |
| token exchange for the downstream call | Pattern (the specification requires a separate token, not a method) | RFC 8693 |
| per-tool grants checked on every call; principal type in the decision rule; decisions only through the cockpit | This site's recommendation, implemented in the example | mcp_matrix.py, pdp.py |
Security notes#
Security note. Treat every tool call as an untrusted request from a model, whatever the host promises. The specification itself says MCP "cannot enforce these security principles at the protocol level"; the server's checks are the enforcement.
- Validate the audience on every HTTP request; a token issued for another resource gets 401, even with a valid signature and the right scopes.
- Decide grants, scopes and the record on every call; never trust the discovery list, a cached "may use", or a tool annotation.
- No outgoing request carries the caller's token. Obtain a separate token for the downstream audience.
- Irreversible writes name the principal type and the client in the rule, not only a scope.
- A local stdio server runs with its user's rights: install it like software, sandbox it, and keep production credentials out of its environment.
- Log each call's subject, actor, tool, record, decision and authorization policy version, never the token (Audit).
Monday checklist#
- For each tool, write down its scope, the principal types allowed and the arguments that name a record. A tool with no record argument and a write effect needs a second look.
- Call every hidden tool by name with a valid token, and every listed tool on a record outside the caller's task or unit. All must be refused.
- Revoke one grant in a test environment and call the tool within a second. It must be refused.
- Search the tool server's outgoing HTTP code for the incoming
Authorizationheader. It must never be reused. - Check that
scopes_supportedin your protected resource metadata is minimal, and that no wildcard scope exists.
Exercises#
- The platform team proposes to drop the per-call grant check, because "revoked tools are removed from
tools/listanyway". What is the precise risk? - The agent's task names
SUB-1004. It callsget_roof_assessmentforSUB-1004and then forSUB-2001. What does each call return in the example, and why is the second not 403? - A vendor's MCP server documentation says "configure your existing access token; we forward it to our API". Which sentence of the specification does that design break, and what do you ask the vendor?
AnswersOne line each
- A client or model can send any tool name it has seen anywhere; without the execution check a revoked grant keeps working, as in the opening's other design.
- 200 for
SUB-1004(inside the delegated task,R-AZ-05), 404 forSUB-2001, because another unit's record is answered as not found so its existence is not revealed. - "The MCP server MUST NOT pass through the token it received from the MCP client"; ask how they obtain a separate token for their API and whether their server validates that tokens were issued for it.
Advanced perspective#
Filtering discovery: useful, cacheable, never the controlWhy hide tools at all, and how caching changes the picture
Filtering tools/list by the caller's authorization is worth doing. Standard (MCP specification 2026-07-28, tools page): the tool set "MUST NOT vary per-connection" but "MAY vary by the authorization presented on the request". A model that never reads a tool it cannot use proposes fewer impossible calls, wastes fewer turns and leaks less about the catalog to a caller who should not know it exists.
Two things make discovery a poor control. First, a list is computed once and then cached, by the client and sometimes by a gateway, while authorization changes in seconds: a grant is revoked, a task expires, a record changes unit. Second, the list has no arguments. It can say "this caller may use record_recommendation"; it cannot say "on SUB-1004 only, until 10:15". The execution check has both the time and the arguments. Design the list as a hint for the model and the call as the decision, and test them separately: a test that calls every hidden tool by name, and a test that calls listed tools on records outside the caller's reach.
Per-tool scopes or a policy decision point?How far coarse scopes carry, and where record-level policy must live
A tempting design gives every tool its own scope (tool.get_roof_assessment, tool.record_recommendation) and stops there. It works for "which tools", it keeps the authorization server's consent screen honest, and it makes step-up challenges precise. It cannot express "inside the task", "same unit", "assigned underwriter" or "after step-up within 300 seconds", because those depend on the record and on the moment. Encoding records into scopes (sub.SUB-1004.write) explodes the scope space and moves record ownership into the identity provider, which does not own the data.
The split that holds: scopes in the token say which family of actions a client may attempt; the tool server or the domain service asks a decision point about the specific record with the subject, the actor, the task and the context. The best practices page lists, among common mistakes, "Treating claimed scopes in token as sufficient without server-side authorization logic". Where the decision point runs is a latency and ownership question (Enforcement); that it runs on every call is not.
Enterprise-managed authorization and the revocation windowCentral revocation is immediate at the identity provider, not at the server
The extension's documentation says that revoking access at the identity provider takes "effect immediately across all MCP clients". Read it with token lifetimes in mind. Revocation stops new ID-JAGs and therefore new access tokens. An access token already issued by the MCP server's authorization server stays valid at the MCP server until it expires, unless the server learns of the revocation through introspection, a deny list or a shared signals feed. The extension's specification uses example lifetimes labelled non-normative: an ID-JAG that expires 300 seconds after issue and an access token with expires_in 86400.
For a workforce leaving an insurer, a day-long access token defeats the point of central revocation. This site's recommendation: keep access tokens for MCP servers short (minutes, not a day), check per-tool grants on every call so an urgent revocation can bypass the token, and measure the real time from "access removed at the identity provider" to "call refused at the server" as an operational target (Operations). The draft status matters here too: clients, identity providers and authorization servers may implement different revisions, so test the whole chain, not one product.
A gateway in front of many serversWhat it can decide, what it cannot, and the token it must not forward
A platform team with twenty MCP servers wants one place for token validation, rate limits and logging. A gateway gives that: one key-set cache, one revocation feed, consistent 401 answers, per-client limits before any server spends work. It is a pattern; the specification defines no gateway role.
Three constraints follow from the standard. A gateway that forwards the caller's token to a server needs that token's audience to be the server, or the server accepts a token not issued for it. A gateway that mints a new internal token has become an authorization server for that hop and needs the same care as one. And the gateway cannot make record decisions without the domain data, so each server keeps its own per-call policy. The split that holds: the gateway rejects what any server would reject, and each server validates again for its own audience and decides each call. Derive both from one policy source, so the gateway never allows what the server refuses.
In one breath#
A local stdio server takes its credentials from the environment and runs inside its user's operating system rights; a remote MCP server is an OAuth resource server that accepts only tokens issued for its own audience and never passes them on. Discovery decides what a caller sees; execution decides each call again, with the grant, the scope and a decision on the record named by the arguments. Enterprise-managed authorization moves the "may this person use this server" decision to the identity provider through a Stable extension built on an IETF draft, and leaves every per-call check where it was.
The tool server now refuses what the agent may not do. But one tool, search_guidance, and its neighbour find_similar_decisions, do something different from reading one record: they search thousands of chunks from many sources, and return the closest ones. Which of those chunks this caller may read, and what happens when the authorization filter and the nearest-neighbour search disagree, is the question of RAG.