An MCP tools/call needs a scope the token lacks — what should the server return?

## Distinguishing the two rejections A remote MCP server has two very different things to say about a request it will not serve. - **No usable credential.** Nothing was presented, or what was presented is expired, malformed, or bound to a different audience. That is an authentication-layer failure and the answer is `401`. - **A perfectly good credential that does not cover this call.** The token is for this server, unexpired and genuine; it simply lacks the permission the specific tool or resource requires. That is an authorization-layer failure and the answer is `403` with `error="insufficient_scope"`. Getting this split right matters because the two point the client at different remedies. A `401` says "go authenticate"; the `insufficient_scope` signal says "you are the right caller, come back with more permission". Collapsing both into a generic failure leaves the client unable to do anything useful except give up. ## Why it is an HTTP status and not a JSON-RPC error Authorization in MCP is transport-level. The token rides on the HTTP request, is evaluated before the JSON-RPC body is meaningfully processed, and the answer belongs at the same layer. A JSON-RPC error object inside a `200` would bury a security decision in the payload, where generic clients and infrastructure cannot see it, and would make it indistinguishable from a tool that merely failed. Reserve `isError` and JSON-RPC error objects for what happened *inside* a call the caller was allowed to make. ## What the client does next The step-up loop is: 1. Read the `403` and the `insufficient_scope` signal, including any indication of which scope is required. 2. Run an authorization flow requesting that additional scope, with the same audience binding as before — the token must still be for this MCP server. 3. Re-issue the original call **as a new request with a new JSON-RPC id**, carrying the new token. Step 3 is where the stateless design shows through. Through revision 2025-11-25, MCP had a protocol-level session, and it was natural to imagine "upgrading" it. Revision 2026-07-28 removed sessions and the `Mcp-Session-Id` header entirely, along with the `initialize` handshake. There is no connection-scoped authorization state to change; there is only the next request, which will be authorized on the credential it carries. ## Consent, not just plumbing A step-up should be user-visible. The extra scope is a widening of what the server may do on the user's behalf, and MCP's security model puts the host in charge of consent — the protocol cannot enforce it. A host that silently escalates whenever a `403` appears has automated away exactly the decision the user was supposed to make. The good behaviour is to explain which additional permission the call needs and let the user approve or refuse; a refusal simply means the call does not happen. ## The visible-surface consequence MCP requires that the set of tools, prompts and resources a server exposes must not vary *per connection*, but explicitly allows it to vary by the authorization presented. Both halves of that rule are load-bearing here. It means a server may legitimately hide write tools from a read-only token and reveal them once a broader token arrives — the difference is attributable to the credential, not to which connection you happen to be on or what you did earlier. Clients should therefore treat cached listings as tied to the authorization used to fetch them; the `ttlMs` and `cacheScope` fields on a `tools/list` result exist so a server can mark an authorization-dependent listing as private rather than publicly cacheable. ## Server-side design notes Decide scope granularity deliberately. One coarse scope per server makes step-up meaningless and every token maximally powerful; a scope per individual tool produces consent screens nobody reads. A workable middle ground groups by capability and blast radius — read versus write, or per data domain — so that a step-up prompt has a meaning a user can evaluate. Also make the required scope discoverable in the rejection where you can. A client that knows which permission was missing can ask for exactly that; a client that only knows "more" tends to ask for everything, which is how over-broad tokens spread. ## What weak answers look like Returning `401` for a scope problem, which sends the client back through authentication that will succeed and change nothing. Returning a tool result with `isError` set, which hides the security decision inside the payload. Or describing the recovery as "the session is upgraded" — a mechanism that no longer exists after 2026-07-28.