docs: rework the authorization guide around CIMD - #3191
Conversation
Make Client ID Metadata Documents the primary client registration path in the authorization tutorial, with an end-to-end Stytch walkthrough (authorization UI plus TypeScript and C# MCP servers on the v2 SDKs). The Keycloak walkthrough moves under a legacy Dynamic Client Registration section. Conceptual registration material now summarizes and links to the client-registration spec page instead of restating it. Both the 2026-07-28 and draft copies are updated in lockstep.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Q4CPu9vPge4agzGH9XJZ2
The rewritten guide showed TypeScript and C# but omitted Python, one of the Tier 1 SDKs. Add a Python tab built on the mcp v2 SDK: an MCPServer with AuthSettings for the RFC 9728 protected-resource metadata and a TokenVerifier that validates JWT access tokens against the authorization server's published JWKS, rejecting tokens whose audience does not match this server through the SDK's check_resource_allowed helper. Unlike the TypeScript example, no metadata router is needed because the Python SDK serves the metadata and issues the WWW-Authenticate challenge itself, and the prose calls that out. The example was exercised end to end against the published mcp 2.0.0 with a local authorization server issuing real RS256-signed tokens: unauthenticated, wrong-audience, and expired requests all return 401, and a token minted for this server succeeds. Applied identically to the draft and 2026-07-28 copies. No-Verification-Needed: docs-only prose changes :house: Remote-Dev: homespace
localden
left a comment
There was a problem hiding this comment.
Went through the SDK usage against the published v2 packages. Two things.
TypeScript: the sample is correct as written and compiles clean under strict tsc against the published @modelcontextprotocol/server, /node, and /express 2.0.0, including the auth imports (requireBearerAuth, mcpAuthMetadataRouter, and getOAuthProtectedResourceMetadataUrl really do come from /express). The one gap is zod: it only type-checks with zod 4, and zod 3 blows up on the registerTool overloads, so the dependency needs to be stated. Suggestion inline.
C#: checked AddMcp, MapMcp().RequireAuthorization(), WithHttpTransport, McpAuthenticationDefaults, the ResourceMetadata option and its Resource / AuthorizationServers / ScopesSupported members, and the 2.0.0 package versions against the SDK. It all lines up, and matches the SDK's own ProtectedMcpServer sample. Nothing to change there.
Python was missing, so I pushed a tab for it in 3a9d078 rather than proposing a hundred-line suggestion: an MCPServer with AuthSettings and a TokenVerifier that validates JWTs against the authorization server's JWKS and rejects wrong-audience tokens via the SDK's check_resource_allowed. The Python SDK serves the protected-resource metadata and the WWW-Authenticate challenge itself, so there's no metadata router to wire, and the prose calls that out. I ran it end to end against the published mcp 2.0.0 with a local authorization server issuing real RS256 tokens: no token, wrong audience, and expired all come back 401, a token minted for the server succeeds. Applied to both the draft and 2026-07-28 copies.
Requested by Den Delimarsky · Slack thread
Before
The hands-on half of the guide walked through two specific identity products end to end, including dashboard configuration and a vendor login app, and the flow it demonstrated was built around Dynamic Client Registration.
After
The guide teaches the current CIMD-based flow in provider-agnostic terms. It describes what any authorization server must support (CIMD advertised via
client_id_metadata_document_supported, standard metadata endpoints, scope issuance, and token audience binding) and centers the code on what the SDKs are doing. The TypeScript server usesmcpAuthMetadataRouter,requireBearerAuth, andcheckResourceAllowed, and the C# server usesAddMcp()with the ASP.NET Core JWT bearer middleware, withhttps://auth.example.comstanding in for the authorization server. Dynamic Client Registration is covered as a generic fallback for authorization servers without CIMD support, with spec links and no vendor walkthrough. The2026-07-28anddraftcopies stay in lockstep, differing only in version-pinned spec links.How
Rewrote the implementation sections of both tutorial copies, removed the vendor setup walkthroughs and their images, and verified the TypeScript sample compiles under strict
tscagainst the published v2 SDK packages.npm run prepand the docs checks pass.Supersedes #2155