Skip to content
← Blog

Release

TurboMCP v2.3.0: MCP 2025-11-25 Support, Multi-Tenancy, and the 2.3.x Hardening Line

TurboMCP 2.3.0 adds the final MCP 2025-11-25 specification (Tasks, URL elicitation, sampling tools), a multi-tenant SaaS toolkit, and an OAuth 2.1 dependency upgrade. 2.3.1 to 2.3.7 follow with Inspector, Claude Code, WebSocket, and TLS fixes.

TurboMCP Engineering Team · · 9 min read

TurboMCP 2.3.0, released on 2025-12-02, adds support for the final MCP 2025-11-25 specification and a multi-tenancy toolkit for servers that front more than one customer. The seven patch releases that followed (2.3.1 on 2025-12-09 through 2.3.7 on 2026-01-05) are mostly compatibility and hardening work that you will want if you run HTTP, WebSocket, or TLS-terminating deployments.

If you only read one thing: the new specification features are opt-in behind feature flags, so upgrading from 2.2.x does not change wire behavior unless you ask for it. The two places that can break your build are the elicitation API and the oauth2 5.0 upgrade, both covered below.

What changed in 2.3.0

MCP 2025-11-25 specification support

The following additions live in turbomcp-protocol and are gated by feature flags (mcp-draft enables all of them, individual flags exist for granular control):

Capability Spec reference What you get
Tasks API SEP-1686 Durable state machines for long-running operations, polling and deferred result retrieval
URL-mode elicitation SEP-1036 Out-of-band, URL-based interactions for sensitive data
Tool calling in sampling SEP-1577 tools and toolChoice parameters in sampling requests
Icon metadata SEP-973 Icons for tools, resources, resource templates, and prompts
Enum improvements SEP-1330 oneOf/anyOf titled enums, multi-select arrays, default values
Tool execution settings n/a execution.taskSupport field (forbidden, optional, required)

On the server side this ships with task storage and task handlers. The feature flags on the turbomcp crate are mcp-draft, mcp-tasks, mcp-url-elicitation, mcp-sampling-tools, and mcp-icons.

Authorization features

turbomcp-auth gains four opt-in modules, each behind its own flag:

  • SSRF protection (mcp-ssrf): secure HTTP fetching with redirect blocking and request validation. The OAuth HTTP client also blocks redirects to prevent redirect-based SSRF.
  • Client ID Metadata Documents (SEP-991, mcp-cimd): a cache-backed fetcher with metadata discovery and validation for OAuth clients.
  • OpenID Connect Discovery (RFC 8414, mcp-oidc-discovery): authorization server metadata discovery with TTL-based caching.
  • Incremental scope consent (SEP-835, mcp-incremental-consent): WWW-Authenticate parsing and incremental authorization flows.

Multi-tenant SaaS support

If one TurboMCP process serves several customers, 2.3.0 adds the pieces you would otherwise write yourself:

  • A TenantConfigProvider trait with static and dynamic implementations, and per-tenant configuration for rate limits, timeouts, tool permissions, and request size limits.
  • MultiTenantMetrics with LRU-based eviction (1000 tenants by default).
  • A tenant extraction layer with HeaderTenantExtractor, SubdomainTenantExtractor, and CompositeTenantExtractor.
  • RequestContext::tenant() and require_tenant() for reading the tenant, and validate_tenant_ownership() to refuse cross-tenant access with a ResourceAccessDenied error.

The shipped multi_tenant_server example shows the pattern. This is adapted from it:

use turbomcp::prelude::*;

#[server(name = "multi-tenant-example", version = "1.0.0")]
impl MultiTenantServer {
    #[tool("Get a resource by ID (validates tenant ownership)")]
    async fn get_resource(&self, ctx: Context, resource_id: String) -> McpResult<String> {
        // Reject requests that carry no tenant
        let _tenant_id = ctx.request.require_tenant()?;

        let resources = self.resources.read().await;
        let resource = resources
            .get(&resource_id)
            .ok_or_else(|| McpError::Tool(format!("Resource not found: {}", resource_id)))?;

        // Refuse access to another tenant's data
        ctx.request.validate_tenant_ownership(&resource.tenant_id)?;

        Ok(format!("Resource: {} (Name: {})", resource.id, resource.name))
    }
}

Build it with the multi-tenancy feature on top of full:

cargo run --example multi_tenant_server --features full,multi-tenancy

Tenant ownership validation is the part that matters. Extracting a tenant ID is easy to get right once; checking ownership on every resource access is what actually prevents cross-tenant reads.

Breaking changes and migration

Most of 2.3.0 is additive. These are the exceptions.

Elicitation API

ElicitRequestParams is now an enum with Form and Url variants. Struct-literal construction no longer compiles; use the ElicitRequestParams::form() factory and the new message() accessor. On the client, ElicitationRequest::schema() returns Option<&ElicitationSchema> (None for URL mode), timeout() returns None for URL mode, and is_cancellable() returns false for URL mode.

OAuth 2.1 dependency upgrade

