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-Authenticateparsing 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
TenantConfigProvidertrait with static and dynamic implementations, and per-tenant configuration for rate limits, timeouts, tool permissions, and request size limits. MultiTenantMetricswith LRU-based eviction (1000 tenants by default).- A tenant extraction layer with
HeaderTenantExtractor,SubdomainTenantExtractor, andCompositeTenantExtractor. RequestContext::tenant()andrequire_tenant()for reading the tenant, andvalidate_tenant_ownership()to refuse cross-tenant access with aResourceAccessDeniederror.
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 nowset_revocation_url(), andStandardRevocableTokenmoves to theoauth2::root.jsonwebtokenmoves from 9.2 to 10.2.0 with theaws_lc_rsbackend.
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(): prefers2025-11-25, fallback enabled (the default).compatible(): prefers2025-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()returnsTls13). TLS 1.2 is still available asTlsVersion::Tls12but is deprecated. MultiIssuerValidatoronly 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()returnsfalsefor shorter keys. - Path traversal detection now covers URL-encoded patterns, null bytes, and Unicode lookalikes.
native-tlsis 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
- Bump the dependency. Rust 1.89.0 or later is required.
[dependencies]
turbomcp = "2.3"
tokio = { version = "1", features = ["full"] }
- Opt in to the specification features you need, for example:
turbomcp = { version = "2.3", features = ["full", "mcp-tasks", "mcp-url-elicitation"] }
- Fix elicitation call sites to use
ElicitRequestParams::form(). - If you use OAuth, rebuild against
oauth25.0 and renameset_revocation_uritoset_revocation_url. - If you serve Claude Code, set
protocol_version = "compatible". - 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