python-sdk

FastMCP provides a high-level decorator-driven API (@mcp.tool(), @mcp.resource(), @mcp.prompt()) that automatically wraps Python function return values into MCP protocol types and injects context via type annotations. Uses Python's inspect module to extract function signatures and Pydantic models to generate JSON schemas for tool parameters, eliminating manual protocol message construction. The framework handles automatic serialization of return values and context injection through type hints, reducing boilerplate from ~50 lines to ~5 lines per tool.

The Server class in src/mcp/server/lowlevel/server.py provides constructor-based handler registration (on_list_tools=..., on_call_tool=..., on_read_resource=...) for developers needing fine-grained control over MCP protocol behavior. Handlers receive raw protocol request objects and must explicitly construct Pydantic-validated response types, enabling custom logic for authentication, caching, dynamic tool generation, and protocol negotiation. This low-level API bypasses FastMCP's abstractions and exposes the full JSON-RPC 2.0 message lifecycle.

The SDK supports progress reporting for long-running operations through the progress notification mechanism. Servers can send progress updates (progress_start, progress_update, progress_end) to clients during tool execution, allowing clients to display progress bars or status updates. Progress notifications are sent asynchronously without blocking tool execution, enabling real-time feedback for operations that take seconds or minutes to complete.

The SDK implements MCP capability negotiation through the initialize protocol method, where clients and servers exchange supported capabilities (tools, resources, prompts, notifications, etc.). Both sides declare their capabilities, and the protocol layer validates compatibility. This enables forward/backward compatibility: older clients can work with newer servers by ignoring unsupported capabilities, and servers can adapt behavior based on client capabilities.

The SDK includes an experimental task system (src/mcp/types.py) that enables servers to define multi-step operations where clients can submit tasks and receive results asynchronously. Tasks support progress tracking, cancellation, and result streaming. This is an experimental feature designed for operations that span multiple protocol round-trips or require client-side decision making between steps.

The SDK supports multiple content types (text, image, PDF, etc.) through a unified TextContent and ImageContent type system. Tool results can return structured content with MIME types, enabling rich output beyond plain text. The protocol layer automatically serializes content based on type, and clients can handle different content types appropriately (display images, render PDFs, etc.). This enables tools to return complex outputs without requiring clients to parse text representations.

The SDK abstracts transport mechanisms (STDIO, SSE, StreamableHTTP) through a uniform (read_stream, write_stream) interface that carries SessionMessage objects, allowing application code to remain transport-agnostic. ServerSession and ClientSession classes manage bidirectional communication, message routing, and lifecycle events independently of the underlying transport. StreamableHTTPSessionManager adds production features: session resumability via event stores, DNS rebinding protection, and stateful session recovery across connection interruptions.

The SDK implements the full MCP protocol as JSON-RPC 2.0 using Pydantic's discriminated unions (src/mcp/types.py) to automatically route messages based on the 'method' field. All protocol messages (requests, responses, notifications) are defined as Pydantic models with strict validation, enabling type-safe message handling and automatic serialization/deserialization. The discriminated union pattern eliminates manual message routing logic and provides compile-time type checking for protocol compliance.

ClientSession provides a high-level async API for making MCP requests (list_tools, call_tool, read_resource, etc.) and subscribing to server notifications through callback handlers. The client automatically manages request IDs, correlates responses to requests, and handles both request/response patterns and server-initiated notifications. Built on asyncio, it supports concurrent requests with proper error handling and timeout management, abstracting away JSON-RPC 2.0 request ID correlation.

The SDK uses Python's inspect module to extract function signatures and Pydantic's schema generation to automatically create JSON schemas for tool parameters. Type hints (int, str, list, Pydantic models) are converted to JSON Schema Draft 7 format, with docstrings parsed for parameter descriptions. This enables LLMs to understand tool parameters without manual schema definition, supporting complex nested types, optional parameters, and default values through Pydantic's validation framework.

FastMCP supports context injection by examining function parameter type annotations and automatically providing matching context objects (RequestContext, ServerSession, etc.) at runtime. A tool function can declare parameters like `context: RequestContext` and FastMCP will inject the current request context without requiring explicit parameter passing. This pattern is implemented through Python's inspect module and type annotation introspection, enabling clean separation between business logic and protocol-level context.

The SDK supports server-side authentication through token verification and authorization configuration. Servers can register authorization handlers that validate client tokens (JWT, API keys, etc.) before processing requests. The authorization layer integrates with ServerSession to enforce per-session authorization policies, enabling fine-grained access control over tools, resources, and prompts. Authorization failures return JSON-RPC 2.0 error responses with appropriate error codes.

The SDK supports MCP Resources (static or dynamic content accessible via URI) and Prompts (reusable instruction templates) through decorator-based definitions (@mcp.resource(), @mcp.prompt()). Resources can be static (file paths, URLs) or dynamic (generated at request time from handler functions). Prompts support template variables that LLMs can fill in. Both are registered with the server and advertised to clients through list_resources and list_prompts protocol methods, enabling clients to discover and consume them.

FastMCP supports lifespan management through @mcp.server.lifespan context managers that execute initialization and cleanup code when the server starts and stops. The lifespan pattern (async context manager) allows servers to set up resources (database connections, thread pools, caches) on startup and clean them up on shutdown. This integrates with the server lifecycle, ensuring resources are properly released even if the server crashes or is forcefully terminated.