Skip to content
← Blog

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 (in turbomcp-core) is the unified interface for every deployment target. The #[server] macro generates the implementation, along with run_stdio(), run_http(), run_tcp(), and run_unix() style methods.
  • A no_std + alloc foundation. turbomcp-types, turbomcp-core, and turbomcp-wire can be used without std, which is what makes WASM targets practical.
  • One source of truth for constants. PROTOCOL_VERSION, SUPPORTED_VERSIONS, error_codes, and methods live in turbomcp-core and are re-exported elsewhere.
  • Modular transports. Each transport is its own crate, and turbomcp-transport remains 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 rich RequestContext (correlation IDs, headers, transport info), and a Router in turbomcp-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 reqwest 0.12 to 0.13, tokio 1.49, axum 0.8.8, and OpenTelemetry 0.31. Because oauth2 5.0 depends on reqwest 0.12, a new OAuth2HttpClient adapter in turbomcp-auth bridges 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, SessionId rejects IDs over 256 bytes, and TCP gets an optional strict_mode for malformed JSON.
  • SSRF protection blocks private networks, localhost, cloud metadata, link-local, and multicast ranges.
  • CORS echoes the request Origin and adds Vary: Origin instead of using a wildcard.
  • New crates: turbomcp-openapi (OpenAPI 3.x to MCP; GET endpoints become resources, other methods become tools) and turbomcp-transport-streamable (Streamable HTTP types for MCP 2025-11-25, no_std capable).
  • WASM server architecture: Durable Objects (rate limiter, session, state, token stores), streamable transport, middleware, visibility control, and composite servers with namespacing. turbomcp-wasm-macros uses the same #[server], #[tool], #[resource], #[prompt] syntax as native.
  • CLI commands: turbomcp new, build, dev, install (Claude Desktop and Cursor), and deploy (Cloudflare Workers).
  • StdioTransport::from_child and from_raw for child processes and custom async streams, and Json<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

  1. Make sure you are on Rust 1.89.0 or later.
  2. Move to the latest 2.3.x first and fix any deprecation warnings.
  3. Bump the dependency:
[dependencies]
turbomcp = "3.0"
tokio = { version = "1", features = ["full"] }
  1. Replace error imports with use turbomcp::prelude::*; and swap ServerError for McpError.
  2. Remove the retired feature flags from Cargo.toml (the table above).
  3. Rename handler context parameters to &RequestContext where needed.
  4. If you use JWT validation, make the JwtValidator::new() call site async.
  5. 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

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.