Skip to content

README.v2.md

Latest commit

 

History

History
132 lines (86 loc) · 5.84 KB

README.v2.md

File metadata and controls

132 lines (86 loc) · 5.84 KB
Raw

MCP Python SDK

Python implementation of the Model Context Protocol (MCP)

PyPI MIT licensed Python Version Documentation Protocol Specification

Important: this documents v2 of the SDK, which is in alpha. Pre-releases are published to PyPI as 2.0.0aN, and each alpha may contain breaking changes from the previous one.

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 the migration guide for what's changed. We're targeting a beta on 2026-06-30 and a stable v2 on 2026-07-27, alongside the spec release. Before stable, we plan to add a significant set of backwards compatibility shims so the final upgrade is much smaller than today's diff.

v1.x is the only stable release line and remains recommended for production. It is in maintenance mode and continues to receive critical bug fixes and security patches. Installers never select a pre-release unless you opt in (for example pip install mcp==2.0.0a3), 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.

Try the alpha and tell us what breaks: #python-sdk-dev on the MCP Contributors Discord. For v1 documentation, see the v1.x README.

Documentation

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

It has the full tutorial, 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.0a3"          # or: pip install "mcp[cli]==2.0.0a3"

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.0a3" 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:

uv run mcp dev server.py

Call add with a=1, b=2 and you get 3 back.

Notice what you did not write: no JSON Schema (a: int, b: int is the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.

The tutorial takes it from here.

A client in 10 lines

The same package is a full MCP client. Client connects to a URL, a stdio subprocess, a custom transport, or (for tests) straight to a server object in memory with no transport at all:

import asyncio

from mcp import Client

from server import mcp


async def main() -> None:
    async with Client(mcp) as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}


asyncio.run(main())

Swap mcp for "http://localhost:8000/mcp" and the exact same code talks to a remote server.

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

License

This project is licensed under the MIT License. See the LICENSE file for details.