If you use the auth feature, oauth2 moves from 4.4.2 to 5.0.0:

  • The client uses the typestate API (compile-time endpoint tracking).
  • set_revocation_uri() is now set_revocation_url(), and StandardRevocableToken moves to the oauth2:: root.
  • jsonwebtoken moves from 9.2 to 10.2.0 with the aws_lc_rs backend.

The upgrade removes 29 transitive dependencies, including the duplicate reqwest 0.11 and several old base64 versions.

Known issue: token revocation

OAuth2Client::revoke_token() returns an error in 2.3.0 because of the oauth2 5.0 typestate constraints. Tokens still expire normally on their TTL. If you rely on explicit revocation, stay on 2.2.x for that path until it is addressed.

The 2.3.x patch line

Version Date Why you care
2.3.1 2025-12-09 Adds URL_ELICITATION_REQUIRED (-32042), ToolExecution/TaskSupportMode, and Tool::with_execution(). tower-http 0.6.8.
2.3.2 2025-12-09 MCP Inspector fix: explicit CORS preflight handling and Access-Control-Expose-Headers: mcp-session-id, mcp-protocol-version. Regression tests for tool serialization.
2.3.3 2025-12-09 The #[server] HTTP middleware method now uses ::turbomcp::axum::Router, so you no longer need axum as a direct dependency.
2.3.4 2025-12-13 WebSocket client requests no longer time out (responses are routed to correlation handlers). mcp-tasks propagates to turbomcp-server. Error::source() returns the real source.
2.3.5 2025-12-16 Configurable protocol version negotiation. Fixes Claude Code connection failures.
2.3.6 2026-01-03 Security hardening: TLS 1.3 default, TLS bypass gate, JWT algorithm allowlist, and more.
2.3.7 2026-01-05 Protocol compliance tests and a WebSocket test-hang fix.

Browser tools and MCP Inspector (2.3.2)

Browser-based clients such as MCP Inspector were blocked because Axum answered the CORS preflight with 405 before CorsLayer ran, and because browsers cannot read response headers that are not in the expose list. Both are fixed. CORS is still off by default; enable it for browser tools with ENABLE_CORS=1.

Claude Code compatibility (2.3.5)

Claude Code only supports 2025-06-18, while TurboMCP advertised 2025-11-25 without proper negotiation. 2.3.5 adds ProtocolVersionConfig:

  • latest(): prefers 2025-11-25, fallback enabled (the default).
  • compatible(): prefers 2025-06-18.
  • strict(version): accepts only that version.
  • custom(preferred, supported): full control.

With the macro:

// Claude Code compatible
#[turbomcp::server(protocol_version = "compatible")]
impl MyServer { /* ... */ }

// Only accept one version
#[turbomcp::server(protocol_version = "strict:2025-11-25")]
impl MyServer { /* ... */ }

Negotiation works like this: if the client’s version is in your supported list, the server answers with it; otherwise it offers its preferred version when allow_fallback is true, and rejects the connection when it is false.

Security hardening (2.3.6)

This release came out of a security audit. If you terminate TLS or validate JWTs with TurboMCP, read the changelog entry in full. The main points:

  • Disabling certificate validation now requires TURBOMCP_ALLOW_INSECURE_TLS=1. Without it the client panics with a security error.
  • The default minimum TLS version is now 1.3 (TlsVersion::default() returns Tls13). TLS 1.2 is still available as TlsVersion::Tls12 but is deprecated.
  • MultiIssuerValidator only accepts asymmetric JWT algorithms (ES256/384, RS256/384/512, PS256/384/512), which blocks algorithm confusion attacks.
  • API keys must be at least 32 characters; validate_api_key() returns false for shorter keys.
  • Path traversal detection now covers URL-encoded patterns, null bytes, and Unicode lookalikes.
  • native-tls is gone from the dependency tree; HTTP clients use rustls explicitly.

The API key and TLS default changes can break existing deployments. Test staging with 2.3.6 before rolling to production.

Upgrade steps

  1. Bump the dependency. Rust 1.89.0 or later is required.
[dependencies]
turbomcp = "2.3"
tokio = { version = "1", features = ["full"] }
  1. Opt in to the specification features you need, for example:
turbomcp = { version = "2.3", features = ["full", "mcp-tasks", "mcp-url-elicitation"] }
  1. Fix elicitation call sites to use ElicitRequestParams::form().
  2. If you use OAuth, rebuild against oauth2 5.0 and rename set_revocation_uri to set_revocation_url.
  3. If you serve Claude Code, set protocol_version = "compatible".
  4. Check API key lengths (32 characters minimum) and any custom TLS configuration before deploying 2.3.6 or later.

This line was followed by a major release. If you are planning ahead, read TurboMCP v3.0.0, which removes several of the 2.x feature flags and consolidates the error types.

For product details, see the TurboMCP page. If you want help running MCP servers in production, contact us.

  • TurboMCP
  • Rust
  • MCP
  • MCP 2025-11-25
  • Tasks API
  • Multi-Tenancy
  • OAuth 2.1
  • 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.