Skip to content
← Blog

Release

TurboMCP v4.0.0-alpha.1: A Ground-Up Rewrite, Now in Public Alpha

TurboMCP v4 is a from-scratch rewrite of the Rust MCP SDK: three protocol revisions from one handler, a typed client, tower middleware, and a smaller crate family. This is a prerelease, and APIs may change.

TurboMCP Engineering Team · · 9 min read

TurboMCP v4.0.0-alpha.1 is the first published release of v4, a ground-up rewrite of the TurboMCP SDK. It ships as the same turbomcp crate at a new major version. This is an alpha: a prerelease for community testing, and the API can still change before 4.0.0. The stable line remains 3.x; see our TurboMCP v3.6.0 release post at /blog/turbomcp-v3-6-0/.

v4 is now the main line of the repository. The 3.x line lives on the v3.x branch. v4 uses Rust edition 2024 and requires Rust 1.88 or newer.

Why a rewrite

The v3 workspace grew to a large family of crates, each with its own surface for transports, middleware and capabilities. v4 starts from a different premise, stated in the project README: both halves of the protocol (server and client), a macro-driven zero-boilerplate surface, and strict spec compliance as a feature. The goals that follow from that:

  • Capabilities should be derived from what you wrote, not declared separately, so they cannot drift from the implementation.
  • One handler should serve every protocol revision a deployment cares about, without per-version code.
  • Cross-cutting concerns should use an existing ecosystem (tower) rather than an SDK-specific middleware trait.
  • Compliance should be measured against the official conformance suite and other SDKs, not asserted.

What is architecturally different from v3

One macro defines a server

#[server] over an impl block, with #[tool], #[resource] (fixed or RFC 6570 templated URIs), #[prompt] and #[completion] methods, produces a fully wired server. JSON schemas are generated from signatures at compile time. Json<T> returns produce structuredContent plus a generated outputSchema, and Image / Audio returns produce media content blocks.

The advertised capabilities are derived from which markers are present. In v3 you worked with type-state capability builders; in v4 declaring a #[resource] is what advertises the resources capability.

use turbomcp::prelude::*;

#[derive(Clone)]
struct Hello;

#[server(name = "hello", version = "1.0.0")]
impl Hello {
    /// Say hello to someone.
    #[tool(description = "Say hello to someone")]
    async fn hello(&self, name: String) -> McpResult<String> {
        Ok(format!("Hello, {name}!"))
    }
}

#[tokio::main]
async fn main() -> Result<(), turbomcp::ProtocolError> {
    // Logs MUST go to stderr: stdout carries the MCP protocol framing.
    Hello.run_stdio().await
}

Three protocol revisions, one handler

The same server answers 2025-06-18, 2025-11-25, and a 2026-07-28 revision. Handlers speak version-neutral types (turbomcp::neutral). Each revision has its own wire types generated from that revision’s published schema, and the conversions between them destructure exhaustively, so a field added to one revision is a compile error until someone decides what the others do with it.

