mcp

FastMCP provides a high-level decorator API (@mcp.tool(), @mcp.resource(), @mcp.prompt()) that automatically wraps Python functions into MCP protocol handlers. The framework uses Python type annotations to inject context (e.g., via @mcp.use_context), automatically serializes return values into MCP result types, and generates JSON-RPC 2.0 compliant messages without requiring manual handler construction. This eliminates boilerplate compared to the low-level Server API which requires explicit handler registration and result type construction.

The Server class (src/mcp/server/lowlevel/server.py) provides a constructor-based API where developers register handler functions via parameters like on_list_tools=..., on_call_tool=..., on_read_resource=... This approach gives full control over JSON-RPC message construction, session lifecycle, and protocol negotiation. Handlers receive raw MCP request objects and must explicitly construct result types, enabling fine-grained control over error handling, streaming responses, and capability negotiation.

The SDK supports progress notifications and streaming responses, allowing tools to report progress during long-running operations and stream partial results back to clients. Tools can emit ProgressNotification messages during execution, and clients can subscribe to these notifications to display progress to users. Streaming responses allow tools to return large results incrementally without buffering the entire response in memory.

The SDK implements MCP capability negotiation during the initialize handshake, allowing servers and clients to advertise their supported features and agree on a common protocol version. Servers declare which capabilities they support (tools, resources, prompts, sampling, etc.), and clients can query these capabilities to determine which features are available. This enables forward/backward compatibility — older clients can work with newer servers by only using supported features.

The SDK includes an experimental task system that allows servers to define complex, multi-step operations that clients can execute. Tasks are similar to tools but support more complex workflows with state management, branching, and progress tracking. This is an early-stage feature designed for future MCP extensions but is available for experimentation.

The SDK supports multiple content types (text, image, PDF, etc.) for tool results and resources, allowing servers to return richly formatted responses. Content types are abstracted behind a unified interface, enabling clients to handle different content types appropriately (render images, display PDFs, etc.). This enables tools to return structured, formatted output that LLMs and clients can interpret correctly.

The SDK abstracts transport mechanisms (STDIO, SSE, StreamableHTTP) behind a uniform (read_stream, write_stream) interface that carries SessionMessage objects. This allows server and client code to be transport-agnostic — the same handler logic works over STDIO for local development, SSE for browser clients, or StreamableHTTP for production deployments. The transport layer handles serialization/deserialization of JSON-RPC messages and manages connection lifecycle independently of application logic.

The protocol layer (src/mcp/types.py) defines all MCP messages using Pydantic discriminated unions keyed on the 'method' field. This enables automatic validation and routing of incoming JSON-RPC messages to the correct handler without manual type checking. The type system provides compile-time safety (via type hints) and runtime validation (via Pydantic), ensuring malformed messages are rejected before reaching application handlers. All protocol messages (requests, responses, notifications) are strongly typed.

The ClientSession class provides a high-level async API for making MCP requests (list_tools, call_tool, read_resource, etc.) with automatic response handling and error propagation. Developers call methods like await session.call_tool(name, arguments) and receive strongly-typed response objects without manually constructing JSON-RPC messages or handling protocol details. The API handles request/response correlation, timeout management, and server notification subscriptions.

The SDK automatically extracts Python function signatures and type annotations to generate JSON schemas for tool parameters. When a function is decorated with @mcp.tool(), the framework inspects the function's signature, docstring, and type hints to construct a ToolDefinition with a JSON schema describing required/optional parameters, types, and descriptions. This schema is used by LLMs to understand how to call the tool without requiring manual schema definition.

FastMCP uses Python type annotations to inject context objects (e.g., @mcp.use_context(RequestContext)) into tool functions. The framework maintains a context lifecycle tied to the request/response cycle, allowing tools to access request metadata, session information, and server state without explicit parameter passing. Lifespan hooks (@mcp.on_startup, @mcp.on_shutdown) manage resource initialization and cleanup across the server's lifetime.

The SDK allows servers to expose resources (files, documents, data) and prompts (instruction templates) via @mcp.resource() and @mcp.prompt() decorators. Resources are defined with URIs and can return text or binary content; prompts are templates with arguments that LLMs can discover and use. Both are registered in the server's capability list and can be queried by clients, enabling LLMs to access external data and use pre-defined instruction templates without hardcoding them.

The SDK supports server-side authentication via token verification and authorization configuration. Servers can validate client credentials (API keys, OAuth tokens) before processing requests, and implement role-based access control (RBAC) to restrict which clients can access which tools/resources. The authorization layer integrates with the ServerSession to enforce permissions at the request level.

StreamableHTTP is a production-grade transport that uses HTTP streaming (chunked transfer encoding) for bidirectional communication. It includes built-in session management via StreamableHTTPSessionManager, event stores for message persistence, and resumability — if a connection drops, the client can reconnect and resume the session without losing state. The transport includes DNS rebinding protection and configurable security features for production deployments.