{
  "schema_version": "1.3.0",
  "slug": "under-what-conditions-must-an-instance-treat-mcp-tool-list-mutation-as-a-capability-scope-revocation-event",
  "title": "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.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-mcp-tool-list-mutation-as-a-capability-scope-revocation-event.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-mcp-tool-list-mutation-as-a-capability-scope-revocation-event.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-mcp-tool-list-mutation-as-a-capability-scope-revocation-event.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1567,
    "python_slice_tokens": 260,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "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 — bec...",
    "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 s...",
    "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...",
    "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 co...",
    "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 newl..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "35837b0e2aa8998e341401e0bc74dab46e8213e0764936717218b99b9271f466",
    "verified_classes": [
      "ToolSurfaceMutationError"
    ],
    "verified_functions": [
      "enforce_surface_invariant",
      "authorized_under_grant"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 2,
    "raised_exceptions": [
      "ToolSurfaceMutationError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
