Skip to content
← Blog

Release

TurboMCP v3.1.0: Audit Remediation, Spec-Compliant HTTP, and the 3.0.x to 3.1.5 Line

TurboMCP 3.1.0 fixes a no-op OAuth expiry check, enforces DPoP ath at the resource server, adds graceful HTTP shutdown, and makes protocol negotiation multi-version by default. Also: the 3.0.x themes and 3.1.1 to 3.1.5 follow-ups.

TurboMCP Engineering Team · · 10 min read

TurboMCP 3.1.0 was released on 2026-04-17. It is the remediation pass from an audit of 3.0.13, and it is mostly about making things that looked like they worked actually work: an OAuth token expiry check that never returned true, a graceful-shutdown setting that was stored and ignored, an HTTP client that raced on endpoint discovery, and unbounded buffers in the WebSocket path.

If you run TurboMCP with OAuth, DPoP, or the HTTP/WebSocket transports, you should upgrade. Several changes are source-breaking at compile sites (listed below), though each fix is a line or two.

Security fixes

  • Expired OAuth tokens were never detected. OAuth2Client::is_token_expired compared expires_in == 0, treating a relative duration as a countdown, so it never returned true and callers forwarded expired bearer tokens indefinitely. TokenInfo now records issued_at, with expires_at, is_expired, and is_expired_with_skew(Duration) helpers. The check uses 60 seconds of clock skew.
  • DPoP ath is enforced at the resource server (RFC 9449 section 4.3). Previously a stolen proof could be paired with a separately issued access token. Now, when an access token is presented, a proof without ath fails with DpopError::AccessTokenHashFailed.
  • TLS advisories resolved. aws-lc-sys 0.38.0 to 0.40.0 and rustls-webpki 0.103.9 to 0.103.12 address RUSTSEC-2026-0044, -0048, -0049, -0098, and -0099. These affect outbound HTTPS in auth (OIDC discovery, JWKS), transport, and client.
  • SSRF protection is on by default for JWT issuer discovery. JwtValidator::new and MultiIssuerValidator::add_issuer wrap an SsrfValidator::default() policy (loopback, RFC 1918, link-local, cloud metadata). This matters in multi-issuer setups where the issuer string comes from an attacker-controllable JWT payload.
  • DPoP nonce tracker is bounded. MemoryNonceTracker takes with_capacity(usize) (default 1,000,000) with time-ordered eviction at an 80% high-water mark, and lookup is O(1). Before, it was unbounded with no automatic cleanup.
  • API keys are stored as BLAKE3 digests, not plaintext. add_api_key now returns McpResult<()> and rejects keys shorter than MIN_API_KEY_LENGTH; list_api_keys is removed in favor of api_key_count().
  • PKCE verifier is a SecretString, and OAuth state comparison no longer leaks length through timing.
  • OAuth redirect URIs reject 0.0.0.0. Allowed loopback hosts are exactly 127.0.0.1, [::1], and localhost.

Transport fixes

Area Before 3.1.0 In 3.1.0
HTTP shutdown with_graceful_shutdown stored but ignored; SIGTERM aborted in-flight responses Waits for SIGINT/SIGTERM, drains in-flight requests up to the configured timeout (max 60s)
HTTP client construction StreamableHttpClientTransport::new panicked on bad TLS config Returns TransportResult<Self>
HTTP endpoint discovery Fixed 500 ms sleep, racy on slow networks Awaits a oneshot fired on the first endpoint SSE event
SSE reads Could stall on a half-open TCP connection sse_read_timeout (default 5 minutes) lets the reconnect loop take over
WebSocket outbound Unbounded channels, a memory DoS from slow readers Bounded at 1024; saturated pong buffer closes the connection
STDIO backpressure Dropped messages with a warn! log Awaits channel capacity
TCP Nagle’s algorithm could delay small frames TCP_NODELAY set after accept and connect

The HTTP client also gets an async recv_async() that awaits both the POST response queue and the SSE stream.

Graceful shutdown with the builder looks like this (from the builder documentation in the repository):

use std::time::Duration;
use turbomcp::prelude::*;

#[tokio::main]
async fn main() {
    MyServer.builder()
        .transport(Transport::http("0.0.0.0:8080"))
        .with_rate_limit(100, Duration::from_secs(1))
        .with_connection_limit(1000)
        .with_graceful_shutdown(Duration::from_secs(30))
        .serve()
        .await
        .unwrap();
}

Protocol and macro fixes

  • ProtocolConfig::default() is multi-version. The default supported_versions is now every stable version rather than only the latest, and older clients (for example 2025-06-18) are accepted through version adapters. If you want exact-match behavior, use ProtocolConfig::strict.
  • #[tool] schemas for scalar and optional parameters were wrong. A bool parameter was emitted as an opaque object, so LLM clients sent wrongly typed values. Non-object root schemas are now wrapped under allOf so they describe the property correctly. Absent versus present-but-malformed optional parameters are also distinguished.
  • #[prompt] arguments surface #[description("...")] in PromptArgument.description.
  • CompositeHandler prefix routing no longer mis-splits prefixes containing _ or :// (a prefix like my_weather previously failed to route).
  • ResourceTemplate::new validates RFC 6570 structure (unbalanced or nested braces), and JsonRpcError::with_validated_code rejects out-of-range codes.

Breaking changes and migration

