Install & Compatibility
Where this runs
tested against v2.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
72MB installed
● package 72MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastMCP (bundled in mcp package)
✓ from mcp.server.fastmcp import FastMCP
mcp = FastMCP('My Server')
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
mcp.run(transport='stdio')
✗ from mcp import FastMCP
FastMCP lives at mcp.server.fastmcp, not at the top-level mcp namespace.
Low-level Server (legacy pattern)
✓ from mcp.server import Server
from mcp.server.stdio import stdio_server
✗ from mcp import Server
Low-level Server class for manual protocol handling. FastMCP is preferred for new servers — it derives tool schemas from type hints automatically.
Two server modes: stdio for local/Claude Desktop integration, streamable-http for production remote deployments. FastMCP derives tool schemas from Python type hints and docstrings automatically.
# Server (stdio transport — for Claude Desktop, local agents)
from mcp.server.fastmcp import FastMCP
mcp = FastMCP('My Server')
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
@mcp.resource('data://{name}')
def get_data(name: str) -> str:
"""Fetch named data"""
return f'Data for {name}'
@mcp.prompt()
def review_code(code: str) -> str:
return f'Please review this code:\n\n{code}'
if __name__ == '__main__':
mcp.run() # defaults to stdio
# ---
# Server (streamable-http — for remote/production deployments)
mcp = FastMCP('My Server', stateless_http=True, json_response=True)
if __name__ == '__main__':
mcp.run(transport='streamable-http') # serves at /mcp by default
# ---
# Client (connecting to an MCP server)
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import asyncio
async def main():
async with streamablehttp_client('http://localhost:8000/mcp') as (r, w, _):
async with ClientSession(r, w) as session:
await session.initialize()
tools = await session.list_tools()
result = await session.call_tool('add', {'a': 1, 'b': 2})
print(result)
asyncio.run(main())
Debug
Known issues
breakingSSE transport (Server-Sent Events) is deprecated as of MCP spec 2025-03-26. Servers built with transport='sse' still work but emit deprecation warnings. The replacement is streamable-http (single /mcp endpoint).fixReplace mcp.run(transport='sse') with mcp.run(transport='streamable-http'). For production use stateless_http=True, json_response=True. SSE endpoint was at /sse; streamable-http endpoint is at /mcp.
affects: all — deprecation introduced in spec 2025-03-26, SDK support from ~1.6+
breakingmcp v2 is in pre-alpha development on the main branch with significant transport layer changes. Users on v1.x should pin: mcp>=1.25,<2. Unpinned installs that pull from main will get pre-alpha code.fixPin to mcp>=1.25,<2 for stable production use. Monitor GitHub releases for v2 GA.
affects: v2 pre-alpha
breakingmcp.server.fastmcp.FastMCP (bundled, v1.0) and fastmcp.FastMCP (standalone package, v2.x+) are two different classes with diverging behaviour. They are not interchangeable. The standalone fastmcp package has additional features (auth, middleware, proxy, composition) not in the bundled version.fixPick one and use it consistently. For simple local tools: mcp package + from mcp.server.fastmcp import FastMCP. For production/remote/auth: pip install fastmcp + from fastmcp import FastMCP.
affects: all
breakingPassing host= and port= to FastMCP() constructor is deprecated. These arguments now belong on run(). Passing them to the constructor raises TypeError with a migration hint.fixMove transport config to run(): mcp.run(transport='streamable-http', host='0.0.0.0', port=8080)
affects: standalone fastmcp v2+
gotchamcp dev and mcp run CLI commands only work with FastMCP-based servers, not low-level Server class implementations.fixUse FastMCP for servers you want to run with the CLI. Low-level Server implementations must be run directly with Python.
affects: all v1.x
gotchaTool names must be valid identifiers: alphanumeric and underscores only. Names with hyphens, spaces, or special characters fail spec validation (SEP-986, enforced from mcp ~1.20+).fixUse snake_case for all tool names. e.g. get_weather not get-weather.
affects: mcp >=1.20
gotchaMCP clients call list_tools() on every agent run by default. For remote servers this adds latency. Both the official SDK and standalone fastmcp support cache_tools_list=True on the client to skip redundant list calls.fixSet cache_tools_list=True on client-side MCP server instances when tool definitions are stable.
affects: all
breakingRunning MCP servers on Python 3.13+ may encounter a `ValueError: I/O operation on closed file` during server startup. This occurs when Uvicorn's default `ColoredFormatter` attempts to access `sys.stdout.isatty()` in an environment where `sys.stdout` might be prematurely closed or not a TTY (e.g., certain container or CI/CD setups), likely exacerbated by Python 3.13's changes to standard stream lifecycle management. This error prevents the server from starting.fixSet the environment variable `NO_COLOR=1` before running the MCP server to disable colored logging, for example: `NO_COLOR=1 python your_script.py`. This tells Uvicorn not to attempt colored output, bypassing the `sys.stdout.isatty()` call that causes the error.
affects: all mcp versions on python>=3.13
Upgrade
Version history
2.1.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
anyiorequiredAsync I/O abstraction layer for stdio and HTTP transports.
httpxrequiredHTTP client for streamable-http transport.
starletterequiredASGI framework used internally for HTTP transport mounting.
pydanticrequiredSchema validation for tool input/output types.