{"slug": "mcp-python-sdk-v2-migrate-fastmcp-to-mcpserver-now", "title": "MCP Python SDK v2: Migrate FastMCP to MCPServer Now", "summary": "The MCP Python SDK v2, released stable on July 27, removes the FastMCP class, renaming it to MCPServer, and introduces breaking changes including snake_case field names and context injection. The official migration guide from the Model Context Protocol team details the changes, and most migrations take five minutes. Teams unable to migrate immediately can pin to mcp>=1.28.1,<2, as IBM's mcp-context-forge team did, while v1.x continues to receive critical fixes.", "body_md": "MCP Python SDK v2 shipped stable on July 27. If you have a Python MCP server — including one built last week following a tutorial — you have breaking changes waiting. `FastMCP`\n\nis gone, import paths moved, and every field flipped to snake_case. The good news: most migrations take five minutes. Here’s exactly what to change.\n\n## The Rename That Breaks Everything First\n\nThe most immediate change is the class rename: `FastMCP`\n\nis now `MCPServer`\n\n. There is no deprecation shim. There is no backward-compatible alias. The old import path simply does not exist in v2. The [official migration guide](https://py.sdk.modelcontextprotocol.io/migration/) covers the full list — but the rename is the one that breaks your server at startup, before anything else runs.\n\n``` python\n# Before — MCP Python SDK v1\nfrom mcp.server.fastmcp import FastMCP\nmcp = FastMCP(\"my-server\")\npython\n# After — MCP Python SDK v2\nfrom mcp.server.mcpserver import MCPServer, Context\nmcp = MCPServer(\"my-server\")\n```\n\nEverything under `mcp.server.fastmcp.*`\n\nmoved to `mcp.server.mcpserver.*`\n\n. The `ctx.fastmcp`\n\nproperty is now `ctx.mcp_server`\n\n. One more detail worth catching: the default server name string changes from `\"FastMCP\"`\n\nto `\"mcp-server\"`\n\n— pass an explicit name if you rely on `serverInfo.name`\n\nin your client.\n\n## snake_case Is Now Everywhere\n\nAll Pydantic model fields switched from camelCase to snake_case for Python access. The JSON wire format is unchanged — but the Python attributes are not. This one hides well: your server may start fine and only fail at runtime when code reads a tool or resource field.\n\n`tool.inputSchema`\n\n→`tool.input_schema`\n\n`result.isError`\n\n→`result.is_error`\n\n`listing.nextCursor`\n\n→`listing.next_cursor`\n\n`content.mimeType`\n\n→`content.mime_type`\n\nIf you serialize models for wire format, pass `by_alias=True`\n\n: `tool.model_dump(by_alias=True, mode=\"json\")`\n\nstill produces the camelCase JSON that clients expect.\n\n## Context Injection Replaces get_context()\n\nHandler context is now injected as an explicit parameter. `mcp.get_context()`\n\nis removed. The fix is a one-line signature change — but it’s pervasive if your tools use progress reporting or logging:\n\n``` php\n# Before\n@mcp.tool()\nasync def search(query: str) -> str:\n    ctx = mcp.get_context()\n    await ctx.report_progress(0, 100)\n    return f\"Results for: {query}\"\nphp\n# After\n@mcp.tool()\nasync def search(query: str, ctx: Context) -> str:\n    await ctx.report_progress(0, 100)\n    return f\"Results for: {query}\"\n```\n\nThe `@mcp.tool()`\n\ndecorator stays. Only the context acquisition changes.\n\n## Transport Parameters Move to run()\n\nConstructor-level transport arguments no longer exist. Move them to the `run()`\n\ncall:\n\n```\n# Before\nmcp = FastMCP(\"Demo\", json_response=True, stateless_http=True)\nmcp.run(transport=\"streamable-http\")\n\n# After\nmcp = MCPServer(\"Demo\")\nmcp.run(transport=\"streamable-http\", json_response=True, stateless_http=True)\n```\n\n## Not Ready Yet? Pin Your Version\n\nIf your team cannot migrate immediately, pin before an unpinned install auto-upgrades:\n\n```\n# requirements.txt\nmcp>=1.28.1,<2\n```\n\nThis is exactly what [IBM’s mcp-context-forge team did](https://github.com/IBM/mcp-context-forge/issues/5839). SDK v1.x continues to receive critical bug fixes and security patches. The deprecated features — sampling, roots, logging — have a one-year grace period, and a v2 server falls back to legacy behavior for older clients. Pinning is not a cop-out; it’s responsible dependency management while your team plans the migration.\n\n## Why FastMCP Had to Go\n\nThe rename reflects a deeper protocol shift. The [MCP 2026-07-28 specification](https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28/) eliminates the `initialize`\n\nhandshake and session IDs entirely — any server instance can handle any request. Round-robin load balancers work without sticky sessions. Serverless deployments become straightforward. “FastMCP” made sense as a high-level layer on top of session-based MCP. Once sessions disappear from the protocol, *all* MCP servers are stateless by design — the name stops meaning anything, and `MCPServer`\n\nis simply what it is.\n\n## Migration Checklist\n\n- Update package:\n`pip install \"mcp>=2.0\"`\n\n- Replace all\n`FastMCP`\n\nimports →`MCPServer`\n\nfrom`mcp.server.mcpserver`\n\n- Update any\n`mcp.server.fastmcp.*`\n\nsubmodule paths - Replace\n`ctx = mcp.get_context()`\n\nwith`ctx: Context`\n\nparameter in handler signatures - Search codebase for\n`inputSchema`\n\n,`isError`\n\n,`nextCursor`\n\n,`mimeType`\n\n— rename each - Move constructor transport params to\n`run()`\n\n- If using HTTP transport directly: swap\n`httpx`\n\nfor`httpx2`\n\nIf you built a v1 server from our [MCP Server in Python guide](https://byteiota.com/build-mcp-server-python-tutorial/), the structure still holds — apply these changes on top. For anything beyond the mechanical renames, the [full v2 changelog](https://py.sdk.modelcontextprotocol.io/whats-new/) covers the low-level server API, union type adapter changes, and the new multi-round-trip request pattern.", "url": "https://wpnews.pro/news/mcp-python-sdk-v2-migrate-fastmcp-to-mcpserver-now", "canonical_source": "https://byteiota.com/mcp-python-sdk-v2-migrate-fastmcp-mcpserver/", "published_at": "2026-08-04 10:09:30+00:00", "updated_at": "2026-08-04 10:23:32.942539+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure"], "entities": ["MCP Python SDK", "FastMCP", "MCPServer", "Model Context Protocol", "IBM", "mcp-context-forge"], "alternates": {"html": "https://wpnews.pro/news/mcp-python-sdk-v2-migrate-fastmcp-to-mcpserver-now", "markdown": "https://wpnews.pro/news/mcp-python-sdk-v2-migrate-fastmcp-to-mcpserver-now.md", "text": "https://wpnews.pro/news/mcp-python-sdk-v2-migrate-fastmcp-to-mcpserver-now.txt", "jsonld": "https://wpnews.pro/news/mcp-python-sdk-v2-migrate-fastmcp-to-mcpserver-now.jsonld"}}