docs: rework the authorization tutorial around CIMD#3070
Draft
claude[bot] wants to merge 8 commits into
Draft
Conversation
* Version the documentation section alongside the specification The Documentation tab now uses the same Mintlify version picker as the Specification tab. The current guides move to docs/docs/2026-07-28/ as the canonical, in-progress version, and identical snapshots are stored under 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05 so every released spec version has matching docs. No content backfill: the snapshots are a copy of today's docs. Internal links inside each versioned tree point within that version. Old unversioned /docs/ URLs redirect to the 2026-07-28 pages, and a /docs/latest alias mirrors /specification/latest so links and the warning banner survive future version bumps. The spec version warning script is generalized to also show a banner on older docs versions. Version labels are chosen so the picker entries unify with the Specification tab when cut-release.yml promotes the draft spec to 2026-07-28 on this branch. :house: Remote-Dev: homespace * Use a Draft docs version, promoted to a dated version at release cut Replace the docs/docs/2026-07-28 directory with docs/docs/draft so the Documentation tab mirrors the Specification tab exactly: dated released versions plus a Draft entry. Both tabs now share identical version labels, so the picker unifies immediately instead of after the cut. Unversioned /docs/... URLs and /docs/latest now point at the latest released version (2025-11-25), matching the spec's redirect semantics. cut-release.yml promotes docs/docs/draft alongside the spec draft: copies it to docs/docs/<version>, rewrites internal links, patches the Documentation tab nav, retargets the latest-alias and legacy redirects (including /specification/latest, which was never retargeted), and adds dated siblings for draft-source redirects. Also fixes the promoted version being inserted after older versions instead of first. :house: Remote-Dev: homespace * Reorder top nav: Documentation, Specification, Extensions first :house: Remote-Dev: homespace * Propagate base-branch docs updates into all versioned copies after rebase During the rebase onto docs/2026-07-28-release, git's rename detection paired the old docs/docs/* paths only with the 2025-06-18 snapshot, so docs edits that landed on the base branch (Rust client tutorial, Claude Desktop connector UI text, requestedSchema fix, Kotlin SDK tier, auth sample link, OAuth URL validation guidance) were merged into that copy alone. Copy the merged 2025-06-18 files over draft, 2025-11-25, 2025-03-26, and 2024-11-05 with internal links rewritten to each version's prefix, keeping all snapshots identical per the PR's intent. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N5Z3TGJTN8cH6goHhdekqc --------- Co-authored-by: Claude <noreply@anthropic.com>
…aude/rc-auth-tutorial
Cover RFC 9728 well-known fallback discovery, RFC 9207 iss validation, multiple authorization servers with issuer-keyed registration state, application_type and redirect URI rejection handling in DCR, incremental scope consent and step-up authorization, and CIMD registration details. Point Security Best Practices links at the relocated docs page, migrate the TypeScript examples to the v2 SDK packages, and align the examples and pitfalls with the sessionless draft transport. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
The CIMD getClient example now rejects documents whose client_id does not match the URL or that lack the required fields, matching the authorization server MUSTs in the Client Registration spec, and the surrounding prose describes exactly that. The Common Issues note lists only the spec-required metadata fields. The session identifier pitfall now scopes header handling to servers that support only the draft revision instead of stating it as universal behavior. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
The getClient prose now notes the remaining AS-side MUST, validating the redirect_uri in each authorization request against the metadata document's redirect_uris, and scopes the callback's checks to document-level validation. The discovery fallback text now attributes the root well-known URI to the MCP spec's extension of RFC 9728 rather than to the RFC itself. Also removes two leftover screenshot placeholder comments in the Stytch walkthrough. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
The Keycloak example accepted any active token from introspection and the Stytch example verified JWTs without an audience check. Both now reject tokens whose aud claim does not match the server, using checkResourceAllowed from @modelcontextprotocol/server, as the authorization spec requires. Both examples also mounted /mcp with no auth middleware, so the 401 challenge described earlier in the tutorial never happened. The route is now guarded by requireBearerAuth bound to the provider, with a resource_metadata pointer in the WWW-Authenticate challenge. Also drops an unused createOAuthMetadata import from the Keycloak example. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
Trim asides that restated what underlying RFCs allow before stating what MCP requires, and drop redundant justifications. Requirements and spec pointers are unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PiRGukoDqKwVRsvDWP2EsN
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Den Delimarsky · Slack thread
The authorization tutorial previously taught Dynamic Client Registration with a session-keyed example server. It now teaches Client ID Metadata Documents (CIMD) as the primary registration path and de-emphasizes DCR. The examples are sessionless and follow the 2026-07-28 draft authorization flows.
Motivation and Context
Prepares the docs for the 2026-07-28 release. The tutorial predated the draft authorization changes.
Closes #3026
Closes #3027
Closes #3028
Closes #3034
Closes #3035
Closes #3038
Closes #3048
Supersedes #2155.
This PR is stacked on #3062 and should merge after it.
It also includes the authorization tutorial portion of #3031, which was closed by the stateless lifecycle PR.
How Has This Been Tested?
Documentation-only change.
npm run check:docspasses locally (Prettier formatting, the MDX JS-comment check, and the Mint broken-links check).Breaking Changes
None.
Types of changes
Checklist
Additional context
The CIMD tutorial rewrite is ported from #2155 by @localden. Per AI_POLICY.md: this PR was drafted with AI assistance, and a human contributor reviews the full content before merge.
Generated by Claude Code