Skip to content
← Blog

Release

TurboMCP v3.5.0: Spec-Correct Progress, Bidirectional WebSocket, and a Full Conformance Audit

TurboMCP 3.5.0 fixes progress reporting, opens completions, subscriptions and logging to macro servers, makes WebSocket bidirectional, and closes sixteen broken MUSTs found in a spec audit.

TurboMCP Engineering Team · · 14 min read

TurboMCP 3.5.0 (2026-09-25) is the largest release on the 3.x line. It started with a downstream report that a long-running handler could not report progress on any transport, grew into a feature-by-feature audit of the SDK against the MCP specification, and ended with a second end-to-end audit of the release itself. This post covers the themes. The changelog has the per-item detail, and MIGRATION.md in the repository lists the breaking changes with upgrade steps.

If you run MCP in production, the items most likely to matter to you are the handshake fix for older clients, the fix for lost stdio/TCP/Unix input, panic handling on every transport, WebSocket server-to-client calls, and the new OAuth 2.1 protected-resource support on the Streamable HTTP server.

How it started: progress

The report had four assertions and two held. Nothing in the request path ever read params._meta.progressToken, so the token a client sends to ask for progress never reached a handler. And the WebSocket transport built its RequestContext without an McpSession, so sample, elicit_form, elicit_url and notify_client all failed there. HTTP, STDIO, TCP, Unix and channel were wired correctly.

Underneath was a worse bug. The one progress helper shipped, RichContextExt::report_progress, used the request id as the progress token. The specification says progress notifications “MUST only reference tokens that were provided in an active request.” The SDK emitted notifications carrying a token no client had issued, even when progress had never been requested.

The new API

RequestContext gains report_progress(progress, total, message), alongside sample and elicit_*. The router lifts params._meta.progressToken off any incoming request once, centrally, and progress_token() and wants_progress() expose it.

use turbomcp::prelude::*;

#[derive(Clone)]
struct Slow;

#[server(name = "slow", version = "1.0.0")]
impl Slow {
    /// Reports progress unconditionally, the way a handler author would.
    #[tool]
    async fn work(&self, ctx: &RequestContext) -> McpResult<String> {
        ctx.report_progress(1.0, Some(3.0), Some("starting")).await?;
        ctx.report_progress(3.0, Some(3.0), None).await?;
        Ok("done".into())
    }
}

The method is a no-op returning Ok(()) when the client sent no token or the transport has no session. Both are correct: progress is optional, and referencing a token that was never issued is forbidden. Handlers can call it unconditionally, and wants_progress() lets you skip expensive instrumentation when nobody is listening.

Notifications emitted during a request could also arrive after its response, because the transport loops polled completed responses ahead of outgoing session traffic. Outgoing session commands are now drained first on WebSocket and on the line transports.

Breaking: removed helpers

RichContextExt::report_progress and report_progress_with_token are removed from turbomcp-protocol. The old behaviour was itself the bug, and report_progress_with_token has no replacement because choosing your own token is what the specification forbids. Callers move from ctx.report_progress(50.0, 100.0, Some("...")) to ctx.report_progress(50.0, Some(100.0), Some("...")). The trait was never re-exported from the turbomcp facade, so for anyone depending on turbomcp alone, progress reporting was unreachable before. In turbomcp-wasm, the old method is renamed log_progress, since it only formats to the console.

Opening #[server]’s sealed extension points

#[server] generated a complete impl McpHandler with no override hook, and no second impl block is possible. Five of the trait’s extension points were unreachable for every macro-built server. Completions, resource subscriptions and logging were not merely undocumented, they were impossible.

Marker Serves Capability advertised
#[completion] completion/complete completions
#[subscribe] resources/subscribe resources.subscribe
#[unsubscribe] resources/unsubscribe none (required with #[subscribe])
#[set_level] observes logging/setLevel none (logging is always declared)
#[roots_changed] notifications/roots/list_changed none (roots is a client capability)

Declaring a marker generates the override and flips the matching capability. Omitting it keeps the trait default, which answers capability_not_supported, and leaves the capability unadvertised. The two move together by construction, so a server cannot claim a capability it would refuse to serve. #[subscribe] without #[unsubscribe] is a compile error, because only the author knows how to undo a subscription. A trailing ctx: &RequestContext is optional on all five.

#[server(name = "docs", version = "1.0.0")]
impl Docs {
    #[tool]
    async fn search(&self, query: String) -> McpResult<String> { /* ... */ }

