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()andnotify_prompts_list_changed(). RequestContext::list_rootsasks the client for its filesystem roots (gated on therootscapability), paired withMcpHandler::on_roots_list_changed.RequestContext::notify_elicitation_completeand the client-sideElicitationCompleteHandlerclose the URL-mode elicitation loop.Json<T>now advertises itsoutputSchema, inferred from the return type (Json<T>,McpResult<Json<T>>,Result<Json<T>, E>). The declaration is gated on the schema describing an object, soJson<Vec<_>>advertises nothing and sends its data as text rather than promising a shape the result may not deliver.McpHandler::page_sizeand#[server(page_size = N)]opt a server into paged list methods with opaquenextCursors. The default staysNone. 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:
- Older clients were refused instead of offered a supported version.
allow_fallbackdefaulted tofalse, so a client asking for2024-11-05or2025-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. - stdio, TCP and Unix readers could silently lose part of a message.
AsyncBufReadExt::read_lineis documented as not cancel safe, and the other arms of thattokio::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. - A malformed server-to-client request got no answer. When
sampling/createMessageorelicitation/createparams failed to deserialize, nothing was sent back, and on the line transportsSessionHandle::callawaits with no timeout, so the hang was permanent. Both paths now answer-32602.
Other conformance fixes include:
outputSchemais no longer stripped for 2025-06-18 clients, where it is part of theToolschema.URLElicitationRequiredErrornow carriesdata: { elicitations: [...] }as the spec requires.- The client answers a server
pinginstead of-32601, and no longer cancels its owninitializeon timeout. - Streamable HTTP validates
MCP-Protocol-Versiononinitializeand sessionlessping. turbomcp-proxyno longer double-wrapsresources/readresults, which had made every proxied resource read undeserialisable by typed clients.- The client sent
"params": nullon parameterless notifications, which the TypeScript SDK’s schema rejects. That made the handshake fail against every TypeScript-SDK server.paramsis 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
nextCursorwas 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 atinitialize. - 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 newsigterm_grace, soon_shutdownhooks 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 sessionfrom every sample. The upgrade is lazy: a handler that says nothing back still gets the single JSON object it always did. notifications/cancelledis 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
retryfield is honoured. - Sessions expire. Idle sessions are reaped (default one hour) and
initializepastmax_http_sessionsgets 503. After a 404 the client re-initializes once and retries. trusted_proxiesnow works,allow_missing_originadmits non-browser clients without weakening the Origin check, and a cross-origin SSEendpointevent 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. 401with aWWW-Authenticatechallenge carryingresource_metadataand supported scopes, and403 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::JwtBearerValidatorvalidates 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()andenable_sampling_context()let a client declare the capabilities a spec-abiding server needs before sendingtools,toolChoiceorincludeContext.CreateMessageRequest::validateenforces the message content constraints, andRequestContext::samplerefuses 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, andsample()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/resultpath. - 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, sodb://{table}/rows/{id}.jsonalso claimeddb://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-wasmpreviously 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-proxystdio frontends, path parameter encoding inturbomcp-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:
- Move any
report_progresscall to the new signature, withtotalasOption<f64>. - Update anything that matches on the old
-32001..-32006error codes. Retired codes are still read on ingress. - If you construct
InitializeResultby struct literal, switch toInitializeResult::new(). - If you used
DpopValidator, plan a replacement. It never verified the proof signature or HTTP binding. - If you build
ChildProcessConfigor 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