Welcome to the MCP Python SDK
Relevant source files
The following files were used as context for generating this wiki page:
The MCP Python SDK provides a comprehensive framework for building servers and clients that adhere to the Model Context Protocol. The core of the server-side implementation is the FastMCP class, which offers a high-level, decorator-based API for rapidly developing MCP-compliant services. This SDK is designed to simplify the creation of complex, interactive applications by abstracting the protocol's details and providing robust features like tool management, resource handling, authentication, and multiple communication transports.
The repository includes a collection of simple examples to demonstrate the usage of the SDK for building various types of servers, such as those with tool support, authentication, and different transport mechanisms. These examples serve as a practical starting point for developers looking to integrate with the MCP ecosystem.
Sources: tests/server/fastmcp/test_server.py:15, examples/README.md:3-5
Core Concepts & Architecture
The FastMCP framework is built around three primary concepts: Tools, Resources, and Prompts. These components are managed by the central FastMCP instance, which exposes them to clients over a chosen transport.
This diagram illustrates the high-level architecture, where a client communicates through a transport layer to the FastMCP server, which then dispatches requests to the appropriate manager for tools, resources, or prompts.
Sources: tests/server/fastmcp/test_server.py, tests/server/fastmcp/test_integration.py, examples/servers/simple-tool/README.md:6-9
Development and Contribution
Development Setup
To contribute to the SDK, you need Python 3.10+ and uv. The setup process involves forking the repository, cloning it, and installing dependencies.
- Install Dependencies:
uv sync --frozen --all-extras --dev - Set up Pre-commit Hooks:
uv tool install pre-commit --with pre-commit-uv --force-reinstall
Sources: CONTRIBUTING.md:7-16
Development Workflow
The development workflow follows standard Git practices, emphasizing testing and code quality.
This diagram outlines the steps for contributing code, from branching to merging a pull request.
Sources: CONTRIBUTING.md:18-43, CLAUDE.md:19-25
Code Quality and Tooling
The project enforces strict code quality standards using a suite of Python tools managed by uv.
| Tool | Command | Purpose |
|---|---|---|
| uv | uv sync, uv run | Package and environment management. pip is not used directly. |
| ruff | uv run ruff check/format | Linting and code formatting to enforce a consistent style. |
| pyright | uv run pyright | Static type checking to ensure type safety. |
| pytest | uv run pytest | Running the test suite, including async tests with anyio. |
| pre-commit | pre-commit run | Runs checks automatically on every commit. |
Key requirements:
- Type hints are mandatory for all functions.
- Public APIs must have docstrings.
- Follow existing code patterns precisely.
Sources: CONTRIBUTING.md:45-51, CLAUDE.md:6-18
Server Features (FastMCP)
The FastMCP class is the primary entry point for creating an MCP server. It provides decorators to easily define tools, resources, and prompts.
Sources: tests/server/fastmcp/test_server.py:15
Tools
Tools are functions that a client can execute on the server. They are defined using the @mcp.tool() decorator.
- Definition: A simple Python function decorated with
@mcp.tool(). - Arguments: Tool arguments are inferred from the function's type hints.
- Return Value: The return value is converted into an MCP
ContentBlock. Primitive types, Pydantic models, and dataclasses are automatically converted to structured output. - Title: A user-friendly
titlecan be provided, which takes precedence over the function name for display purposes.
# Source: tests/server/fastmcp/test_server.py:149-153
mcp = FastMCP()
@mcp.tool()
def sum(x: int, y: int) -> int:
return x + y
Sources: tests/server/fastmcp/test_server.py:149-153, tests/server/fastmcp/test_title.py:12-16
Resources
Resources represent data that can be read by a client. They are defined using the @mcp.resource() decorator, which takes a URI as its first argument.
- Static Resources: A function with no parameters linked to a static URI.
- Resource Templates: If the URI contains placeholders (e.g.,
r://{x}), the function becomes a template. The placeholder names must match the function's arguments. - Resource Types: The SDK supports
FunctionResourcefor dynamically generated content andFileResourcefor serving static files.
# Source: tests/server/fastmcp/test_server.py:649-653
mcp = FastMCP()
@mcp.resource("resource://{name}/data")
def get_data(name: str) -> str:
return f"Data for {name}"
Sources: tests/server/fastmcp/test_server.py:649-653, 563-571, tests/server/fastmcp/servers/test_file_server.py
Prompts
Prompts are templates for generating messages, often used to guide language models. They are defined with the @mcp.prompt() decorator.
- Definition: A function decorated with
@mcp.prompt()that returns a message or list of messages. - Arguments: Like tools, arguments are inferred from type hints.
- Description: The function's docstring is used as the prompt's description unless one is provided explicitly.
# Source: tests/server/fastmcp/test_server.py:898-902
mcp = FastMCP()
@mcp.prompt()
def fn(name: str) -> str:
"""This is the function docstring."""
return f"Hello, {name}!"
Sources: tests/server/fastmcp/test_server.py:898-902
Context Injection
For advanced use cases, tools and resources can receive a Context object. This object provides access to the underlying server session, enabling features like sending log messages or progress notifications.
To use it, add a parameter type-hinted with Context to your function.
# Source: tests/server/fastmcp/test_server.py:794-798
async def logging_tool(msg: str, ctx: Context[ServerSession, None]) -> str:
await ctx.debug("Debug message")
await ctx.info("Info message")
return f"Logged messages for {msg}"
Sources: tests/server/fastmcp/test_server.py:749-756, 794-798
Communication Transports
The SDK supports multiple communication transports for client-server interaction. A FastMCP instance can generate a Starlette application for a specific transport.
- SSE (Server-Sent Events):
mcp.sse_app() - StreamableHTTP:
mcp.streamable_http_app() - Stdio: The
stdio_clientcan be used to run a server command and communicate over standard I/O.
The integration test suite validates functionality across both SSE and StreamableHTTP transports, ensuring consistent behavior.
Sources: tests/server/fastmcp/test_integration.py:173-181, examples/servers/simple-tool/README.md:6-9, examples/servers/simple-streamablehttp/README.md:13-16
Authentication
The SDK provides robust OAuth 2.0 authentication support, complying with modern specifications like RFC 9728 for resource discovery. The recommended architecture separates the Authorization Server (AS), which handles user authentication and token issuance, from the Resource Server (RS), which is the MCP server itself.
RFC 9728 Discovery Flow
The client discovers the authorization server through the resource server.
This diagram shows the standard flow where a client first queries the MCP server (RS) to find the AS, then performs the OAuth flow with the AS to get a token, and finally uses that token to make authenticated calls to the RS.
Sources: examples/servers/simple-auth/README.md:4-5, 31-46, tests/server/fastmcp/auth/test_auth_integration.py
Key Endpoints
| Endpoint | Location | Purpose |
|---|---|---|
/.well-known/oauth-protected-resource | Resource Server | Informs the client where the Authorization Server(s) are located. |
/.well-known/oauth-authorization-server | Authorization Server | Provides OAuth metadata like token and authorization endpoints. |
/register | Authorization Server | Allows clients to dynamically register themselves. |
/authorize | Authorization Server | Starts the user authorization process. |
/token | Authorization Server | Exchanges authorization codes or refresh tokens for new access tokens. |
/revoke | Authorization Server | Revokes an existing access or refresh token. |
Sources: examples/servers/simple-auth/README.md:31-46, tests/server/fastmcp/auth/test_auth_integration.py:440-457
Documentation and Security
Project Documentation
The project's official documentation is built using MkDocs with the material theme. It includes a home page and an API reference generated from source code docstrings using mkdocstrings.
Sources: mkdocs.yml:1, 11-13, 80-94
Security Policy
Security is a top priority. The project's security program is managed on HackerOne. Any potential vulnerabilities should be reported through Anthropic's Vulnerability Disclosure Program submission form.
Sources: SECURITY.md:5-13