Fields a revision predates are dropped per session on the way out. For example, a 2025-06-18 session does not see Tasks, icons or URL-mode elicitation, and tasks/* answers -32601 there. You can pin the set of revisions a server accepts:

#[server(name = "hello", version = "1.0.0", protocols("2025-11-25", "2026-07-28"))]

One caveat specific to this release: alpha.1 speaks the 2026-07-28 revision as synced to the upstream 2026-07-28-RC tag, not the final frozen schema. A release candidate is not a freeze. We corrected this in alpha.2 (covered in our alpha.3 post, /blog/turbomcp-v4-0-0-alpha-3/). If you tested the 2026-07-28 wire on alpha.1, expect differences.

Transports

  • stdio, always linked.
  • Streamable HTTP on axum 0.8, with per-POST SSE upgrade, sessions and DELETE termination, Origin and Host DNS-rebinding guards, and trusted-proxy X-Forwarded-For handling.
  • WebSocket with the same production guards: Origin policy, bearer auth through the shared HttpAuthenticator seam, message-size caps, keepalive pings and idle-peer reaping.

The Transport trait documents a seven-invariant parity contract that every transport upholds.

A typed client

With feature = "client", v4 includes the other half of the protocol: handshake and version negotiation, the server-turn loop for elicitation and sampling, an HTTP transport, and a task-aware call_tool that drives resultType: "task" answers to completion.

Composition and per-caller visibility

Composite mounts several servers as one. In alpha.1, tools and prompts are namespaced {prefix}.{name} and resource URIs are untouched. with_visibility(...) decides per caller which components exist at all, by tag, declared scopes, or a closure. Hidden means unreachable: refused exactly as something that never existed.

Middleware is tower

The dispatcher is a tower::Service<JsonRpcMessage>, so cross-cutting concerns are ordinary Layers that see every method on every transport. v3’s McpMiddleware trait has no equivalent in v4.

Tasks, enterprise seams and a no_std foundation

  • Core Tasks on 2025-11-25 (ServerBuilder::with_tasks(), per-tool #[tool(task)]) and the Tasks extension (feature = "ext-tasks", SEP-2663) including in-execution input_required.
  • OAuth 2.1 resource-server auth (JWKS bearer validation, RFC 8707 audience binding, RFC 9728 metadata, per-tool #[tool(scopes(...))]) and a full OAuth 2.1 client flow behind feature = "client-oauth".
  • Identity-keyed rate limiting, OpenTelemetry tracing and metrics, pluggable SessionBackend and TaskBackend storage, session idle timeout and termination.
  • turbomcp-core, -codec and -protocol build no_std for wasm32-unknown-unknown, checked on every CI run.

What we verified for alpha.1

Per the alpha.1 changelog: the official @modelcontextprotocol/conformance suite reported 47 checks, 43 passing, 0 failing, 4 informational. Cross-SDK interop with the official Rust SDK (rmcp) runs in both directions. Line coverage was about 90% against an 85% CI floor. Every pair of facade features is compiled in CI, on Linux, macOS and Windows, with cargo-deny supply-chain checks on each push and cargo-fuzz targets for each untrusted-input decoder.

These are the alpha.1 figures. The conformance coverage grew substantially in later alphas; see /blog/turbomcp-v4-0-0-alpha-5/ for the current state.

Breaking changes from v3

The macro surface is intentionally source-compatible with v3 for the common case, and simple servers port with little more than a version bump. The deliberate differences, documented in crates/turbomcp/MIGRATION.md:

Area v3 v4
Argument errors McpError::invalid_request McpError::invalid_params
Request context One shared RequestContext A distinct context per RPC (CallToolContext, ReadResourceContext, …)
Bidirectional features On the shared context ctx.client on the three contexts that can carry them
Capabilities Type-state builders Derived from the markers you write
Middleware McpMiddleware hooks tower::Layer over the dispatcher
Draft version string DRAFT-2026-v1 placeholder The real 2026-07-28 string
TCP and Unix transports Supported Not ported (dropped as non-spec); use stdio locally, HTTP or WebSocket over a network
gRPC and DPoP Present Not ported

Server composition and visibility, which were absent early in the v4 work, are back as Composite and with_visibility.

v4 also does not serve the 2024-11-05 and 2025-03-26 protocol revisions. If you need peers on those, the project points to the official Rust SDK, rmcp.

Who should try it

Try v4 if you:

  • are starting a new server or client and can tolerate API changes between prereleases,
  • need the 2026-07-28 stateless revision alongside the stateful ones,
  • want a client and server from one SDK, or tower-based middleware,
  • can report issues. The project explicitly asks for bug reports and ergonomics feedback.

Who should stay on v3

Stay on 3.x if you:

  • run production workloads that cannot absorb breaking changes between prereleases (VERSIONING.md says a prerelease may break API against the prerelease before it),
  • depend on the TCP or Unix transports, gRPC, or DPoP,
  • rely on v3’s McpMiddleware hooks without capacity to port them to tower layers.

The v3 line is maintained on the v3.x branch. See /blog/turbomcp-v3-6-0/ for its latest release.

Getting started

[dependencies]
turbomcp = "4.0.0-alpha.1"
tokio = { version = "1", features = ["full"] }

Cargo does not select prereleases from a range like "4", so pin the alpha explicitly. Optional capabilities are Cargo features: http, websocket, auth, client, client-oauth, telemetry, and ext-tasks. See the TurboMCP product page for the current overview, or contact us if you want to talk through a migration.

  • TurboMCP
  • v4
  • Alpha
  • Rust
  • MCP
  • Rewrite
  • Release

Keep reading

Want this running in your business?

We build and deploy production AI for enterprises. Let's talk about what you're working on.