MCP Python SDK

[!CAUTION] This README documents v2 of the MCP Python SDK — a pre-release (alpha/beta) line under active development. Do not use v2 in production. Pre-releases are published to PyPI as 2.0.0aN / 2.0.0bN, and each pre-release may contain breaking changes from the previous one. Pin an exact version and expect to update your code when you bump the pin.

v1.x is the only stable release line and remains recommended for production. It lives on the v1.x branch and continues to receive critical bug fixes and security patches; see the v1.x README for its documentation. pip and uv don't select a pre-release unless you explicitly request one, so existing installs are unaffected. If your package depends on mcp, add a <2 upper bound to your version constraint (for example mcp>=1.27,<2) before the stable release lands.

v2 is a major rework of the SDK, both to support the 2026-07-28 MCP specification release and to fix long-standing architectural issues. See What's new in v2 for the tour of what changed, and the migration guide for every breaking change. Stable v2 is targeted for 2026-07-27, alongside the spec release. Try the pre-releases and tell us what breaks, or discuss in #python-sdk-dev on the MCP Contributors Discord.

Documentation

The documentation lives at https://py.sdk.modelcontextprotocol.io/v2/.

It has a Get started guide, What's new in v2, the API reference, and the migration guide.

What is MCP?

The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but designed for LLM interactions. With this SDK you can:

• Build MCP servers that expose tools, resources, and prompts to any MCP host
• Build MCP clients that connect to any MCP server
• Speak every standard transport: stdio, Streamable HTTP, and SSE

Requirements

Python 3.10+.

Installation

uv add "mcp[cli]==2.0.0b1"          # or: pip install "mcp[cli]==2.0.0b1"

The pin matters while v2 is in pre-release: an unpinned install resolves to the latest stable v1.x, which this README does not describe. Check PyPI for the newest pre-release, and use uv run --with "mcp==2.0.0b1" for one-off commands.

A server in 15 lines

Create a server.py:

from mcp.server import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

Full example: docs_src/index/tutorial001.py

That's a complete MCP server: one tool, one templated resource. Open it in the [MCP Inspector](https://github.com/mode