modelcontextprotocol-python-sdk-context - SKILL.md Agent Skill

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".