Change Fix
TokenInfo gains issued_at: Option<SystemTime> Add the field to literal constructors. It is serde(default), so cached v3.0 tokens still load.
validate_proof and parse_and_validate_jwt take ProofContext Pass ProofContext::ResourceServer or ProofContext::TokenEndpoint
StreamableHttpClientTransport::new returns a Result Add ?
authorization_code_flow returns (String, SecretString) Use expose_secret()
add_api_key returns McpResult<()>; list_api_keys removed Add ?; use api_key_count()
JwtValidator::new applies SSRF policy Use new_unchecked for tests against private OIDC providers
Default protocol config is multi-version ProtocolConfig::strict(...) restores single-version
Loopback redirect rejects 0.0.0.0 Use 127.0.0.1, [::1], or localhost

The two that need real code attention are the DPoP and HTTP client changes:

use turbomcp_dpop::ProofContext;

// v3.0.x
// gen.validate_proof(&proof, "POST", uri, Some(token)).await?;

// v3.1.0
gen.validate_proof(&proof, "POST", uri, Some(token), ProofContext::ResourceServer).await?;

// v3.0.x: let transport = StreamableHttpClientTransport::new(config);
let transport = StreamableHttpClientTransport::new(config)?;

Strict single-version behavior:

let cfg = ServerConfig::builder()
    .protocol(ProtocolConfig::strict(ProtocolVersion::LATEST.clone()))
    .build();

The 3.0.x line in themes

Between 3.0.0 and 3.1.0 there were fourteen patch releases (2026-03-05 to 2026-04-15). The ones worth knowing:

  • Security (3.0.3, 3.0.6). Constant-time API key comparison, JWT scope and aud enforcement (RFC 8707), DNS-resolving SSRF checks in the proxy, JWT aud parsing that accepts both string and array forms (RFC 7519), a 64 KB JWKS response limit, opaque error IDs instead of internal error text in JSON-RPC responses, and max_tracked_ips on the rate limiter. lz4_flex, quinn-proto, and lru were updated or replaced for RUSTSEC advisories.
  • Protocol policy (3.0.3, 3.0.8 to 3.0.10). 3.0.3 narrowed v3 to MCP 2025-11-25 only. 3.0.8 reversed course with a ProtocolVersion enum and version adapters that filter responses to match the client’s negotiated version. 3.0.9 and 3.0.10 stored the negotiated version per session on every transport and enforced the initialize lifecycle. The default became multi-version in 3.1.0.
  • Client features (3.0.4, 3.0.11). Progress notification handlers, automatic cursor pagination for list operations, RequestContext::notify_client(), and tool-list-changed helpers.
  • Streamable HTTP (3.0.13). The full spec lifecycle (POST, GET SSE, DELETE), origin validation, per-session request ID deduplication, an SSE primer event, and 413 for oversized bodies. JSON Schema 2020-12 keywords are preserved on tool schemas.
  • Resources (3.0.14). Custom URI schemes such as notion:// or slack:// now reach your resource handlers. An earlier hardcoded scheme allowlist violated the spec.
  • Channel transport (3.0.1). An in-process channel transport for same-process MCP communication.

3.1.1 to 3.1.5

Version Date Summary
3.1.1 2026-04-21 turbomcp-types becomes the sole canonical home for MCP types; RequestContext is unified with bidirectional session state; CLI rejects symlink-based path escapes.
3.1.2 2026-04-27 Spec gaps closed: resources/subscribe, resources/unsubscribe, logging/setLevel, and completion/complete routing; notifications/cancelled actually cancels in-flight handlers; Tasks API typed routing; proxy origin allowlist.
3.1.3 2026-04-29 Strict jsonrpc: "2.0" validation, DPoP replay and private-JWK checks, removal of the deprecated turbomcp-transport::axum subtree.
3.1.4 2026-05-08 Server-initiated sampling, elicitation, and notifications over Streamable HTTP/SSE; resources/templates/list across server, client, macros, and proxy.
3.1.5 2026-05-11 Interoperability with RMCP and Codex clients; a visibility policy for exact allowed, disabled, and hidden rules on tools, resources, and prompts.

Two items deserve a note. 3.1.4 means ctx.sample(...), ctx.elicit_form(...), ctx.elicit_url(...), and ctx.notify_client(...) now send requests and notifications over SSE on initialized HTTP sessions, and client responses POSTed with the session ID are correlated back to the handler. 3.1.5’s visibility policy lets you trim tools/list for context-constrained LLM clients: hidden components are omitted from lists but remain callable, disabled components are rejected on direct use, and disabled wins over hidden or allowed.

Upgrade steps

  1. Bump the dependency to the latest 3.1 patch:
[dependencies]
turbomcp = "3.1"
  1. Fix the compile sites in the migration table above.
  2. Re-run any OAuth or DPoP tests, particularly resource server paths that previously accepted proofs without ath.
  3. If you pinned a single protocol version for older clients, decide whether the new multi-version default is what you want.
  4. If you depend on turbomcp-transport::axum (removed in 3.1.3), move to turbomcp_server::transport::http, run_http, or into_axum_router.
  5. Add graceful shutdown to HTTP deployments and test SIGTERM handling in your orchestrator.

Earlier in the series: TurboMCP v3.0.0 covers the rewrite. See also the TurboMCP product page, or contact us for help with production MCP deployments.

  • TurboMCP
  • Rust
  • MCP
  • Security
  • DPoP
  • OAuth 2.1
  • Streamable HTTP
  • Migration

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.