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_expiredcomparedexpires_in == 0, treating a relative duration as a countdown, so it never returnedtrueand callers forwarded expired bearer tokens indefinitely.TokenInfonow recordsissued_at, withexpires_at,is_expired, andis_expired_with_skew(Duration)helpers. The check uses 60 seconds of clock skew. - DPoP
athis 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 withoutathfails withDpopError::AccessTokenHashFailed. - TLS advisories resolved.
aws-lc-sys0.38.0 to 0.40.0 andrustls-webpki0.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::newandMultiIssuerValidator::add_issuerwrap anSsrfValidator::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.
MemoryNonceTrackertakeswith_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_keynow returnsMcpResult<()>and rejects keys shorter thanMIN_API_KEY_LENGTH;list_api_keysis removed in favor ofapi_key_count(). - PKCE verifier is a
SecretString, and OAuthstatecomparison no longer leaks length through timing. - OAuth redirect URIs reject
0.0.0.0. Allowed loopback hosts are exactly127.0.0.1,[::1], andlocalhost.
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 defaultsupported_versionsis 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, useProtocolConfig::strict.#[tool]schemas for scalar and optional parameters were wrong. Aboolparameter was emitted as an opaqueobject, so LLM clients sent wrongly typed values. Non-object root schemas are now wrapped underallOfso they describe the property correctly. Absent versus present-but-malformed optional parameters are also distinguished.#[prompt]arguments surface#[description("...")]inPromptArgument.description.CompositeHandlerprefix routing no longer mis-splits prefixes containing_or://(a prefix likemy_weatherpreviously failed to route).ResourceTemplate::newvalidates RFC 6570 structure (unbalanced or nested braces), andJsonRpcError::with_validated_coderejects 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
audenforcement (RFC 8707), DNS-resolving SSRF checks in the proxy, JWTaudparsing 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, andmax_tracked_ipson the rate limiter.lz4_flex,quinn-proto, andlruwere 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
ProtocolVersionenum 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
413for oversized bodies. JSON Schema 2020-12 keywords are preserved on tool schemas. - Resources (3.0.14). Custom URI schemes such as
notion://orslack://now reach your resource handlers. An earlier hardcoded scheme allowlist violated the spec. - Channel transport (3.0.1). An in-process
channeltransport 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
- Bump the dependency to the latest 3.1 patch:
[dependencies]
turbomcp = "3.1"
- Fix the compile sites in the migration table above.
- Re-run any OAuth or DPoP tests, particularly resource server paths that previously accepted proofs without
ath. - If you pinned a single protocol version for older clients, decide whether the new multi-version default is what you want.
- If you depend on
turbomcp-transport::axum(removed in 3.1.3), move toturbomcp_server::transport::http,run_http, orinto_axum_router. - 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