[Feature] Full support for MCP Python SDK v2 (mcp 2.0.0 / 2026-07-28 spec)

[phpmac]

Summary

Request for full support of the MCP Python SDK v2 (mcp==2.0.0, stable since 2026-07-28, implementing the 2026-07-28 protocol revision).

This is distinct from #321 and #322 — those report the Server.__init__() positional-arg crash and suggest a one-line keyword-arg fix. That fix only prevents the crash; it does not make fastapi-mcp actually work against the v2 SDK. This issue tracks the broader ask: a version of fastapi-mcp that is built for and tested against mcp>=2.0.

Why this matters

mcp==2.0.0 is a major rework. From the official release notes:

This is v2 of the MCP Python SDK, the current stable release line. It is a major rework of the SDK, both to support the 2026-07-28 MCP specification and to fix long-standing architectural issues.

Key breaking changes that affect fastapi-mcp:

1. HTTP stack migration: httpx -> httpx2. v2 depends on httpx2>=2.5.0 and rebuilds the Streamable HTTP transport on top of it. Any code in fastapi-mcp that touches the transport layer, client construction, or ASGI plumbing needs to be re-evaluated against the new stack.
2. New top-level API surface. v2 introduces mcp.server.MCPServer / mcp.Client with a much simpler API (e.g. @mcp.tool() decorator, type hints as schema). The lowlevel Server class signature changed (keyword-only args after name), which is the crash already tracked in [BUG] Incompatible with mcp 2.0 — Server.__init__() positional arg crash #321.
3. 2026-07-28 protocol revision. Stateless single-exchange POST (no initialize handshake, no session ID), removal of WebSocket transport. fastapi-mcp currently assumes the 2025-era session lifecycle.

A keyword-arg patch keeps fastapi-mcp compiling but it still runs on the legacy transport and API — it is not real v2 support.

Ecosystem impact (we are blocked on both sides)

We maintain a project (ARL — Asset Reconnaissance Lighthouse) that uses MCP in both directions and shares a single mcp package install:

Component	Package	Current constraint
MCP server (expose our API)	fastapi-mcp==0.4.0	mcp>=1.12.0 (no upper bound; breaks at >=1.28 with "Task group is not initialized")
MCP client (AI agent connects out)	openai-agents	pins mcp>=1.19,<2.0, uses httpx-based transport

Because openai-agents also pins mcp<2.0, both upstream packages must release v2-compatible versions before we can migrate. We are filing this issue so fastapi-mcp has a tracked v2 milestone alongside whatever openai-agents plans.

What we are asking for

• A fastapi-mcp release (0.5.x or 1.0) that officially targets mcp>=2.0 and is tested against the v2 SDK + httpx2.
• A temporary mcp>=1.12,<2 upper bound on the current 0.4.x line so downstream lockfiles do not accidentally resolve mcp==2.0.0 and crash at startup (the crash in [BUG] Incompatible with mcp 2.0 — Server.__init__() positional arg crash #321).
• Any roadmap / timeline you can share for v2 support, so we can plan our migration.

Environment

• fastapi-mcp==0.4.0
• mcp==2.0.0 (stable, 2026-07-28)
• Python 3.13

Thank you for the project — happy to help test a v2 branch if one exists.

[jayagentworks]

Hi, I'd like to work on this issue.

I've reproduced the incompatibility locally and have done an initial investigation before making any code changes.

Reproduction environment

Python 3.12
fastapi-mcp==0.4.0 from the current source tree
mcp==2.2.0

Using a minimal FastAPI application and:

from fastapi_mcp import FastApiMCP

mcp = FastApiMCP(app)
mcp.mount()

startup consistently fails at:

Server(self.name, self.description)

with:

TypeError: Server.init() takes 2 positional arguments but 3 were given

I also verified that this is not only the constructor issue described in #321/#322.

In MCP 2.2.0, the low-level Server constructor uses keyword-only arguments after name, and the old handler registration APIs are also gone:

hasattr(server, "list_tools") -> False
hasattr(server, "call_tool") -> False
hasattr(server, "run") -> True

The v2 Server API instead exposes callbacks such as on_list_tools and on_call_tool, and the handler contracts have changed as well. For example, tool calls now receive a request context and CallToolRequestParams, and are expected to return a CallToolResult.

So I agree that fixing only:

Server(self.name, description=self.description)

would not provide real MCP v2 support.

My current implementation plan is:

Migrate the low-level server construction and tools/list / tools/call handlers to the MCP v2 callback API.
Update handler signatures and return types to ListToolsResult / CallToolResult.
Migrate HTTP request context handling from the old server-level context access to the v2 callback context, while preserving the existing header forwarding behavior.
Keep the existing OpenAPI-to-Tool conversion and API execution path where possible, rather than rewriting that layer.
Validate the modern Streamable HTTP flow against MCP v2, including tool discovery and tool calls without relying on the legacy initialize/session lifecycle.
Preserve and regression-test legacy HTTP/SSE behavior where the MCP v2 SDK still supports it.
Update the MCP dependency range and add/adjust tests for the v2 contracts and transport behavior.

I'm intentionally avoiding a broad rewrite to the high-level MCPServer API unless the low-level v2 API proves insufficient, since fastapi-mcp already has a dynamic tool list and centralized execution path that map naturally to the low-level callbacks.

I haven't modified the implementation yet. I've first prepared the migration plan and reproduction so the scope is clear.

If this direction sounds good, I'd be happy to take #323 and start working on the implementation.