mcp-use v2: A Deep Dive into Stateless MCP Servers

Median operations per second just jumped from 8,615 to 10,982, and cold launch times were slashed by more than half (down to 68.1 ms). These aren't just marginal gains; they are the result of a complete ground-up rewrite of mcp-use v2 to align with the stateless 2026-07-28 MCP specification. For anyone building LLM agents or server-side connectors, moving to a stateless architecture is a massive win for scalability and deployment.

The Shift to Stateless MCP

The core change in the spec is the elimination of sessions. We no longer have to deal with the initialize/initialized handshake or the Mcp-Session-Id header. Now, every single request is self-contained, carrying its own protocol version, client identity, and capabilities within the _meta field.

Beyond the session removal, there are several technical shifts that change how we handle AI workflows:

• Multi Round-Trip Requests: Server-initiated calls are out. Instead, the server returns resultType: "input_required" with a requestState. The client then retries the call with inputResponses. This means mid-call user confirmations no longer require a persistent, live connection.
• Header-Based Routing: Mcp-Method and Mcp-Name are now mandatory HTTP headers. This is huge for infrastructure, as it allows WAFs, gateways, and rate limiters to route traffic without having to parse the JSON body.
• Auth and Deprecations: DCR is being phased out in favor of CIMD. Additionally, roots, sampling, and logging are entering a 12-month deprecation window, and legacy HTTP+SSE is on a one-year offramp.

Building MCP Apps with mcp-use

While the framework supports general MCP servers, the real power lies in MCP apps for ChatGPT plugins and Claude connectors. By using the ext-apps extension, tools can now return UIs that render directly within the chat interface.

From a developer experience perspective, mcp-use provides a few critical features for a professional AI workflow:

• Schema Validation: It supports Standard Schema validators, meaning you can use Zod, ArkType, or Valibot for tool and prompt I/O.
• Edge Deployment: Since the HTTP layer is powered by Hono, you can mount the server inside existing apps for edge deployments.
• Next.js Integration: For those struggling with the unmaintained mcp-handler, mcp-use offers a drop-in replacement. You simply wrap next.config.ts in withMcpUse and export the handlers from a catch-all route.
• OAuth Ready: Native integrations for Clerk, Auth0, Supabase, Keycloak, WorkOS, and Better Auth.

Debugging and Deployment

The toolkit includes a built-in MCP inspector accessible via mcp-use dev at /mcp/inspector with hot-reload support. For those working with coding agents, the CLI has a headless feature that allows agents to actually "see" what they are building. By running:

mcp-use client <name> screenshot --tool <tool>

The framework renders the View headlessly through Chrome. This allows an agent to call a tool, detect a failure, and then take a screenshot of the generated UI to diagnose the visual layout—essentially giving the LLM a feedback loop for UI development.

The transition to v2 does involve some breaking changes, but the reality is that about 90% of servers built with v2 remain compatible across both versions of the spec.