    #[completion]
    async fn complete(&self, params: serde_json::Value) -> McpResult<serde_json::Value> {
        // ...
    }

    #[subscribe]
    async fn watch(&self, uri: String, ctx: &RequestContext) -> McpResult<()> {
        // ...
    }

    #[unsubscribe]
    async fn unwatch(&self, uri: String) -> McpResult<()> {
        // ...
    }
}

This sketch is adapted from the #[server] documentation at the 3.5.0 tag, where it is marked illustrative, with the required #[unsubscribe] added. The unwatch signature follows the documented #[unsubscribe] form, where ctx is optional. The sketch itself was not compiled.

Supporting additions:

  • Typed notification helpers on RequestContext: notify_resource_updated(uri), notify_tools_list_changed(), notify_resources_list_changed() and notify_prompts_list_changed().
  • RequestContext::list_roots asks the client for its filesystem roots (gated on the roots capability), paired with McpHandler::on_roots_list_changed.
  • RequestContext::notify_elicitation_complete and the client-side ElicitationCompleteHandler close the URL-mode elicitation loop.
  • Json<T> now advertises its outputSchema, inferred from the return type (Json<T>, McpResult<Json<T>>, Result<Json<T>, E>). The declaration is gated on the schema describing an object, so Json<Vec<_>> advertises nothing and sends its data as text rather than promising a shape the result may not deliver.
  • McpHandler::page_size and #[server(page_size = N)] opt a server into paged list methods with opaque nextCursors. The default stays None. A supplied cursor is now honoured, where before a client walking pages was served page one forever.
  • #[title("...")] on a prompt argument, and #[resource(audience, priority, last_modified, size)] and #[tool(task_support)].

Wrappers stop dropping methods

VisibilityLayer and CompositeHandler silently dropped complete, subscribe, unsubscribe and set_log_level, so wrapping a server disabled those features whatever the inner handler implemented. MiddlewareStack similarly failed to forward several methods. All are forwarded now. VisibilityLayer gates subscriptions and completions by the same rule as reads, so a hidden resource stays indistinguishable from one that does not exist.

WebSocket is bidirectional

The WebSocket transport gets a per-connection session handle. Handler tasks push onto a channel the connection loop drains, so a handler awaiting session.call() never blocks the socket’s read side. The receive loop now distinguishes a client’s response to a server-initiated request from a new request, and client capabilities are captured at initialize. Sampling, both elicitation modes, list_roots and notifications now work on the one transport that had none.

The stdio, TCP, Unix, WebSocket and channel transports now share one session implementation. Abandoned server requests no longer leak their slot (after 64 unanswered samples or elicitations a connection could never make another), a disconnect no longer hangs the server, and logging/setLevel and log rate limiting work outside HTTP.

Specification conformance

After the work above, TurboMCP 3.x was audited against the MCP specification feature by feature, across both wire versions it serves, with every finding independently re-checked. Sixteen broken MUSTs came out of it, and all sixteen are fixed. The three with the widest blast radius:

  1. Older clients were refused instead of offered a supported version. allow_fallback defaulted to false, so a client asking for 2024-11-05 or 2025-03-26 (legacy Claude Desktop configs, MCP Inspector defaults, older SDK clients) got a hard error on its first message. The lifecycle spec allows exactly two outcomes, respond with the same version or with another version the server supports. Refusing is neither. The fallback machinery existed and was switched off.
  2. stdio, TCP and Unix readers could silently lose part of a message. AsyncBufReadExt::read_line is documented as not cancel safe, and the other arms of that tokio::select! are fed by concurrently spawned handler tasks, so losing the race was routine. Any request that did not arrive in a single poll could lose its prefix and desynchronise the stream. Reading now happens on its own task.
  3. A malformed server-to-client request got no answer. When sampling/createMessage or elicitation/create params failed to deserialize, nothing was sent back, and on the line transports SessionHandle::call awaits with no timeout, so the hang was permanent. Both paths now answer -32602.

