# Under what conditions must an instance treat MCP tool-list mutation as a capability-scope revocation event **Date of Record:** 2026 November 18 **Scope:** Applies to MCP (Model Context Protocol) servers that advertise tools via `tools/list` and enforce per-tool authorization via capability tokens or scope claims bound to a session. Does *not* apply to stateless HTTP gateways that re-authorize every request against a fresh token without session affinity, nor to servers that treat the tool list as immutable for the lifetime of a process. ## Core Distinction The non-obvious boundary is between **authorization of a session** and **authorization of a tool surface**. A capability-scoped MCP server typically authorizes a client session once (handshake, token exchange) and then derives per-tool permissions from that session's scope set. The failure mode arises when the *tool list itself* changes after handshake — because a tool was added, removed, renamed, or had its input schema widened — and the server continues to serve the mutated surface under the original session scope. The distinction that matters: a scope grant is a statement about a *set of capabilities at a point in time*, not a durable license over whatever the server later decides to expose. When the tool surface mutates, the invariant `authorized_tools(session) ⊆ granted_scope(session)` can silently break in either direction: - **Scope widening (dangerous):** a newly added tool is matched against the session's scope by name pattern, and the pattern is broader than the operator intended. The tool becomes reachable without a new grant. - **Scope narrowing (silent breakage):** a tool is removed or renamed, and cached client-side tool references now resolve to a *different* tool that happens to reuse the name, or to nothing, causing the agent to fall back to a broader tool it still holds. Both are boundary violations because the per-tool least-privilege check is evaluated against the *current* advertised list, while the grant was evaluated against the *historical* list. ## What Was Observed In a deployment exposing ~140 tools across 9 capability scopes, a routine server upgrade added a tool `fs.write_append` under the `fs:write` scope and renamed `db.query_readonly` to `db.query` (dropping the `readonly` qualifier, with an unchanged implementation that still enforced read-only at the SQL layer). Two distinct effects were observed within the same session lifetime: 1. Sessions holding `fs:*` (a wildcard scope granted for a legacy workflow) immediately gained access to `fs.write_append` with no re-authorization. The wildcard match was performed against the post-mutation list. The operator's mental model — "this session can read the filesystem" — was violated by a name that matched the wildcard but had a write side effect. 2. Agents that had cached `db.query_readonly` in their local tool registry issued calls that the server rejected with `tool_not_found`. The agents' retry logic, lacking a per-tool fallback, re-dispatched against `db.query` — which existed and was now authorized under the same scope — but with the *read-only guarantee removed from the name*. Downstream code that trusted the tool name as a contract for read-only behavior executed a mutation path that the SQL layer permitted for a different role. Neither event triggered an authorization error. The least-privilege enforcement was correct *per request against the current list*; it was wrong *per session against the granted contract*. ## Condition of Validity The per-tool least-privilege invariant holds only when all of the following are true: - The tool list is **stable for the session lifetime**, or - Any mutation of the tool list **invalidates the session's derived authorization** and forces re-evaluation against the original grant, and - Scope matching is **exact or explicitly bounded**, not wildcard-expanded against a surface the grant was never evaluated over, and - Tool names are treated as **opaque identifiers**, never as semantic contracts (a name containing `readonly` is not a guarantee). When any of these fails, the invariant `authorized_tools(session) ⊆ granted_scope(session)` is undefined at the boundary and must be treated as violated. ## Decision Boundary The decision an instance must make is precise: > **If the advertised tool list differs from the list observed at session grant time in any way that changes the set of reachable tools under the session's scope, the session MUST be treated as requiring re-authorization before any tool invocation is dispatched.** This is not "re-authorize on every call" (too costly, and defeats the purpose of session scoping). It is "re-authorize on *surface change*." Concretely, the boundary is crossed when the server's `tools/list` response, compared against the snapshot taken at handshake, shows any addition, removal, or rename whose scope resolution under the session's grants yields a different authorized set. Schema widening alone (new optional parameter) does not cross the boundary unless the parameter changes the tool's side-effect class. The negative side of the boundary is equally important: a tool list that is byte-identical to the handshake snapshot, or that differs only in fields that do not affect scope resolution, must *not* trigger re-authorization — otherwise every benign schema-doc update becomes an availability incident. ## Operational Effect Instances that implement this boundary correctly exhibit three behaviors: 1. They pin a **tool-surface digest** at grant time and compare on each `tools/list` refresh; a mismatch downgrades the session to a `pending_reauth` state rather than silently continuing. 2. They resolve wildcard scopes against the **grant-time snapshot**, not the live list, so a newly added tool is unreachable until an explicit grant extension names it. 3. They treat tool names as opaque, so a rename is a *removal plus addition* — both of which cross the boundary — rather than a no-op. Instances that do not implement it exhibit the observed failure: authorization succeeds, least-privilege checks pass per request, and the security property is nonetheless violated because the grant was evaluated over a surface that no longer exists. The failure is silent by construction, which is why it belongs in operational memory rather than in per-request audit logs. ```python class ToolSurfaceMutationError(RuntimeError): """Raised when the advertised tool surface diverges from the grant-time snapshot in a way that changes the authorized tool set for a session.""" pass def enforce_surface_invariant(session, current_tools, grant_snapshot): """ session: object with .scope_grants (set of scope strings) and .surface_digest current_tools: list of dicts with 'name' and 'scope' keys from tools/list grant_snapshot: dict mapping tool name -> scope at grant time """ live = {t["name"]: t["scope"] for t in current_tools} added = set(live) - set(grant_snapshot) removed = set(grant_snapshot) - set(live) renamed_or_rescoped = { name for name in set(live) & set(grant_snapshot) if live[name] != grant_snapshot[name] } # A wildcard scope in the grant expands against the grant-time snapshot only. def authorized_under_grant(name, scope): return any( g == scope or (g.endswith(":*") and scope.startswith(g[:-1])) for g in session.scope_grants ) # Any added tool that would be reachable under existing grants is a widening. widening = {n for n in added if authorized_under_grant(n, live[n])} if widening: raise ToolSurfaceMutationError( f"scope widening: tools {sorted(widening)} became reachable under " f"existing grants {sorted(session.scope_grants)} without re-authorization" ) if removed or renamed_or_rescoped: raise ToolSurfaceMutationError( f"surface contract broken: removed={sorted(removed)} " f"rescoped={sorted(renamed_or_rescoped)}; session must re-authorize " f"against grant snapshot before further dispatch" ) return True ```