| name | modelcontextprotocol-python-sdk-context |
| description | Answers questions about the official Model Context Protocol (MCP) Python SDK (`mcp` package on PyPI, `modelcontextprotocol/python-sdk` on GitHub). Tracks the `main` branch (v2 pre-alpha — `MCPServer`/snake_case/constructor-`on_*` handlers). Use when working with MCP servers or clients in Python, debugging v1→v2 migrations, or answering questions about tools, resources, prompts, transports, OAuth, or experimental tasks. References load on demand from `references/`. |
Context navigator
Overview
This navigator catalogs references for the official MCP Python SDK at GitHub SHA 3eb579948a4719d606d2adbd1f3f69371c9c0f48 (HEAD of main on 2026-05-26). HEAD is v2 pre-alpha; the current stable release lives on the v1.x branch and uses the older FastMCP / camelCase / decorator-based APIs. All references in this contextualizer document v2 syntax — if you have v1 code in front of you, start with the migration reference.
When asked a question this navigator's domain covers:
- Scan the Catalog below for the matching topic.
- Follow the link to read the reference file.
- If the question spans multiple references, consult the Cross-reference map.
- If a reference points at a source URL for deeper detail, follow it only if the reference itself didn't answer the question.
Claims policy
Cite by default, and make load-bearing claims verifiable:
- Inline-cite every load-bearing claim with its SHA-pinned permalink — the
https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<start>-L<end> link the reference gives for that fact (versions, defaults, signatures, deprecations, behavior a user could get wrong by guessing). Put the permalink inline, on the claim. Use a bare filename parenthetical (e.g. (reference-name.md)) only when the reference genuinely provides no permalink. This inline permalink is what the grounded-citation eval (SELF-AUDIT Check 8) grades.
- Don't cite orientational prose — "what is X?", "when did X launch?" — answer those from this navigator alone; opening a reference is itself a citation gesture.
- End with a one-line provenance footer, emitted italic, formatted
*References consulted: foo.md, bar.md. Grounded in {{LIBRARY}}@{{VERSION}} — [reference index]({{INDEX_URL}}).* The footer is a summary of what you read — not a substitute for the inline permalinks on the claims. The {{LIBRARY}} / {{VERSION}} / {{INDEX_URL}} tokens are agent-substituted at answer time, so they appear literally in the stamped SKILL.md.
- If no reference was opened, say so in the footer ("Answered from general knowledge — no {{LIBRARY}} references consulted") — never fake it.
The voice is competent and careful — no "as an AI assistant" hedging.
Catalog
| Reference | Description |
|---|
| overview | Orientation: what the SDK is, v1.x vs v2 split, top-level package layout, recommended entry points (MCPServer vs lowlevel Server), AGENTS.md ground rules (uv-only, anyio, 100% coverage). Start here for new readers. |
| mcpserver | High-level server via MCPServer (formerly FastMCP): @tool/@resource/@prompt decorators, Context injection, structured output, Image/Audio/Icon, lifespan, elicitation, sampling, run() and ASGI mounting. The default path for new server code. |
| lowlevel-server | Lowlevel Server class: constructor on_* keyword handlers (no decorators in v2), full handler-name reference table, when to drop down from MCPServer, no automatic return-value wrapping, streamable_http_app() from the lowlevel. |
| client | Writing MCP clients: Client (in-memory or remote), ClientSession for raw streams, ClientSessionGroup for fan-out, calling tools/resources/prompts, paginated lists with PaginatedRequestParams, the four callbacks (sampling, elicitation, list-roots, logging). |
| transports | MCP transports in the Python SDK: stdio, SSE (legacy), streamable HTTP (recommended), and websocket. Covers stdio_client / streamable_http_client / sse_client signatures, server-side stdio_server and MCPServer.streamable_http_app(), mounting in Starlette/ASGI, the v2 httpx.AsyncClient injection pattern, DNS-rebinding protection, and the session-ID capture workaround. |
| auth | OAuth 2.1 authentication in the MCP Python SDK. Server-side: TokenVerifier protocol, OAuthAuthorizationServerProvider, AuthSettings, bearer-token middleware, and the resource-server vs. authorization-server modes. Client-side: OAuthClientProvider with PKCE, TokenStorage interface, callback flow. |
| types | mcp.types — protocol Pydantic models with snake_case attribute access (camelCase wire), _adapter TypeAdapter instances that replaced RootModel unions, ContentBlock taxonomy, str-vs-AnyUrl URI shift, JSON-RPC error code constants, _meta extension field. |
| migration-v1-to-v2 | Concise port-your-code cheatsheet. FastMCP→MCPServer, McpError→MCPError, decorators→on_* kwargs, streamablehttp_client→streamable_http_client, camelCase→snake_case, AnyUrl→str, removed helpers, search-and-replace strategy. |
| experimental-tasks | Experimental async-tasks feature: lifecycle states, enable_tasks() setup, ServerTaskContext, client-side call_tool_as_task + poll_task, TaskStore interface. Tracks the draft MCP spec — API may change without notice. |
Cross-reference map
- "How do I build a server?" → start at
mcpserver for the happy path; drop to lowlevel-server only if you need handler-level protocol control. The auth reference layers on top of either.
- "My v1 code is broken on
main." → migration-v1-to-v2 is the entry point; it links out to mcpserver, lowlevel-server, transports, and types for the patterns the migration touches.
- "Why won't my client connect?" →
transports first (especially the httpx.AsyncClient injection pattern and DNS-rebinding rules); client second for ClientSession vs Client semantics.
- "What does this field name mean?" or "Why is
RootModel.root gone?" → types.
- "How do I authenticate?" →
auth; pairs with transports (streamable HTTP carries the bearer token) and the URL-elicitation pattern in mcpserver.
- "How do I get the authenticated OAuth user inside my tool?" →
auth for the get_access_token() accessor and AccessToken.subject/.claims; pairs with mcpserver (the Context.client_id gotcha — that property reads MCP _meta, not the bearer token).
- "My tool needs to take a long time." →
experimental-tasks; pairs with mcpserver (Context/progress) and lowlevel-server (where tasks register today).
- "What ground rules apply to patches against the SDK?" →
overview's "Repo ground rules" section (uv-only, anyio, 100% coverage, no @deprecated shims on main).
Markdown style for generated references
Reference files use soft wrapping: one paragraph per line, no hard line breaks at fixed column widths. Editors and rendered Markdown reflow at viewport width. Do not insert manual line breaks within a paragraph to keep lines under ~80 columns — that produces mid-sentence breaks in rendered output and makes diffs noisier. Code blocks, tables, bullet lists, and headings follow their own rules; this directive applies to prose paragraphs only.
Instructions to Claude
When loading a reference file, the path syntax depends on the platform:
-
Claude Code: Read the reference using the platform-provided skill-directory variable: Read $CLAUDE_SKILL_DIR/references/<source-slug>-<topic>.md
-
Claude Desktop: Read the reference using a relative path; the platform resolves it from the skill's installed location: Read references/<source-slug>-<topic>.md
Loading rules:
- Load one reference at a time unless the Cross-reference map says to load both.
- If the primary reference doesn't fully answer the question, follow any source URL pointers it provides for deeper detail.
- Do not eagerly load companion files; only follow companion links when the primary reference says to.
- If the user's question is clearly out of scope for this contextualizer, don't invoke this skill at all.
Progressive disclosure
References prioritize curated insight over re-specifying upstream sources:
- Gotchas, cross-system patterns, and "why" context are kept in the reference (curation value).
- Exact schemas, API signatures, and parameter lists are summarized in the reference and linked to their authoritative source via source URLs.
When a reference includes a source URL pointer, follow it only when the reference's own summary didn't cover the question. The contextualizer is optimized for the common case; the upstream source is the long tail.
Optional SKILL.json sibling
This navigator MAY ship a SKILL.json sibling alongside this SKILL.md for machine-readable consumers (downstream tools and non-Claude agents that prefer structured metadata to markdown parsing). The sibling is purely opt-in additive — contextualizers without it pass verification unchanged.
When SKILL.json is present, the ## Catalog table above, the SKILL.json catalog[] entries, and the references/<source-slug>-*.md files on disk must be in three-way correspondence. Entries carrying "draft": true in SKILL.json are excluded from this trijection and surface as a one-line summary at verify time. The skill-json-trijection named check fires only when SKILL.json is present; absence is a silent-skip pass.
Full schema: see 02-artifact-contract.md §"SKILL.json".