Other conformance fixes include:

  • outputSchema is no longer stripped for 2025-06-18 clients, where it is part of the Tool schema.
  • URLElicitationRequiredError now carries data: { elicitations: [...] } as the spec requires.
  • The client answers a server ping instead of -32601, and no longer cancels its own initialize on timeout.
  • Streamable HTTP validates MCP-Protocol-Version on initialize and sessionless ping.
  • turbomcp-proxy no longer double-wraps resources/read results, which had made every proxied resource read undeserialisable by typed clients.
  • The client sent "params": null on parameterless notifications, which the TypeScript SDK’s schema rejects. That made the handshake fail against every TypeScript-SDK server. params is now omitted.

Error codes

TurboMCP used a homegrown -32001..-32006 scheme that diverged from the spec and reused -32002 for a failed tool call, so a client keying off the code read a tool failure as a missing resource. The mapping now follows the specification:

Condition Was Now
Resource not found -32004 -32002
Unknown tool -32001 -32602
Invalid prompt name -32003 -32602
Capability not supported -32006 -32601
Tool ran and failed -32002 -32603

The exact ErrorKind still travels in _meta under io.turbomcp/errorKind, and retired codes are still understood on ingress so peers on older TurboMCP are read correctly. Other enforcement changes: missing name or uri params now answer -32602, logging/setLevel is validated, stored per session and applied, and completion responses are capped at 100 values with hasMore set on truncation.

Hardening

The audit also flagged nine behaviours that were conformant but fragile. Notable ones:

  • A panicking handler produced no response. All transports, including Streamable HTTP, now convert a panic to -32603. The connection survives, the panic is logged in full, and the client sees only a summary.
  • One malformed capability erased all the others. Client capabilities are now parsed field by field instead of falling back to defaults, so a newer peer’s unknown sub-capability no longer makes every server-initiated call fail.
  • Auto-pagination truncated lists. Client loops stopped on an empty page even when nextCursor was present, and now stop on a repeated cursor instead. The proxy’s introspection loops are bounded.
  • The client sent a hardcoded MCP-Protocol-Version. It now uses the version negotiated at initialize.
  • Nested composite mount prefixes could shadow a tool. Mounting now rejects nesting and validates the prefix charset.
  • Log notifications are rate limited per session, with over-budget messages dropped and the count reported on the next admitted message. The SSE subscriber queue is bounded. Progress is deliberately not throttled.
  • Child MCP servers get a chance to shut down. Shutdown now closes stdin, waits shutdown_timeout, then sends SIGTERM and finally SIGKILL after a new sigterm_grace, so on_shutdown hooks run. Drop sends SIGTERM instead of SIGKILL.

Streamable HTTP

The flagship remote transport was the one furthest from the transport specification.

  • A POST can answer with text/event-stream. Everything a handler produced mid-call (ctx.sample(), elicitation, progress) was previously pushed onto the standalone GET stream, which the spec reserves for messages unrelated to a running request. A client that only POSTs got -32603 No active SSE stream for HTTP session from every sample. The upgrade is lazy: a handler that says nothing back still gets the single JSON object it always did.
  • notifications/cancelled is honoured over HTTP, with a per-session registry so one client cannot cancel another’s request by guessing an id.
  • SSE streams are resumable via Last-Event-ID, with bounded history, never across streams or sessions.
  • Streams are no longer cut at 30 seconds. The client’s request timeout was reqwest’s whole-request timeout. Streams are now bounded per chunk, and the SSE retry field is honoured.
  • Sessions expire. Idle sessions are reaped (default one hour) and initialize past max_http_sessions gets 503. After a 404 the client re-initializes once and retries.
  • trusted_proxies now works, allow_missing_origin admits non-browser clients without weakening the Origin check, and a cross-origin SSE endpoint event is refused rather than followed with the bearer token.

MCP authorization

The native server had none: turbomcp-auth shipped the pieces and no transport called them. ServerConfig::authorization(HttpAuthorization) now makes the Streamable HTTP server an OAuth 2.1 protected resource:

  • RFC 9728 metadata at /.well-known/oauth-protected-resource.
  • 401 with a WWW-Authenticate challenge carrying resource_metadata and supported scopes, and 403 insufficient_scope.
  • Tokens from the header only, the principal on the request context, and each session bound to the principal that created it.
  • turbomcp_auth::server::JwtBearerValidator validates JWTs, including the audience check.

On the client, StreamableHttpClientConfig::auth_provider receives the parsed challenge on a 401 or 403 and the request is retried once. turbomcp_auth::discovery::ClientDiscovery follows the 2025-11-25 discovery order and refuses a server that does not advertise S256 PKCE.

