René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Reduce authorization spec verbiage by delegating to the OAuth RFCs it builds on","articleBody":"## Motivation\n\nThe authorization spec pages restate a substantial amount of material that is already normatively defined in the OAuth specifications they cite (OAuth 2.1, RFCs 6750/7591/8414/8707/9728/9700, RFC 9207, the CIMD draft, and the OIDC specs). Restated text bloats the spec and drifts out of sync with the RFCs. The audit found several such drifts already: the refresh-token rotation requirement omits OAuth 2.1 §4.3.1's sender-constrained alternative, and the exact redirect-URI matching statement omits the loopback-port exception. The proposal is to delegate to RFC citations and keep only (a) MCP-specific requirements and (b) explicit deltas against the cited RFC, with the requirement-level change named. In addition, a significant share of the material (worked examples, attack walkthroughs, and rationale) is genuinely useful but non-normative, and should **move to the documentation tutorials** (`docs/docs/tutorials/security/`) rather than be deleted. Per maintainer direction (applied in v4), authorization flow overviews, the end-to-end sequence diagrams of the authorization, discovery, and CIMD flows, stay in the specification and are excluded from the relocation set.\n\nAn audit at commit `02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5` (v4, which applies the maintainer direction that flow overviews stay in the spec on top of v3's side-by-side quote verification) found **67 overlapping or non-normative passages** (one v3 passage is split in v4): 7 pure duplicates (~25-30 lines deletable outright), 26 passages that restate RFC mechanics around a small MCP delta (an estimated further 120-165 lines compressible), 15 passages of non-normative tutorial material (~105 lines) that should relocate to the docs, and 25 passages that any trim must preserve: 22 MCP-specific keeps (notably the token-passthrough prohibitions, the per-request Authorization rule, and the CIMD localhost consent rules; several sit inside otherwise trimmable or movable sections) plus the 3 flow overviews reclassified to keep in v4.\n\n**Quote verification (new in v3).** Every delete-and-cite and compress-to-delta finding now carries side-by-side spec/RFC quote evidence in the audit report: 54 pairs, of which 6 are verbatim copies, 22 are same-strength paraphrases, and 26 are partial mismatches where the cited RFC states the rule at a weaker level, with an extra option, or against a different party. The partial mismatches confirmed the delta-first approach and forced two downgrades: the redirect-URI registration one-liner (security-considerations.mdx L73) and the state-parameter SHOULD (L77-78) are now keep items, because no cited RFC carries either rule.\n\n**Flow overviews (new in v4).** Per maintainer direction, authorization flow overviews belong in the spec rather than the documentation. Three findings are reclassified from move-to-docs to keep: the \"Authorization Flow Steps\" section ([index.mdx L139-L191](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L139-L191)),`` the discovery \"Sequence Diagram\" section ([authorization-server-discovery.mdx L96-L144](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L96-L144)),`` and the CIMD \"Client ID Metadata Documents Flow\" diagram ([client-registration.mdx L71-L112](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L71-L112)),`` split in v4 from the former L53-L112 bundle so that the \"Example Metadata Document\" ([L53-L69](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L53-L69))`` remains a move item. The discovery diagram's step-for-step overlap with RFC 9728 §5 Figure 1 is retained as an informational observation under the keep disposition.\n\n## Evidence format (examples)\n\nThe full per-finding evidence is in the audit report; three representative pairs show the format and the three grades.\n\nA paraphrase where the citation carries the deleted sentence (the query-string token rule):\n\n\u003e **Spec says** (index.mdx L259-274): \"MCP client **MUST** use the Authorization request header field defined in OAuth 2.1 Section 5.1.1 [...] Access tokens **MUST NOT** be included in the URI query string\"\n\u003e **OAuth 2.1 §5.1 and §5.1.1 say**: \"clients MUST NOT send the access token in a URI query parameter [...] Clients SHOULD make authenticated requests with a bearer token using the `Authorization` request header field\"\n\u003e _paraphrase_ ⚑ canonical: the query-string prohibition deletes to the citation (kept visible only if maintainers want the emphasis); the header rule is a SHOULD-to-MUST upgrade that must stay stated as a delta.\n\nA verbatim copy where a single citation replaces the whole passage:\n\n\u003e **Spec says** (security-considerations.mdx L80-82): \"Authorization servers **SHOULD** only automatically redirect the user agent if it trusts the redirection URI. If the URI is not trusted, the authorization server MAY inform the user and rely on the user to make the correct decision.\"\n\u003e **RFC 9700 §4.11.2 says**: \"The authorization server SHOULD only automatically redirect the user agent if it trusts the redirection URI. If the URI is not trusted, the authorization server MAY inform the user and rely on the user to make the correct decision.\"\n\u003e _verbatim_\n\nA partial mismatch showing why compression must state the delta rather than just cite:\n\n\u003e **Spec says** (security-considerations.mdx L27-34): \"For public clients, authorization servers **MUST** rotate refresh tokens as described in OAuth 2.1 Section 4.3.1.\"\n\u003e **OAuth 2.1 §4.3.1 says**: \"Authorization servers MUST utilize one of these methods [...]: Sender-constrained refresh tokens [...] Refresh token rotation\"\n\u003e _partial-mismatch_: the spec mandates rotation only while the cited section offers two options; the edit must either cite both options or declare the narrowing as an explicit MCP tightening.\n\n## Biggest duplication and relocation areas\n\n| RFC / area | What is duplicated or relocatable | Where (roughly) | Suggested action |\n|---|---|---|---|\n| OAuth 2.1 | Bearer token usage, token validation/error handling, refresh-token handling, and most attack narratives in the security page (PKCE, open redirection, token theft; some sentences near-verbatim) | [index.mdx L259-L326](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L259-L326),`` [security-considerations.mdx L27-L82](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L27-L82)`` | Compress each block to a §-level citation plus MCP's requirement-level upgrades (header-only MUST, unconditional PKCE, 401 MUST, etc.); move the PKCE mechanism explainer (L51) to the authorization tutorial; keep L73 and L77-78 whole (v3 downgrades) |\n| RFC 6750 | WWW-Authenticate/scope attribute semantics, Bearer example request, status-code table, insufficient_scope response details | [index.mdx L99-L103](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L99-L103),`` [L276-L282](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L276-L282),`` [L318-L353](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L318-L353)`` | Delete the table; move the Bearer example to the authorization tutorial; state only the MAY-to-SHOULD/MUST upgrades and the MCP-added `resource_metadata` parameter |\n| RFC 8707 | Canonical-URI syntax rules, valid/invalid example lists, url-encoded parameter example; the resource-parameter MUST is stated three times across two files | [index.mdx L220-L255](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L220-L255),`` [security-considerations.mdx L14-L23](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L14-L23),`` [L153-L156](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L153-L156)`` | Delete example lists (the RFC has equivalents); state the OPTIONAL-to-MUST upgrade once in index.mdx and cross-reference elsewhere |\n| RFC 8414 / OIDC Discovery | Well-known URL construction mechanics, issuer validation of retrieved metadata | [authorization-server-discovery.mdx L63-L94](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L63-L94)`` | Keep only the MCP MUST-level priority order across both suffixes; cite RFC 8414 §3.1/§3.3/§5 and OIDC Discovery §4/§4.3 for construction and validation |\n| RFC 9728 | Discovery mechanism descriptions and the sequence diagram, which mirrors RFC 9728 §5 Figure 1 step for step | [authorization-server-discovery.mdx L39-L53](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L39-L53),`` [L96-L144](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L96-L144)`` | Cite §3/§5.1; keep the MCP deltas (one-of-two server requirement, root-URI fallback, mandatory client support); the sequence diagram stays in the spec (reclassified keep in v4 per maintainer direction), with its §5 Figure 1 overlap retained as an informational observation |\n| RFC 9207 | iss validation mechanics (table rows 1-2, anti-normalization sentence) | [index.mdx L199-L216](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L199-L216)`` | Cite §2.4 for the base behavior; keep rows 3-4 (genuine profile decisions), the issuer-provenance rule, and the error-display prohibition |\n| CIMD draft | Client/AS requirement bullets, SSRF threat paragraph, trust-policies list | [client-registration.mdx L36-L51](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L36-L51),`` [security-considerations.mdx L92-L125](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L92-L125)`` | Cite draft §3/§4/§6; keep the MCP-required metadata fields, the explicit AS validation MUSTs, and the localhost-redirect normative bullets; move the SSRF narrative, localhost walkthrough, and trust-policy menu to the security best-practices docs page |\n| Worked examples (no single RFC) | The CIMD example metadata document and the Bearer example request. The end-to-end flow diagrams formerly grouped here (the Authorization Flow Steps diagram, the discovery sequence diagram, and the CIMD flow diagram) are keep items in v4: flow overviews stay in the spec per maintainer direction | [index.mdx L276-L282](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L276-L282),`` [client-registration.mdx L53-L69](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L53-L69)`` | Move both to `docs/docs/tutorials/security/authorization.mdx` |\n| Scope guidance and attack narratives | Scope-selection rationale, scope-challenge strategy taxonomy, scope-accumulation and hierarchical-scope Notes, mix-up analysis, foreign-token \"two dimensions\" analysis | [index.mdx L131-L133](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L131-L133),`` [L355-L366](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L355-L366),`` [L382-L389](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L382-L389),`` [L426-L437](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L426-L437),`` [security-considerations.mdx L65-L67](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L65-L67),`` [L140-L143](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L140-L143)`` | Move to `docs/docs/tutorials/security/security_best_practices.mdx` (Scope Minimization, Token Passthrough, and new Attacks-and-Mitigations subsections), leaving the normative SHOULDs/MUSTs and one-line cross-references in the spec |\n\n## Proposed edits\n\n### Delete and cite\n\n- [ ] Delete the Communication Security \"Specifically\" bullets ([security-considerations.mdx L40-L43](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L40-L43)),`` keeping the OAuth 2.1 §1.5 citation\n- [ ] Replace the exact redirect-URI restatement ([security-considerations.mdx L75](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L75))`` with a citation to OAuth 2.1 §2.3.1 (restoring the loopback-port exception)\n- [ ] Delete the open-redirector restatement ([security-considerations.mdx L80-L82](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L80-L82)),`` keeping a single §7.12.2 citation (verbatim copy, see the evidence example above)\n- [ ] Delete the authorization-code attack narrative and the S256 restatement ([security-considerations.mdx L47-L48, L53](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L45-L53));`` L47 is near-verbatim RFC 9700 §4.5\n- [ ] Delete the valid/invalid canonical URI example lists ([index.mdx L235-L245](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L235-L245))`` and the url-encoded resource example ([L249-L253](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L249-L253))``\n- [ ] Replace the issuer-validation restatement ([authorization-server-discovery.mdx L94](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L94))`` with citations to RFC 8414 §3.3 / OIDC Discovery §4.3\n- [ ] Delete or de-normativize the anti-normalization comparison sentence ([index.mdx L214](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L214))``\n\n### Compress to delta\n\n- [ ] Compress Token Requirements ([index.mdx L259-L274](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L259-L274))`` to the header-only delta over OAuth 2.1 §5.1.1; relocate the per-request rule (L272) so it survives\n- [ ] Compress Token Handling ([index.mdx L286-L293](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L286-L293))`` to citations plus the 401-MUST and unconditional-audience deltas; keep L288-289 and L295-300 verbatim\n- [ ] Reduce the refresh-token confidentiality and issuance bullets ([index.mdx L307-L312](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L307-L312))`` to citations; keep the `grant_types`/`offline_access` bullets\n- [ ] Replace the status-code table ([index.mdx L318-L326](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L318-L326))`` with a one-line citation carrying the MUST\n- [ ] Compress the insufficient-scope requirements and Server Scope Management ([index.mdx L337-L353](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L337-L353))`` to the MAY-to-SHOULD and `resource_metadata` deltas, keeping the L391-399 example as the page's single illustration\n- [ ] Trim the scope-attribute re-explanation ([index.mdx L99-L103](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L99-L103))`` to the OPTIONAL-to-SHOULD delta; cite RFC 9728 §2 for the non-exhaustive `scopes_supported` clause (L112-114)\n- [ ] Reduce iss-validation table rows 1-2 and the advertisement clause ([index.mdx L197-L210](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L197-L210))`` to RFC 9207 §2.3/§2.4 citations, keeping rows 3-4 as stated profile decisions; keep L195 and the L216 display prohibition\n- [ ] Compress the resource-parameter bullets ([index.mdx L220-L225](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L220-L225))`` to the OPTIONAL-to-MUST delta; keep L233's uppercase tolerance, the L247 trailing-slash note, and L255\n- [ ] Drop the duplicate multiple-AS sentence ([authorization-server-discovery.mdx L21-L25](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L21-L25)),`` keeping the client-selection responsibility with its §7.6 citation; compress the client-ID uniqueness premise ([L27-L35](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L27-L35))`` to a citation, keeping the per-AS state MUSTs\n- [ ] Compress the discovery-mechanism descriptions ([authorization-server-discovery.mdx L39-L53](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L39-L53))`` to RFC 9728 citations plus the MCP deltas (one-of-two server option, root-URI fallback, mandatory client support); fold the L49 parsing MUST into L47\n- [ ] Compress the well-known URL construction section ([authorization-server-discovery.mdx L63-L92](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L63-L92))`` to the MUST-level priority order with citations, halving or dropping the worked URL lists\n- [ ] Replace the restated CIMD client bullets ([client-registration.mdx L36-L42](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L36-L42))`` with draft §3/§4.1 citations, keeping the MCP-required `client_name`/`redirect_uris` delta\n- [ ] Compress the CIMD authorization-server bullets ([client-registration.mdx L44-L51](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L44-L51))`` to citations, keeping the explicit AS validation MUSTs and rewording the caching bullet against draft §4.4's levels\n- [ ] Optionally drop the RFC 7591 purpose clause ([client-registration.mdx L147-L150](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L147-L150)),`` keeping the MAY + backwards-compatibility note\n- [ ] Token Theft ([security-considerations.mdx L27-L34](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L27-L34)):`` delete the threat prose, reduce the short-lived line to a citation, and rewrite the rotation MUST to either match OAuth 2.1 §4.3.1 (rotation or sender-constraining) or declare the narrowing explicitly (see the partial-mismatch example above)\n- [ ] Cite RFC 8414 §2 for the PKCE absence semantics ([security-considerations.mdx L55-L57](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L55-L57))`` while keeping the fail-closed MUSTs and all of L59-61; state the unconditional-PKCE delta explicitly\n- [ ] Audience sections ([security-considerations.mdx L14-L23](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L14-L23),`` [L136-L156](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L136-L156)):`` consolidate the triple-stated validation and resource-parameter MUSTs into one statement plus cross-references to index.mdx; keep L138 and L145-156 (L151 verbatim); fold the RFC 9068 citation from L142 into L149\n- [ ] Compress the OIDC `application_type` section's remaining prose ([client-registration.mdx L165-L179](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L165-L179)`` stays; see the move item for L154-163)\n\nRemoved from this list in v3 (downgraded to keep after quote verification): the state-parameter SHOULD ([security-considerations.mdx L77-L78](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L77-L78))`` and the redirect-URI registration one-liner ([L73](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L73));`` no cited RFC carries either rule, so both moved to the Keep list below.\n\n### Move to documentation\n\nTo `docs/docs/tutorials/security/authorization.mdx`:\n\n- [ ] Move the Bearer example request ([index.mdx L276-L282](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L276-L282))``\n- [ ] Move the CIMD \"Example Metadata Document\" ([client-registration.mdx L53-L69](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L53-L69));`` the \"Client ID Metadata Documents Flow\" diagram (L71-L112) stays in the spec (keep in v4), and the MUST at L32-33, the required-property list at L38-41, and the client_id-equals-URL rule stay\n- [ ] Move the pre-registration options list ([client-registration.mdx L130-L136](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L130-L136));`` the SHOULD-support-static-credentials sentence stays\n- [ ] Move the `application_type` OIDC background and default-to-web rationale ([client-registration.mdx L154-L163](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L154-L163));`` the MUST-send sentence (L160-161) stays, rewritten to inline the OIDC Registration citation; in docs, back the ignore-unknown clause with RFC 7591 §2\n- [ ] Move the CIMD-portability closing paragraph ([client-registration.mdx L199-L202](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L199-L202));`` the binding MUSTs at L183-191 are already scoped to exclude CIMD client IDs\n- [ ] Move the PKCE mechanism explainer sentence ([security-considerations.mdx L51](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L51)),`` merging into the tutorial's existing PKCE introduction\n\nRemoved from this list in v4 (reclassified keep, since flow overviews stay in the spec per maintainer direction): the \"Authorization Flow Steps\" section ([index.mdx L139-L191](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L139-L191)),`` the discovery \"Sequence Diagram\" section ([authorization-server-discovery.mdx L96-L144](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/authorization-server-discovery.mdx#L96-L144)),`` and the CIMD flow diagram ([client-registration.mdx L71-L112](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/client-registration.mdx#L71-L112),`` split from the former L53-L112 bundle). The discovery diagram's overlap with RFC 9728 §5 Figure 1 is retained as an informational observation under keep.\n\nTo `docs/docs/tutorials/security/security_best_practices.mdx`:\n\n- [ ] Move the scope-selection rationale ([index.mdx L131-L133](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L131-L133))`` to the Scope Minimization section; L134-137 (`scopes_supported` semantics) stays in the spec\n- [ ] Move the scope-challenge strategy taxonomy ([index.mdx L355-L366](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L355-L366))`` to Scope Minimization; the SHOULDs at L368-380 stay, with L368's \"Regardless of the approach chosen\" reworded\n- [ ] Move the scope-accumulation Note ([index.mdx L382-L389](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L382-L389))`` to Scope Minimization, replacing it with a one-sentence cross-reference to the step-up flow; the normative union SHOULD at L110-112 and the flow at L411-419 stay\n- [ ] Move the hierarchical-scopes Note ([index.mdx L426-L437](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/index.mdx#L426-L437))`` to Scope Minimization; if the \"must account for hierarchy\" expectation (L433-436) is considered binding, first restate it as one normative sentence in Scope Challenge Handling\n- [ ] Move the mix-up attack analysis ([security-considerations.mdx L65-L67](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L65-L67))`` to a new \"Mix-Up Attacks\" subsection; the spec keeps a one-sentence threat summary with the RFC 9207 citation and a cross-reference to Authorization Response Validation\n- [ ] Move the AS-side SSRF narrative ([security-considerations.mdx L92-L94](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L92-L94))`` to a new AS-side subsection of the SSRF section; the SHOULD + CIMD §6.5 citation (L96-97) stays\n- [ ] Move the localhost impersonation walkthrough ([security-considerations.mdx L101-L107](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L101-L107))`` to a new \"Localhost Redirect URI Impersonation\" subsection; the threat-summary sentence and the SHOULD/MAY/MUST bullets (L109-113) stay\n- [ ] Move the CIMD trust-policy menu ([security-considerations.mdx L119-L125](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L119-L125))`` to a new \"CIMD Trust Policies\" subsection; L117's MAY stays, reworded to a complete sentence with the draft §6.8/§6.4 citations\n- [ ] Move the foreign-token \"two critical dimensions\" analysis ([security-considerations.mdx L140-L143](``https://github.com/modelcontextprotocol/modelcontextprotocol/blob/02dd8f615a4aa6bc6f2671c1151bcd0a9d0ddfd5/docs/specification/draft/basic/authorization/security-considerations.mdx#L140-L143))`` into the Token Passthrough section; carry or re-home the RFC 9068 citation\n\n### Keep: verify these survive every edit above\n\n- [ ] index.mdx: L68-71, L73-74, L76-80, L134-137, L139-191 (Authorization Flow Steps, kept in v4 per maintainer direction), L195, L247, L255, L272, L288-289, L295-300, L314-316, L368-380 (L368 reworded), L410-419, and the priority/relationship rules at L105-114 and L124-129\n- [ ] authorization-server-discovery.mdx: L13-19 (`authorization_servers` REQUIRED), L57-61 (default well-known suffix declaration), and L96-144 (the Sequence Diagram section, kept in v4 per maintainer direction; its RFC 9728 §5 Figure 1 overlap is informational only)\n- [ ] client-registration.mdx: L32-41 (CIMD wire-format core), L71-112 (CIMD flow diagram, kept in v4 per maintainer direction), L130 first sentence, L160-161 (rewritten), L172-179, L181-198\n- [ ] security-considerations.mdx: L55-61 (PKCE fail-closed + OIDC metadata MUSTs), L73 (redirect-URI registration, downgraded from compress in v3; add citations for context), L77-78 (state-parameter SHOULD, downgraded from compress in v3; an explicit MCP profile choice on top of mandatory PKCE), L101 first sentence + L109-113, L117 (reworded), L127-134, L138 + L145-156 (L151 verbatim)\n\n**Deliberate editorial choices (canonical rules kept visible).** Thirteen quote pairs in the audit report are flagged canonical-for-emphasis, across ten passages: the no-query-string token rule (index.mdx L259-274), the refuse-to-serve audience mechanics (index.mdx L286-293), iss validation rows 1-2 (index.mdx L199-210), metadata issuer validation (authorization-server-discovery.mdx L94), the CIMD fetch/redirect bullets (client-registration.mdx L44-51), the audience-binding section (security-considerations.mdx L14-23), the S256 sentence (L45-53), the PKCE absence semantics (L55-57), the redirect-URI registration line (L73), and exact redirect-URI matching (L75). For each, the citation carries the requirement; keeping the sentence in the spec is emphasis, not necessity, so any that stay should stay by a recorded decision rather than by default. (The L73 entry is the exception where retention is required, per its v3 downgrade.)\n\n## Status\n\nThis is a report of audit findings only. No changes are proposed yet; each edit above should be discussed with maintainers before any changes are made, particularly where a restatement currently diverges from the cited RFC (refresh-token rotation, exact redirect-URI matching) and the fix could be read as a normative change. Moves into the tutorials should merge with existing content (the authorization tutorial already has a PKCE introduction; the best-practices page already has Scope Minimization, SSRF, and Token Passthrough sections) rather than duplicating alongside it. The full side-by-side quote evidence for every delete-and-cite and compress-to-delta finding is embedded in the audit report (v3); the v4 revision applies the maintainer direction that authorization flow overviews stay in the spec.","author":{"url":"https://github.com/claude[bot]","@type":"Person","name":"claude[bot]"},"datePublished":"2026-07-08T22:22:02.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/3054/modelcontextprotocol/issues/3054"}