{"id":45,"library":"mcp","title":"MCP Python SDK","description":"Official Python SDK for the Model Context Protocol (MCP), maintained by Anthropic. Used to build MCP servers (exposing tools, resources, prompts to LLMs) and MCP clients. Two important ecosystem distinctions: (1) mcp package bundles FastMCP 1.0 via mcp.server.fastmcp; (2) standalone 'fastmcp' package on PyPI is a separate, more feature-rich framework that diverged from the bundled version. v2 of the mcp package is in pre-alpha on main branch — v1.x is stable.","status":"active","version":"1.26.0","language":"python","source_language":"en","source_url":"https://github.com/modelcontextprotocol/python-sdk","tags":["mcp","model-context-protocol","tools","agents","protocol","anthropic","servers"],"install":[{"cmd":"pip install mcp","lang":"bash","label":"Python — official SDK (stable v1.x)"},{"cmd":"pip install 'mcp[cli]'","lang":"bash","label":"Python — with CLI tools (mcp dev, mcp run)"},{"cmd":"pip install fastmcp","lang":"bash","label":"Python — standalone FastMCP framework (separate package, superset of bundled FastMCP 1.0)"}],"dependencies":[{"reason":"Async I/O abstraction layer for stdio and HTTP transports.","package":"anyio","optional":false},{"reason":"HTTP client for streamable-http transport.","package":"httpx","optional":false},{"reason":"ASGI framework used internally for HTTP transport mounting.","package":"starlette","optional":false},{"reason":"Schema validation for tool input/output types.","package":"pydantic","optional":false}],"imports":[{"note":"FastMCP lives at mcp.server.fastmcp, not at the top-level mcp namespace.","wrong":"from mcp import FastMCP","symbol":"FastMCP (bundled in mcp package)","correct":"from mcp.server.fastmcp import FastMCP\nmcp = FastMCP('My Server')\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n    \"\"\"Add two numbers\"\"\"\n    return a + b\n\nmcp.run(transport='stdio')"},{"note":"Low-level Server class for manual protocol handling. FastMCP is preferred for new servers — it derives tool schemas from type hints automatically.","wrong":"from mcp import Server","symbol":"Low-level Server (legacy pattern)","correct":"from mcp.server import Server\nfrom mcp.server.stdio import stdio_server"}],"quickstart":{"code":"# Server (stdio transport — for Claude Desktop, local agents)\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP('My Server')\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n    \"\"\"Add two numbers\"\"\"\n    return a + b\n\n@mcp.resource('data://{name}')\ndef get_data(name: str) -> str:\n    \"\"\"Fetch named data\"\"\"\n    return f'Data for {name}'\n\n@mcp.prompt()\ndef review_code(code: str) -> str:\n    return f'Please review this code:\\n\\n{code}'\n\nif __name__ == '__main__':\n    mcp.run()  # defaults to stdio\n\n# ---\n\n# Server (streamable-http — for remote/production deployments)\nmcp = FastMCP('My Server', stateless_http=True, json_response=True)\n\nif __name__ == '__main__':\n    mcp.run(transport='streamable-http')  # serves at /mcp by default\n\n# ---\n\n# Client (connecting to an MCP server)\nfrom mcp import ClientSession\nfrom mcp.client.streamable_http import streamablehttp_client\nimport asyncio\n\nasync def main():\n    async with streamablehttp_client('http://localhost:8000/mcp') as (r, w, _):\n        async with ClientSession(r, w) as session:\n            await session.initialize()\n            tools = await session.list_tools()\n            result = await session.call_tool('add', {'a': 1, 'b': 2})\n            print(result)\n\nasyncio.run(main())","lang":"python","description":"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."},"warnings":[{"fix":"Replace 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.","message":"SSE 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).","severity":"breaking","affected_versions":"all — deprecation introduced in spec 2025-03-26, SDK support from ~1.6+"},{"fix":"Pin to mcp>=1.25,<2 for stable production use. Monitor GitHub releases for v2 GA.","message":"mcp 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.","severity":"breaking","affected_versions":"v2 pre-alpha"},{"fix":"Pick 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.","message":"mcp.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.","severity":"breaking","affected_versions":"all"},{"fix":"Move transport config to run(): mcp.run(transport='streamable-http', host='0.0.0.0', port=8080)","message":"Passing 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.","severity":"breaking","affected_versions":"standalone fastmcp v2+"},{"fix":"Use FastMCP for servers you want to run with the CLI. Low-level Server implementations must be run directly with Python.","message":"mcp dev and mcp run CLI commands only work with FastMCP-based servers, not low-level Server class implementations.","severity":"gotcha","affected_versions":"all v1.x"},{"fix":"Use snake_case for all tool names. e.g. get_weather not get-weather.","message":"Tool 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+).","severity":"gotcha","affected_versions":"mcp >=1.20"},{"fix":"Set cache_tools_list=True on client-side MCP server instances when tool definitions are stable.","message":"MCP 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Set 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.","message":"Running 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.","severity":"breaking","affected_versions":"all mcp versions on python>=3.13"}],"env_vars":{"optional":[{"name":"MCP_SERVER_NAME","note":"Used by some MCP clients to identify the server. Set programmatically in FastMCP('name') constructor."}],"required":[]},"last_verified":"2026-05-12T05:47:47.476Z","next_check":"2026-04-01T00:00:00.000Z","problems":[{"fix":"Ensure the 'mcp' package is installed using `pip install mcp`. If the issue persists, check for any local files or directories named 'mcp.py' in your project path and rename them.","cause":"The 'mcp' package is not installed in the active Python environment, or a local file or directory named 'mcp.py' is shadowing the installed package.","error":"ModuleNotFoundError: No module named 'mcp'"},{"fix":"Change the import statement to `from fastmcp import FastMCP` and then instantiate the server with `mcp = FastMCP(\"Server Name\")`.","cause":"This error occurs when attempting to import the `mcp` object directly from the standalone `fastmcp` package. The `fastmcp` package exports `FastMCP` as its primary class, not `mcp`.","error":"ImportError: cannot import name 'mcp' from 'fastmcp'"},{"fix":"Upgrade the `mcp` package to a compatible version using `pip install --upgrade mcp` or `pip install \"mcp>=1.23.0\"` to ensure you have the necessary types.","cause":"This typically indicates a version incompatibility where the installed `mcp` package is older than required by the code, missing recently introduced types or attributes like `ToolUseContent`.","error":"AttributeError: module 'mcp.types' has no attribute 'ToolUseContent'"},{"fix":"Troubleshoot the MCP server itself by checking its logs for specific errors. Ensure the server process is stable and configured correctly (e.g., verifying `command`, `args`, `cwd`, and `env` in its configuration). Restarting the server or killing orphaned Python processes may also resolve the issue.","cause":"This is a generic error indicating that the MCP server, often running as a separate process, has malfunctioned, crashed, or unexpectedly terminated, causing the client to lose its connection.","error":"MCP error -32000: Connection closed"}],"ecosystem":"pypi","meta_description":null,"install_score":85,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.84,"mem_mb":30.2,"disk_size":"68.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.84,"mem_mb":30.2,"disk_size":"107.6M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.68,"mem_mb":27.4,"disk_size":"55.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.35,"mem_mb":30.2,"disk_size":"68M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.39,"mem_mb":30.2,"disk_size":"107M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.23,"mem_mb":27.4,"disk_size":"55M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.47,"mem_mb":32.2,"disk_size":"74.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.48,"mem_mb":32.2,"disk_size":"118.5M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.29,"mem_mb":29.2,"disk_size":"60.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.04,"mem_mb":32.2,"disk_size":"74M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.1,"mem_mb":32.2,"disk_size":"118M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.93,"mem_mb":29.2,"disk_size":"60M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.24,"mem_mb":31.9,"disk_size":"65.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.23,"mem_mb":32,"disk_size":"108.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.08,"mem_mb":29.1,"disk_size":"51.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.23,"mem_mb":31.9,"disk_size":"65M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.38,"mem_mb":32,"disk_size":"108M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.06,"mem_mb":29.1,"disk_size":"51M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.19,"mem_mb":32.5,"disk_size":"65.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.15,"mem_mb":32.5,"disk_size":"107.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.04,"mem_mb":29.6,"disk_size":"51.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"cli","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.23,"mem_mb":32.5,"disk_size":"65M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.22,"mem_mb":32.5,"disk_size":"107M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.05,"mem_mb":29.6,"disk_size":"51M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"cli","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"cli","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}