Release
TurboMCP v3.0.0: A Modular, no_std-Ready Rewrite for Native and WASM MCP Servers
TurboMCP 3.0.0 rebuilds the SDK around a unified McpHandler trait, per-transport crates, a no_std core, and WASM targets. What changed since 2.3.7, what breaks, and how to migrate.
TurboMCP Engineering Team · · 11 min read
TurboMCP 3.0.0 shipped on 2026-03-03 after five betas (3.0.0-beta.1 on 2026-01-18 through beta.5 on 2026-02-23). It is a major rewrite: the changelog describes beta.1 as a complete architectural rewrite with a net reduction of more than 47,000 lines of code. The goal is a smaller SDK in which the same server code can run natively and on edge runtimes such as Cloudflare Workers.
For someone running MCP in production, the practical consequences are these. Error types are unified into one McpError. Transports are separate crates behind the same feature flags you already use. Several 2.x feature flags are gone. And a lot of security work from the beta audits is in the release. If you are on 2.3.x, expect a compile-fix pass, not a redesign of your tools.
Why a 3.0
The 2.x line had grown layered error types (ServerError, turbomcp_protocol::Error, and a wrapper McpError), a monolithic transport crate, and handler plumbing that could not target WASM. Version 3 addresses each:
- One handler trait.
McpHandler(inturbomcp-core) is the unified interface for every deployment target. The#[server]macro generates the implementation, along withrun_stdio(),run_http(),run_tcp(), andrun_unix()style methods. - A
no_std + allocfoundation.turbomcp-types,turbomcp-core, andturbomcp-wirecan be used withoutstd, which is what makes WASM targets practical. - One source of truth for constants.
PROTOCOL_VERSION,SUPPORTED_VERSIONS,error_codes, andmethodslive inturbomcp-coreand are re-exported elsewhere. - Modular transports. Each transport is its own crate, and
turbomcp-transportremains as a re-export hub.
What a v3 server looks like
The macro syntax is familiar. Descriptions can come from the #[tool("...")] argument or from #[tool(description = "...")], and tool return types can be any serializable type or McpResult<T>. This is adapted from the calculator and stateful examples at the 3.0.0 tag:
use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::RwLock;
use turbomcp::prelude::*;
#[derive(Clone)]
struct CounterServer {
counters: Arc<RwLock<HashMap<String, i64>>>,
}
#[turbomcp::server(name = "counter", version = "1.0.0")]
impl CounterServer {
#[tool("Increment a counter by name")]
async fn increment(&self, name: String) -> McpResult<i64> {
let mut counters = self.counters.write().await;
let counter = counters.entry(name).or_insert(0);
*counter += 1;
Ok(*counter)
}
#[tool(description = "Add two numbers")]
async fn add(&self, a: i64, b: i64) -> i64 {
a + b
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Log to stderr: stdout is the MCP protocol channel
tracing_subscriber::fmt()
.with_writer(std::io::stderr)
.init();
let server = CounterServer {
counters: Arc::new(RwLock::new(HashMap::new())),
};
server.run_stdio().await?;
Ok(())
}
Note the Clone derive. McpHandler requires it, and shared state belongs behind an Arc.
Beta.4 also added tags and versions on components, which are useful for access control and progressive disclosure:
#[tool(description = "Delete all data", tags = ["admin", "dangerous"], version = "2.0")]
async fn delete_all(&self) -> McpResult<String> {
Ok("All data deleted (simulated)".into())
}
Highlights by beta
beta.1 (2026-01-18): the rewrite
- New proc-macro system with automatic JSON Schema generation from Rust types.
McpHandler, a richRequestContext(correlation IDs, headers, transport info), and aRouterinturbomcp-core.ServerBuilder, transport modules for stdio, tcp, and http, and automatic capability detection from registered handlers.- Error message sanitization: paths, IPs, and internal errors are filtered from client responses by default, and you can turn it off for development.
- Dependency refresh, including
reqwest0.12 to 0.13,tokio1.49,axum0.8.8, and OpenTelemetry 0.31. Becauseoauth25.0 depends onreqwest0.12, a newOAuth2HttpClientadapter inturbomcp-authbridges the two. - Removed from the 2.x tree: legacy macro modules, the old handler system, the elicitation module, and the multi-tenant configuration in
turbomcp-server.
beta.2 and beta.3 (2026-01-20, 2026-01-22): docs and WASM auth
Mostly documentation (why DPoP is ES256-only, WASM secret management) plus WASM JWT hardening: empty algorithm lists now fail closed, RSA keys are restricted to RS* algorithms and EC keys to ES*, JWKS URLs must be HTTPS (localhost exempt), and JwtConfig no longer implements Default. A WorkerError wrapper enables ? with Cloudflare Workers APIs.
beta.4 (2026-02-17): audit remediation and new crates
A security audit across all 25 crates, with fixes at every severity level. Notable items:
- Auth config secrets serialize as
[REDACTED]instead of plaintext. - STDIO message length is bounded,
SessionIdrejects IDs over 256 bytes, and TCP gets an optionalstrict_modefor malformed JSON. - SSRF protection blocks private networks, localhost, cloud metadata, link-local, and multicast ranges.
- CORS echoes the request
Originand addsVary: Origininstead of using a wildcard. - New crates:
turbomcp-openapi(OpenAPI 3.x to MCP; GET endpoints become resources, other methods become tools) andturbomcp-transport-streamable(Streamable HTTP types for MCP 2025-11-25,no_stdcapable). - WASM server architecture: Durable Objects (rate limiter, session, state, token stores), streamable transport, middleware, visibility control, and composite servers with namespacing.
turbomcp-wasm-macrosuses the same#[server],#[tool],#[resource],#[prompt]syntax as native. - CLI commands:
turbomcp new,build,dev,install(Claude Desktop and Cursor), anddeploy(Cloudflare Workers). StdioTransport::from_childandfrom_rawfor child processes and custom async streams, andJson<T>as a tool return type.
beta.5 (2026-02-23): DPoP and the WASM stack
Broader DPoP (RFC 9449) hardening across turbomcp-auth, turbomcp-dpop, and turbomcp-server, a WASM OAuth 2.1 provider with Web Crypto and PKCE, and a Tower rate-limiting middleware with auth metrics in turbomcp-auth. Macro output is stricter about MCP protocol adherence.
3.0.0 (2026-03-03)
The final release adds turbomcp-telemetry to the top-level crate behind a new telemetry feature (OpenTelemetry, Prometheus metrics, structured logging), included in the full and full-stack bundles, with TelemetryConfig, TelemetryConfigBuilder, and TelemetryGuard in the prelude. It also fixes the tcp_client and unix_client examples and cleans up workspace dependencies.
Breaking changes
The repository’s MIGRATION.md has the full guide. These are the changes most likely to touch your code.
1. Unified error types
ServerError, ServerResult, turbomcp_protocol::Error, and turbomcp_protocol::Result are replaced by McpError and McpResult<T>. The prelude re-exports both.
// v2.x
return Err(ServerError::Internal("failed".to_string()));
// v3.x
use turbomcp::prelude::*;
return Err(McpError::internal("failed"));
In auth validation, McpError::validation() became McpError::invalid_params(). JwtValidator::new() is now async because it performs RFC 8414 discovery.
2. Feature flags
The MCP 2025-11-25 draft flags from 2.3 (mcp-icons, mcp-url-elicitation, mcp-sampling-tools, mcp-enum-improvements, mcp-draft) are gone; those types are always available. The Tasks API now sits behind a single experimental-tasks flag. Several 2.x flags were removed outright:
| Removed in v3 | Replacement |
|---|---|
multi-tenancy, sessions, security, input-validation, rate-limiting |
Removed from the main crate |
context-injection, uri-templates, middleware |
Always available |
network, server-only |
["stdio", "tcp"], ["tcp", "unix"] |
dpop-redis, dpop-hsm-pkcs11, dpop-hsm-yubico, dpop-test-utils |
Use turbomcp-dpop directly with its own features |
If you rely on the 2.3 multi-tenancy toolkit, plan for this explicitly: the feature is not carried forward into the main turbomcp crate.
New bundles are minimal (stdio only), full (all transports plus telemetry), full-stack (full plus the client library), and all-transports. A channel in-process transport and a telemetry feature are new.
3. Handler context
Context from 2.x becomes RequestContext, which the macros now detect by type rather than by parameter name:
#[resource("config://app", tags = ["readonly", "config"])]
async fn get_config(&self, _uri: String, _ctx: &RequestContext) -> McpResult<String> {
Ok(r#"{"theme": "dark"}"#.into())
}
4. Claims and auth
turbomcp_server::Claims is replaced by StandardClaims in turbomcp_core::auth and the richer AuthContext in turbomcp-auth.
5. Builder deprecations
On the WASM builder, .tool(), .resource(), and .prompt() replace .with_tool() and friends (the old names are deprecated).
Upgrade steps
- Make sure you are on Rust 1.89.0 or later.
- Move to the latest 2.3.x first and fix any deprecation warnings.
- Bump the dependency:
[dependencies]
turbomcp = "3.0"
tokio = { version = "1", features = ["full"] }
- Replace error imports with
use turbomcp::prelude::*;and swapServerErrorforMcpError. - Remove the retired feature flags from
Cargo.toml(the table above). - Rename handler context parameters to
&RequestContextwhere needed. - If you use JWT validation, make the
JwtValidator::new()call site async. - Run your integration tests against each transport you deploy.
After 3.0.0
3.0.x patch releases land quickly after this release, including a protocol policy change in 3.0.3 and the multi-version protocol work in 3.0.8. They are covered in TurboMCP v3.1.0. If you are coming from 2.x, read the 2.3.0 post for what you are leaving behind.
For product information, see the TurboMCP page. For help planning a migration, contact us.
- TurboMCP
- Rust
- MCP
- v3
- WASM
- no_std
- Migration
- Security