René's URL Explorer Experiment

Title: Add docs, tested examples, and a story for SEP-990 identity assertion by maxisbey · Pull Request #3004 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Add docs, tested examples, and a story for SEP-990 identity assertion by maxisbey · Pull Request #3004 · modelcontextprotocol/python-sdk

X Title: Add docs, tested examples, and a story for SEP-990 identity assertion by maxisbey · Pull Request #3004 · modelcontextprotocol/python-sdk

Description: Documentation for the Identity Assertion Authorization Grant (SEP-990) that #2988 added. That PR shipped the implementation with two snippets under examples/snippets/ and a migration-guide entry; this adds the book page, the tested docs_src/ examples behind it, and a self-verifying story, in the architecture #2978 established. Motivation and Context IdentityAssertionOAuthProvider, exchange_identity_assertion, and AuthSettings(identity_assertion_enabled=...) are public API with no presence in the docs book, and nothing renders or executes the examples/snippets/ files. Concretely: docs/advanced/identity-assertion.md, a new page after OAuth clients in the nav. It covers both halves: the client provider (and its inverted trust model: the authorization server is configuration, never discovered from the MCP server) and the authorization-server hook. It is careful to keep the two parties apart that the rest of the book is allowed to blur: the enterprise IdP that issues the ID-JAG, and the MCP authorization server that accepts it. The two existing auth pages each gain a one-paragraph cross-reference. docs_src/identity_assertion/: the page's two included examples. The client uses the modern Client API with an in-process stand-in IdP. The authorization server really validates the ID-JAG with pyjwt (signature, typ, iss/aud/exp, the client_id match, jti replay, and an ID-JAG for a resource it does not serve is refused with invalid_target) instead of stubbing the validation out. tests/docs_src/test_identity_assertion.py proves the page's claims, including the whole grant end to end across two in-memory ASGI apps. The recorded wire is one 401, the issuer's well-known fetch, one POST /token, and the retried request: no /authorize, no /register, no protected-resource-metadata fetch. examples/stories/identity_assertion/: a self-verifying story (stand-in IdP, authorization server, bearer-gated MCP server, client), registered in the stories manifest and run by the tests/examples/ matrix over both server variants and both protocol eras. Two things worth a reviewer's attention: The shipped client snippet cannot complete the flow it demonstrates. examples/snippets/clients/identity_assertion_client.py sets issuer="http://localhost:8001", but an authorization server built with create_auth_routes serves its metadata issuer from an AnyHttpUrl, which renders a path-less origin as http://localhost:8001/. The provider's RFC 8414 §3.3 comparison is an exact string match, so discovery stops at issuer mismatch. It shipped that way because nothing executes the snippets, which is the gap this PR closes; the new page documents the exact-match rule and the end-to-end test pins it. I left the examples/snippets/ files untouched here and can fix or fold them into the story as a follow-up. tests/docs_src/test_shape.py loses the plain-ASCII typography check. It enforced a style preference (no em dashes, curly quotes, arrows, section signs) as a hard CI failure across every book page and example, which also blocks legitimate typography such as the section sign in an RFC citation (RFC 7523 §3) that the SDK's own docstrings already use. The plain-ASCII style stays as the convention the book follows; the gate goes. How Has This Been Tested? ./scripts/test (the full suite, 100% branch coverage, strict-no-cover), pre-commit run --all-files, and uv run mkdocs build --strict are green. The new docs test wires the page's two example files together and runs the whole grant in memory, asserting the request sequence, the exact token-request form, and that the sub the IdP signed is what get_access_token().subject reports inside a tool. The story passes the tests/examples/ matrix (both server variants, both protocol eras), and its README commands run for real: uv run python -m stories.identity_assertion.client --http self-hosts a uvicorn server and exits OK. Breaking Changes None. Docs, examples, and tests only; nothing under src/ changes. Types of changes Bug fix (non-breaking change which fixes an issue) New feature (non-breaking change which adds functionality) Breaking change (fix or feature that would cause existing functionality to change) Documentation update Checklist I have read the MCP Documentation My code follows the repository's style guidelines New and existing tests pass locally I have added appropriate error handling I have added or updated documentation as needed Additional context The page presents this as an optional extension (Enterprise-Managed Authorization), not as part of a protocol release, and is deliberate about the two RFCs: obtaining the ID-JAG from the IdP is an RFC 8693 token exchange and out of the SDK's scope; what the SDK implements on both sides is the RFC 7523 jwt-bearer presentation of it. (#2988's title says RFC 8693; the merged implementation is RFC 7523, per the extension spec.) Also moves the stories README's mrtr row out of the "deferred" table, where it was stale: it has been runnable since #2998. AI Disclaimer

Open Graph Description: Documentation for the Identity Assertion Authorization Grant (SEP-990) that #2988 added. That PR shipped the implementation with two snippets under examples/snippets/ and a migration-guide entry; t...

X Description: Documentation for the Identity Assertion Authorization Grant (SEP-990) that #2988 added. That PR shipped the implementation with two snippets under examples/snippets/ and a migration-guide entry; t...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3004

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width