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
DELETEtermination, Origin and Host DNS-rebinding guards, and trusted-proxyX-Forwarded-Forhandling. - WebSocket with the same production guards: Origin policy, bearer auth through the shared
HttpAuthenticatorseam, 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-executioninput_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 behindfeature = "client-oauth". - Identity-keyed rate limiting, OpenTelemetry tracing and metrics, pluggable
SessionBackendandTaskBackendstorage, session idle timeout and termination. turbomcp-core,-codecand-protocolbuildno_stdforwasm32-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-28stateless 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
McpMiddlewarehooks without capacity to port them totowerlayers.
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