Release
TurboMCP v4.0.0-alpha.5: Where v4 Stands Today
Alphas 4 and 5 harden security and lifecycle behavior after the v4 audit. This post also covers unreleased work on main, the remaining gaps to 4.0.0 stable, and how v3 and v4 are supported. v4 is alpha and APIs may change.
TurboMCP Engineering Team · · 12 min read
TurboMCP 4.0.0-alpha.5 was released on 2026-09-13. It is the latest v4 release, and v4 is still an alpha: a prerelease for community testing, and public APIs may change before 4.0.0. This post covers alphas 4 and 5, summarizes the substantial work that has landed on main since, and states plainly what is left before a stable release and how v3 and v4 are supported.
Earlier posts: the alpha.1 announcement and alphas 2 and 3.
Where v4 stands
| Question | Answer |
|---|---|
| Latest release | 4.0.0-alpha.5 (2026-09-13) |
| Channel | Prerelease. A prerelease may break API against the prerelease before it (VERSIONING.md) |
| Stable line | 3.x, maintained on branch v3.x |
| Protocol revisions served | 2025-06-18, 2025-11-25, 2026-07-28, all dated and frozen |
| Not served, and not planned | 2024-11-05, 2025-03-26 |
| Transports | stdio, Streamable HTTP, WebSocket |
| Rust | Edition 2024, MSRV 1.88 |
| Compatibility promise | Starts at 4.0.0 |
The README describes v4 as a from-scratch rewrite that interoperates with the official Rust, TypeScript, Python and Go SDKs in both directions.
alpha.4: audit remediation (2026-09-10)
alpha.4 followed an audit of v4 and is described in the changelog as security, correctness and lifecycle hardening. It changes public contracts, so read the deployment and migration guide in the repository before upgrading. Highlights:
Lookup, visibility and schema enforcement
- Catalog lookup follows pagination, rejects lookup failures, enforces visibility, and routes flat-mounted providers beyond page one.
- Tool calls validate advertised input schemas and structured output schemas, including for tasks.
- Header mirror validation uses current definitions, and client recovery refreshes the whole catalog instead of reusing stale cached metadata.
Lifecycle and overload behavior
- Requests arriving during transport teardown fail closed immediately instead of entering a queue whose pending calls were already drained.
- Saturated servers continue handling control traffic. Client deadlines cover admission and sending, and abandoned requests, callbacks, HTTP pumps, stalled writes and shutdown have bounded ownership and cleanup.
- HTTP overload, body and timeout limits now apply by default.
- Legacy POST SSE responses resume through
GETafter graceful closure, with per-requestLast-Event-ID, retry timing and cancellation, and no repeated POST.
Auth
- Public
OAuthSessionandAuthorizationHandlerclient integration covers coordinated authorization, token refresh, scope step-up and issuer discovery. - JWT validation enforces
nbf. Auth networking has deadlines and body limits, disables redirects and proxies by default, and coalesces JWKS refreshes with failure cooldowns. - Sessions and task state bind to the issuer and subject that created them. MRTR continuations also bind arguments and method.
- Concurrent callers share rejected OAuth refreshes instead of retrying the same failed token.
- Separate issuer validators support deployments with independent signing keys, and
NetworkPolicyoffers opt-in public-only egress with DNS address validation. - Trusted proxy chains stop at a malformed boundary instead of trusting an address farther left.
Contracts that changed
- Custom providers must resolve callable components through authoritative lookup.
- Custom session backends must persist ownership, and session terminators must check it.
- Subscription extensions now receive the authenticated request context.
- Applications supplying their own auth HTTP clients own their redirect and DNS policy guarantees.
alpha.4 also removed unsupported performance claims from the documentation and fixed benchmark fixtures so they assert successful results before timing. The changelog reports that the candidate passed 720 workspace tests, strict Clippy, Rust 1.88, foundation WASM checks, 43 feature combinations and four fuzz smoke campaigns.
alpha.5: shutdown correctness and SSRF policy (2026-09-13)
alpha.5 is deliberately small: one correctness fix, one policy addition, a dependency refresh, and two breaking changes.
Graceful shutdown no longer discards a mid-write reply
The serve driver raced the shutdown token against the write of a frame it had already taken out of the outbound channel. Nothing else held a copy, so the reply was lost. Worse, the abandoned write was treated as a possibly partial frame, which skipped the drain and aborted every other in-flight handler. The write is now bounded by drain_timeout, the same budget the drain gets. The changelog notes that the busier the server, the likelier this was. As part of the fix, every tokio::select! in the workspace was audited for the same shape (a branch holding a value already taken from its channel); the other 21 sites were clean.
NetworkPolicy::with_allowed_ranges
Under public-only egress, a deployment that accepts untrusted endpoint URLs but also runs its own authorization server on an internal range previously had to choose between SSRF exposure and not working. with_allowed_ranges names CIDR ranges that stay reachable. The URL check and the DNS resolver share one predicate, so a literal address and the same address reached by name are judged identically, and an IPv4-mapped IPv6 spelling is read as the address it maps to.
Breaking changes in alpha.5
tokio-tungstenitemoved from 0.29 to 0.30. ItsWebSocketStreamappears inWebSocketTransport::new, so this is breaking for anyone constructing that transport from their own stream. The changelog notescargo-semver-checksdoes not flag public-dependency major bumps, which is why it is listed by hand.NetworkPolicyis now#[non_exhaustive]. Construct it withdefault()orpublic_only()and adjust withwith_timeout,with_max_response_bytes,with_public_only,with_loopback_httpandwith_allowed_ranges. Struct-literal construction from outside the crate no longer compiles; reading fields is unchanged.
use turbomcp_auth::NetworkPolicy;
let policy = NetworkPolicy::public_only()
.with_timeout(std::time::Duration::from_secs(10));
with_allowed_ranges takes impl IntoIterator<Item = ipnet::IpNet>. This snippet was written against the alpha.5 source but not compiled for this post.
Dependency updates in alpha.5 include jsonschema 0.46 to 0.49, base64 0.22 to 0.23, and reqwest 0.13.5. Thirty-eight unused [workspace.dependencies] entries were dropped, which left the build graph unchanged.
What has landed on main since alpha.5
The following are in the [Unreleased] section of the changelog. They are on main and are not part of the alpha.5 release, so they may change before they ship.
Gateway and CLI
turbomcp-proxy, an embeddable gateway. ARemoteServerconnects to an upstream MCP server (a command over stdio, or a Streamable HTTP or WebSocket endpoint) and serves it as if it were local, bridging transports and revisions. It mounts in aCompositebeside local tools, under the composite’s authentication and visibility. It replaces v3’s frame-level proxy crate.- The
turbomcpcommand (turbomcp-cli, rebuilt for v4).turbomcp proxy --config servers.jsonserves the servers in anmcpServersconfiguration as one MCP server over stdio or Streamable HTTP, and can require OAuth 2.1 bearer tokens over HTTP. Commandstools,resources,prompts,call,read,promptandprobework against a URL, a stdio command, or a configured server. v3’s scaffolding commands (new,build,deploy,install,dev) are not carried over. - Prebuilt binaries on every release for macOS, Linux and Windows, with checksums and build-provenance attestations.
- Gateway upstream policy and credentials: safe environment inheritance for stdio upstreams,
NetworkPolicyfor HTTP and WebSocket upstreams, OAuth client credentials, RFC 8693 token exchange, per-caller connection keying, and forwarding of elicitation, sampling and roots requests to the caller whose call caused them.
One discrepancy to be aware of: the repository’s ROADMAP.md still lists “a proxy and CLI” under Planned and says no v4 proxy or CLI package is currently shipped, because it counts only released packages. The README and changelog describe the code that exists on main. Treat the gateway as unreleased and as needing the remaining gates below before any support claim.
Protocol and server features
- Typed
Interceptors viaServerBuilder::intercept(...), which run every operation over the neutral context so one rule holds on every revision. - Extensions on every revision (SEP-2133), and the client half of an extension via
ClientBuilder::with_client_extension. - Per-call client input handlers (
CallOptions::with_elicitation,with_sampling,with_roots), resumable client tasks (Client::call_tool_detached,Client::resume_task), and#[tool(task = "required")]. - Per-tool step-up authorization: a tool lacking the required scopes answers over HTTP with
403and aWWW-Authenticateinsufficient_scopechallenge, instead of a200tool error no client could act on. - A cross-replica notification bus, resumable response streams with an event store, server-initiated SSE polling, an HTTP health-check route, and a replica deployment guide.
- RFC 6570
UriTemplateparsing and matching for every operator. - An in-memory transport and test harness (
turbomcp::memory::pair(),turbomcp::testing::connect). - OTLP over HTTP/protobuf, session duration metrics, and client-side telemetry.
- Opaque access token validation by RFC 7662 introspection, Enterprise-Managed Authorization (SEP-990) on the client, and
MachineAuthorizationfor flows with no user in the loop.
Security fixes on main
- OAuth secrets are wiped from memory on drop.
- MRTR
requestStateis sealed with XChaCha20-Poly1305 instead of only signed, with key rotation viaServerBuilder::with_state_keys. - Telemetry no longer records a reversible hash of the caller’s subject. The previous redaction was an unkeyed 64-bit FNV hash; subjects are now an HMAC-SHA256 under a
RedactionKey. - An anonymous
initializeflood can no longer evict live sessions: a full session table now refuses new sessions with503andRetry-After. - Under a visibility policy,
resources/readof a URI that no listed resource or template matches is refused.
Breaking changes on main
The Unreleased section lists many breaking changes against alpha.5. Notable ones: a Composite joins prefix and name with __ (weather__forecast) instead of ., because the Anthropic and OpenAI tool APIs accept only [a-zA-Z0-9_-]{1,64}; HttpConfig::enable_cors is gone in favor of the Origin policy; the task store, task-input seam and session backend traits changed shape; telemetry follows the OpenTelemetry MCP semantic conventions with new span names; and the service seam is now Service<McpRequest>. If you build on alpha.5, expect to touch these when the next alpha lands.
What remains before 4.0.0
ROADMAP.md deliberately gives no dates (“a date I can’t keep is worse than none”). Its “Next” section says:
- Audit remediation and stable API review. Implementation and verification are tracked in
docs/V4-AUDIT-REMEDIATION.md. Client authentication conformance now uses the public OAuth coordinator, and both failure baselines are empty. - 4.0.0 stable requires the security and lifecycle regressions to stay green, reproducible performance measurements, public API review, and deployment feedback. The roadmap states that passing conformance alone is insufficient release evidence.
- Deployment documentation. See
docs/DEPLOYMENT.md.
Planned work:
- A proxy and CLI with explicit contracts for remote authentication, notification routing, cancellation, pagination and upstream lifecycle before support can be claimed.
- The Apps extension (SEP-1865), currently a skeleton.
- Fewer crates. Package boundaries must be settled before stable, and removing or moving a public subcrate API is a breaking change even if the
turbomcpfacade stays unchanged.
Explicitly not planned: 2024-11-05 and 2025-03-26 (use rmcp), DPoP (absent from the MCP specification), legacy SSE Last-Event-ID replay on the server for 2026-07-28, and an in-tree distributed rate limiter or session store.
Verification, stated carefully
The README reports, for the alpha.5 line: the official conformance suite as a server scores 236 checks with 231 passing, 0 failing and 5 informational; as a client, 488 distinct successful scenario and check pairs with zero failures, skips or warnings, using hash-pinned fixture corrections (the unmodified upstream mode remains available with its original fixture limitations). Interop runs against rmcp 3.2 and, over Streamable HTTP, the official TypeScript, Python and Go SDKs in both directions.
The README is explicit that conformance and interoperability are compatibility evidence and do not establish performance superiority over any other SDK. We make no such claim here. CI also includes cargo-fuzz targets for untrusted-input decoders and cargo-deny checks.
Support position: v3 and v4
| Line | Branch | Status per VERSIONING.md |
|---|---|---|
4.x |
main |
Prerelease (4.0.0-alpha.x), active development. Compatibility promise starts at 4.0.0 |
3.x |
v3.x |
Stable. Maintained for bug fixes and low-risk additions |
3.x will receive security fixes for at least six months after 4.0.0 is released. New features land on 4.x. The latest v3 release is 3.6.0; see the 3.6.0 release notes.
Our recommendation, which follows from the above:
- Production today: stay on 3.x. v4 has no stable release, and each alpha may break API against the one before.
- New work that can tolerate churn, or that needs the
2026-07-28revision, a typed client,towermiddleware or composition: try v4 and report what is unergonomic. Pin the exact alpha inCargo.toml. - Needs TCP, Unix socket, gRPC or DPoP support, or the
2024-11-05and2025-03-26revisions: v4 does not serve these. Stay on 3.x or evaluatermcpfor the older revisions.
Trying it
[dependencies]
turbomcp = { version = "4.0.0-alpha.5", features = ["http"] }
tokio = { version = "1", features = ["full"] }
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
}
To serve over Streamable HTTP, the repository’s dual_transport example uses the http feature:
Calc.into_server()
.serve(Http::bind(addr).config(HttpConfig::new()))
.await?;
Found something broken or unergonomic? The project asks for issues on GitHub. For the product overview see TurboMCP, and for help evaluating or migrating, contact us.
- TurboMCP
- v4
- Alpha
- Rust
- MCP
- Security
- Roadmap
- Release