Security fixes in turbomcp-auth and turbomcp-dpop: OAuth2Provider validates token audience, the RFC 8707 resource parameter is sent on authorization, token and refresh requests, nbf is enforced, SSRF checks are pinned to the connection and cover the JWKS URI, JWKS fetches follow no redirects, and redirect URIs must be HTTPS or loopback unless custom schemes are opted into. DpopValidator is removed because it verified neither the proof’s signature nor its HTTP binding.

Sampling and elicitation

sampling/createMessage is the one request a server assembles itself, so nothing on the inbound path inspects it.

  • Client::enable_sampling_tools() and enable_sampling_context() let a client declare the capabilities a spec-abiding server needs before sending tools, toolChoice or includeContext.
  • CreateMessageRequest::validate enforces the message content constraints, and RequestContext::sample refuses a sequence that breaks them, instead of letting the provider return an opaque 400.
  • McpSession::protocol_version() lets a handler ask which wire it is writing to, and sample() refuses 2025-11-25-only content on a 2025-06-18 session.
  • Task-augmented sampling is refused up front, since there is no server-initiated tasks/result path.
  • The typed elicitation schema now covers multi-select and titled single-select properties.
  • URL-mode elicitation completion ids are tracked and consumed on the client, so an injected notification cannot drive retry logic with an invented id.

Resources and WASM

  • #[resource] dispatch now matches the full RFC 6570 URI template. Previously only the text before the first { and after the last } was compared, so db://{table}/rows/{id}.json also claimed db://totally/unrelated/path.json. Concrete resources now dispatch before templates regardless of declaration order, and the WASM server uses the same helper.
  • A composite’s resource URIs round-trip: a URI a client receives is always one it can hand straight back.
  • #[resource(mime_type = "...")] now reaches the read, not just the listing.
  • turbomcp-wasm previously had six JSON-RPC dispatchers. Every entry point now goes through the core router and the 2025-06-18 adapter, and auth, JWKS and crypto work on Cloudflare Workers.
  • Proxy, CLI, OpenAPI, gRPC and telemetry crates received fixes too, including rebuilt turbomcp-proxy stdio frontends, path parameter encoding in turbomcp-openapi, and telemetry that no longer exports resource URIs by default.

Every code sample in the READMEs and documentation site was also checked against 3.5, since many showed APIs that never existed.

Upgrade notes

[dependencies]
turbomcp = "3.5"

The turbomcp facade, turbomcp-core, -cli, -stdio, -tcp, -unix, -websocket, -wire, -transport-traits and -transport-streamable are clean under cargo semver-checks against 3.4.0. Thirteen of the twenty-three checked crates fail, almost all for one of three reasons: a public field added to a struct that could be built by literal, a type or function removed because it was wrong, or a feature removed because it gated nothing.

Crate What breaks
turbomcp-auth Duplicate DCR types and validate_canonical_resource_uri removed; ProtectedResourceMetadata.authorization_servers is now an array
turbomcp-dpop DpopValidator and ValidatedDpopClaims removed
turbomcp-client InitializeResult is #[non_exhaustive]; use InitializeResult::new() and with_instructions()
turbomcp-http StreamableHttpClientConfig.auth_provider added
turbomcp-server ServerConfig.http_sessions and .authorization added
turbomcp-transport ChildProcessConfig.sigterm_grace added; build with ..Default::default()
turbomcp-types Elicitation schema additions; URLElicitationRequiredError reshaped
turbomcp-protocol RichContextExt::report_progress* removed
turbomcp-wasm, turbomcp-proxy, turbomcp-openapi, turbomcp-grpc, turbomcp-telemetry Consolidations and removed no-op features; see MIGRATION.md

Practical checklist:

  1. Move any report_progress call to the new signature, with total as Option<f64>.
  2. Update anything that matches on the old -32001..-32006 error codes. Retired codes are still read on ingress.
  3. If you construct InitializeResult by struct literal, switch to InitializeResult::new().
  4. If you used DpopValidator, plan a replacement. It never verified the proof signature or HTTP binding.
  5. If you build ChildProcessConfig or the server config structs by naming every field, add ..Default::default().

Use the TurboMCP repository for MIGRATION.md, the TurboMCP product page for an overview, or contact us if you want help with an upgrade.

  • TurboMCP
  • Rust
  • MCP
  • Specification
  • Progress
  • Streamable HTTP
  • OAuth 2.1
  • WebSocket
  • v3

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.