v1.3.0

Python SDK 1.3.0 - 2025-02-20

Breaking Changes

• Context API Changes: The Context logging methods (info, debug, warning, error) are now async and must be awaited. (#172)

New Features

Lifespan Support

Added comprehensive server lifecycle management through the lifespan API:

@dataclass
class AppContext:
    db: Database

@asynccontextmanager
async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
    try:
        await db.connect()
        yield AppContext(db=db)
    finally:
        await db.disconnect()

mcp = FastMCP("My App", lifespan=app_lifespan)

@mcp.tool()
def query_db(ctx: Context) -> str:
    db = ctx.request_context.lifespan_context["db"]
    return db.query()

(#203)

Async Resources

Added support for async resource functions in FastMCP:

@mcp.resource("users://{user_id}")
async def get_user(user_id: str) -> str:
    async with client.session() as session:
        response = await session.get(f"/users/{user_id}")
        return await response.text()

(#157)

Concurrent Request Handling

Made message handling concurrent, allowing multiple requests to be processed simultaneously. (#206)

Request Cancellation

Added support for canceling in-flight requests and cleaning up resources. (#167)

Server Instructions

Added support for the instructions field in server initialization, allowing servers to provide usage guidance. (#150)

Bug Fixes

• Fixed progress reporting for first tool call by correcting progress_token handling (#176)
• Fixed server crash when using debug logging (#158)
• Fixed resource template handling in FastMCP server (#137)
• Fixed MIME type preservation in resource responses (#170)
• Fixed documentation for environment variables in CLI commands (#149)
• Fixed request ID preservation in JSON-RPC responses (#205)

Dependency Updates

• Relaxed version constraints for better compatibility:
  • pydantic: Changed from >=2.10.1,<3.0.0 to >=2.7.2,<3.0.0
  • pydantic-settings: Changed from >=2.6.1 to >=2.5.2
  • uvicorn: Changed from >=0.30 to >=0.23.1
    (#180)

Examples

• Added a simple chatbot example client to demonstrate SDK usage (#98)

Client Improvements

• Added client support for sampling, list roots, and ping requests (#218)
• Added flexible type system for tool result returns (#222)

Compatibility and Platform Support

• Updated URL validation to allow file and other nonstandard schemas (#68fcf92)
• Force stdin/stdout encoding to UTF-8 for cross-platform compatibility (#d92ee8f)

Internal Improvements

• Improved type annotations for better IDE support (#181)
• Added comprehensive tests for SSE transport (#151)
• Updated types to match 2024-11-05 MCP schema (#165)
• Refactored request and notification handling for better code organization (#166)

New Contributors

• @salman1993 made their first contribution in #150
• @micpst made their first contribution in #158
• @3choff made their first contribution in #98
• @cr7258 made their first contribution in #149
• @sheffler made their first contribution in #172
• @jeremydanielfox made their first contribution in #180
• @zzstoatzz made their first contribution in #181

Full Changelog: v1.2.1...v1.3.0

v1.3.0rc1

Python SDK 1.3.0 Release Candidate 1

Breaking Changes

• Context API Changes: The Context logging methods (info, debug, warning, error) are now async and must be awaited. (#172)
• Resource Response Format: Standardized resource response format to return both content and MIME type. Method read_resource() now returns a tuple of (content, mime_type) instead of just content. (#170)

New Features

Lifespan Support

Added comprehensive server lifecycle management through the lifespan API:

@dataclass
class AppContext:
    db: Database

@asynccontextmanager
async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
    try:
        await db.connect()
        yield AppContext(db=db)
    finally:
        await db.disconnect()

mcp = FastMCP("My App", lifespan=app_lifespan)

@mcp.tool()
def query_db(ctx: Context) -> str:
    db = ctx.request_context.lifespan_context["db"]
    return db.query()

(#203)

Async Resources

Added support for async resource functions in FastMCP:

@mcp.resource("users://{user_id}")
async def get_user(user_id: str) -> str:
    async with client.session() as session:
        response = await session.get(f"/users/{user_id}")
        return await response.text()

(#157)

Concurrent Request Handling

Made message handling concurrent, allowing multiple requests to be processed simultaneously. (#206)

Request Cancellation

Added support for canceling in-flight requests and cleaning up resources. (#167)

Server Instructions

Added support for the instructions field in server initialization, allowing servers to provide usage guidance. (#150)

Bug Fixes

• Fixed progress reporting for first tool call by correcting progress_token handling (#176)
• Fixed server crash when using debug logging (#158)
• Fixed resource template handling in FastMCP server (#137)
• Fixed MIME type preservation in resource responses (#170)
• Fixed documentation for environment variables in CLI commands (#149)
• Fixed request ID preservation in JSON-RPC responses (#205)

Dependency Updates

• Relaxed version constraints for better compatibility:
  • pydantic: Changed from >=2.10.1,<3.0.0 to >=2.7.2,<3.0.0
  • pydantic-settings: Changed from >=2.6.1 to >=2.5.2
  • uvicorn: Changed from >=0.30 to >=0.23.1
    (#180)

Examples

• Added a simple chatbot example client to demonstrate SDK usage (#98)

Internal Improvements

• Improved type annotations for better IDE support (#181)
• Added comprehensive tests for SSE transport (#151)
• Updated types to match 2024-11-05 MCP schema (#165)
• Refactored request and notification handling for better code organization (#166)

v1.2.1

Release Notes

Features

• Added support for async resources
• Added example and test for parameter descriptions in FastMCP tools

Bug Fixes

• Fixed MCP install command with environment variables
• Fixed resource template handling in FastMCP server (#129)
• Fixed package in the generated MCP run config (#128)
• Fixed FastMCP logger debug output
• Fixed handling of strings containing numbers in FastMCP (@sd2k, #142)

v1.2.0

A big thank you to @jlowin for the creation of the fantastic FastMCP, which is now included into the MCP SDK.

Backwards Compatibility

This release is semver compatible. Existing code will continue to work, unless code relied on re-experts from mcp.server. Version 2.0 of the SDK will remove the use of mcp.server.Server in favour of mcp.server.lowlevel.Server. To stay compatible with upcoming major versions, please change from mcp.server import Server to from mcp.server.lowlevel import Server.

Major Features

FastMCP Integration

• Integrated FastMCP as the recommended high-level server framework
• Added new mcp.server.fastmcp module with simplified decorator-based API
• Introduced FastMCP class for easier server creation and management
• Added comprehensive documentation and examples for FastMCP usage

New CLI Package

• Added new CLI package for improved developer experience
• Introduced mcp dev command for local development and testing
• Added mcp install command for Claude Desktop integration
• Added mcp run command for direct server execution

Improvements

Documentation

• Completely revamped README with new structure and examples
• Added detailed sections on core concepts (Resources, Tools, Prompts)
• Updated documentation to recommend FastMCP as primary API
• Added sections on development workflow and deployment options
• Improved example server documentation

Developer Experience

• Added pre-commit hooks for code quality
• Updated to Pydantic 2.10.0 for improved type checking
• Added uvicorn as a dependency for better server capabilities

Bug Fixes

• Fixed encoding errors in STDIO client (@SecretiveShell)
• Fixed deprecation warnings in core components
• Fixed Pydantic field handling for meta fields
• Fixed type issues throughout the codebase
• Fixed example server READMEs
• Added constructor for McpError to allow setting fields (@allenporter)

Breaking Changes

• Deprecated direct usage of mcp.server in favor of mcp.server.fastmcp
• Updated import paths for FastMCP integration
• Changed recommended installation to include CLI features (pip install "mcp[cli]")

Contributors

Special thanks to all contributors who made this release possible, including:

• @jlowin (FastMCP)
• Oskar Raszkiewicz
• @allenporter
• @SecretiveShell
• @restlessronin

Full Changelog: v1.1.3...v1.2.0

v1.1.3

What's Changed

🐛 Bug Fixes

• Fixed encoding errors in STDIO client (@SecretiveShell)
• Fixed deprecation warnings
• Fixed pydantic Field usage with alias for _meta fields
• Added constructor for McpError to allow setting fields (@allenporter)

✨ Features

• Added version string parameter to Server constructor and initialization options (@restlessronin)

🙌 New Contributors

• @allenporter
• @SecretiveShell
• @restlessronin

Thank you for your contributions!

v1.2.0rc1

MCP Python SDK v1.2.0rc1 Release Notes

Major Features

FastMCP Integration

• Integrated FastMCP as the recommended high-level server framework
• Added new mcp.server.fastmcp module with simplified decorator-based API
• Introduced FastMCP class for easier server creation and management
• Added comprehensive documentation and examples for FastMCP usage

New CLI Package

• Added new CLI package for improved developer experience
• Introduced mcp dev command for local development and testing
• Added mcp install command for Claude Desktop integration
• Added mcp run command for direct server execution

Improvements

Documentation

• Completely revamped README with new structure and examples
• Added detailed sections on core concepts (Resources, Tools, Prompts)
• Updated documentation to recommend FastMCP as primary API
• Added sections on development workflow and deployment options
• Improved example server documentation

Developer Experience

• Added pre-commit hooks for code quality
• Updated to Pydantic 2.10.0 for improved type checking
• Added uvicorn as a dependency for better server capabilities

Bug Fixes

• Fixed deprecation warnings in core components
• Fixed Pydantic field handling for meta fields
• Fixed type issues throughout the codebase
• Fixed example server READMEs

Breaking Changes

• Deprecated direct usage of mcp.server in favor of mcp.server.fastmcp
• Updated import paths for FastMCP integration
• Changed recommended installation to include CLI features (pip install "mcp[cli]")

Contributors

Special thanks to all contributors who made this release possible, including:

• Jeremiah Lowin (FastMCP)
• Oskar Raszkiewicz

Full Changelog: v1.1.2...v1.2.0rc1

v1.1.2

Full Changelog: v1.1.1...v1.1.2

v1.1.1

Full Changelog: v1.1.0...v1.1.1

v1.1.0

What's Changed

• Fix first Python demo so it works without further modifications by @simonw in #66
• Fix experimental capabilities example by @jspahrsummers in #70
• Add handler for resource templates by @dsp-ant in #77
• Updated example in README.md for increased outreach by @miguelg719 in #82

New Contributors

• @simonw made their first contribution in #66
• @miguelg719 made their first contribution in #82

Full Changelog: v1.0.0...v1.1.0

1.0.0

We're excited to announce the first stable release of the Model Context Protocol (MCP) Python SDK! This release provides a complete implementation of the MCP specification, enabling seamless integration between LLM applications and context providers.

Features

Core Protocol Implementation

• Full implementation of MCP protocol v2024-11-05
• Robust client and server capabilities with async/await support
• Type-safe request/response handling using Pydantic models
• Support for all core MCP primitives:
  • Prompts and prompt templates
  • Resources and resource templates
  • Tools with JSON Schema validation
  • Progress tracking and notifications
  • Logging with severity levels

Transport Layer Support

• Standard input/output (stdio) transport
• Server-Sent Events (SSE) transport

Client Features

• Simple, intuitive client API
• Automatic protocol negotiation
• Request timeout handling
• Progress tracking
• Error handling with typed exceptions

Server Features

• Decorator-based request handlers
• Built-in capability negotiation
• Request context management
• Support for experimental capabilities
• Automatic request/response routing

Installation

# Using uv (recommended)
uv add mcp

# Using pip
pip install mcp

Basic Usage

Creating a Server

from mcp.server import Server
import mcp.types as types

server = Server("example-server")

@server.list_prompts()
async def handle_list_prompts() -> list[types.Prompt]:
    return [
        types.Prompt(
            name="example-prompt",
            description="An example prompt template",
            arguments=[
                types.PromptArgument(
                    name="arg1", 
                    description="Example argument",
                    required=True
                )
            ]
        )
    ]

# Run the server over stdio
async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
    await server.run(
        read_stream,
        write_stream,
        server.create_initialization_options()
    )

Creating a Client

from mcp import ClientSession, StdioServerParameters

async with mcp.client.stdio.stdio_client(
    StdioServerParameters(command="path/to/server")
) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        prompts = await session.list_prompts()

Requirements

• Python 3.10 or later
• anyio 4.6 or later
• pydantic 2.8.0 or later
• httpx 0.27 or later

Breaking Changes

This is the initial stable release, establishing the baseline API for future versions.

License

MIT License

---

For more information:

• Documentation
• Specification
• GitHub Discussions