Technical Guide
TurboMCP v4.0.0-alpha.3: The Client Gets Measured, and the 2026-07-28 Wire Gets Fixed
Alphas 2 and 3 re-generate the 2026-07-28 wire from the frozen schema, add flat composition, and fix client defects found by scoring it against the official conformance suite. v4 is still alpha and APIs may change.
TurboMCP Engineering Team · · 10 min read
TurboMCP v4 is still an alpha, and APIs may change between prereleases. This post covers 4.0.0-alpha.2 (2026-08-30) and 4.0.0-alpha.3 (2026-09-07), the releases where v4 stopped being only a rewrite and started being measured. If you have not read the announcement, start with the alpha.1 post.
Both releases are mostly correctness work. alpha.2 fixes the 2026-07-28 wire, which alpha.1 claimed to speak and did not. alpha.3 scores the client against the official conformance suite for the first time, and fixes what that turned up.
alpha.2: correcting the 2026-07-28 wire
alpha.1’s 2026-07-28 types were generated from the upstream release candidate’s schema/draft/, which was 195 insertions and 91 deletions behind the frozen release. The server advertised the wire string 2026-07-28 while implementing something slightly different. alpha.2 re-generates the wire from the frozen schema.
Four things the freeze reversed, each of which alpha.1 had implemented the RC way:
serverInfomoved back out ofDiscoverResultinto the result’s_meta.ttlMsandcacheScopebecame required onDiscoverResult.SubscriptionsListenResultreturned, which gives a listen stream a defined ending, so a graceful teardown is distinguishable from a dropped connection.elicitationIdandnotifications/elicitation/completewere removed from the revision, making both2025-11-25-only.
The spec-allocated error codes moved with it: -32003 and -32004 became -32021 and -32022, and header mismatch is -32020. Anything that matches on these numbers needs updating.
Other alpha.2 fixes worth knowing about:
- Multi-round elicitation now finishes. A retry carried only the answers from the round that had just completed, so a handler asking two questions in sequence re-asked the first one forever. Answers are now carried forward inside the signed request state. The changelog describes this as a live defect for any two-step elicitation.
- The stateless request envelope is enforced (SEP-2575).
protocolVersionandclientCapabilitiesare required in a request’s_meta; a missing one answers-32602. - Methods that do not exist on
2026-07-28stop being served.initialize,ping,logging/setLevelandresources/{subscribe,unsubscribe}answer-32601and HTTP 404, andClient::ping()now fails locally on that revision. - Error responses carry the request id. Four transport-level rejections hardcoded
id: null. - A missing client capability is
-32021with HTTP 400 and names what is missing, rather than becoming a tool-levelisError. - RUSTSEC-2026-0258 (
h2queued empty DATA frames without limit) was addressed by bumpingh2to 0.4.19.
Naming: Draft becomes V2026_07_28
ProtocolVersion::Draft is now ProtocolVersion::V2026_07_28, and the turbomcp_protocol::draft module is now v2026_07_28. Both old spellings still compile as deprecated aliases and dispatch identically, so this is not a breaking change. LATEST points at V2026_07_28.
Flat composition
Composite::mount namespaces a server’s tools and prompts under a prefix. alpha.2 adds Composite::mount_flat, which keeps a mounted server’s names exactly as they are. That lets you split a large server into focused ones without breaking anything that calls it: read_note stays read_note. The two mix freely in one composite, for example a flat core with prefixed plugins.
Prefixing makes a name clash impossible. Flat mounting makes it detected: two flat mounts exposing one name fail the list that would have shown both, naming both servers. The check runs when a list is built, not at mount time, because with with_visibility installed what a server exposes depends on the caller.
CompositeServer::preflight(request) runs every list ahead of any request, so a clash surfaces at startup instead of on a client’s first tools/list.
let gateway = Composite::new(Implementation::new("gateway", "1.0.0"))
.mount("weather", Weather.into_server())?
.mount("news", News.into_server())?
// Keeps its own names: serves `ping`, not `health.ping`.
.mount_flat(Health.into_server())?;
This is an excerpt adapted from the repository’s composition example; check the example at the tag you depend on for the surrounding setup, since the serving API changed after alpha.2. Resource URIs are never rewritten either way.
alpha.2 also adds #[tool(schema_extend = "{...}")], which preserves JSON Schema vocabulary the server does not interpret (SEP-2106): cross-field rules such as allOf, anyOf and if/then/else cannot be derived from a Rust signature. It is parsed at compile time, so a malformed object is an error on the literal.
alpha.3: scoring the client
The changelog opens with a plain statement: the client had never been measured. Running it against the official conformance suite found four defects, one of which broke every server-initiated request over HTTP against the reference implementation. A second pass over two-way obligations found three more, all on the same seam: the server had implemented its half, and the client had not implemented the other. A third pass, against Rust API guidelines, found a stdio cancel-safety bug.
Defects that testing a server against its own client could not catch
The standalone GET SSE stream is the clearest example. Streamable HTTP lets a server deliver messages it originates either inline on a POST’s stream or on a standalone GET. TurboMCP’s server always did the former, so every in-repo test passed. Against a server that uses the standalone stream, which the reference TypeScript SDK does, every elicitation/create, sampling/createMessage and roots/list over HTTP hung until it timed out. As the changelog puts it, testing both halves of one SDK against each other cannot catch this by construction.
The client now opens that stream as soon as a stateful revision is negotiated, honours the server’s retry: (capped), resumes with Last-Event-ID, and stops permanently on 404, 405 or 501. A second fix holds the handshake response until the stream is up (or the server has said it offers none), because the stream used to race the caller’s first request.
Other client fixes
| Defect | Effect | Fix |
|---|---|---|
| Abandoned request never told the server to stop | Server kept computing an answer nobody read; dropped futures also leaked pending-table entries | Client sends notifications/cancelled on timeout and on drop, except for initialize and task-augmented requests, which the spec exempts |
| Cancellation dropped from a full channel | Cancellation silently lost when the client was busiest | A full channel hands the send to a task on the same channel, preserving order |
| Streamable HTTP ignored cancellation | Server never saw a cancel | Transport drops the named request’s POST, the disconnect a server must read as cancellation |
Ping answered with -32601 |
Violated bidirectional, mandatory ping | Answered inline, before the handler is consulted |
| stdio lost part of a frame under concurrency | Truncated line decoded, connection failed | Buffer is now a resumable accumulator; Transport documents cancel safety as an implementor requirement |
notifications/initialized lacked MCP-Protocol-Version |
Transport-spec violation | Header sent |
| Subscriptions from departed clients accumulated | Unbounded growth on servers whose resources never change | Pruning also runs when a subscription is recorded |
OAuth hardening
- The OAuth client would authorize over plaintext HTTP. The authorization spec requires HTTPS for authorization server endpoints, and
localhostor HTTPS for redirect URIs. Nothing checked a URL’s scheme. It is now checked at every point a URL enters the flow: the issuer, each endpoint in the discovered metadata, everyauthorization_serversentry, and the caller’s redirect URI. Loopback keeps plaintext, as the spec grants for redirect URIs. The allowlist also rejectsjavascript:,data:,file:andvbscript:authorization URLs. - Protected Resource Metadata’s
resourceis now validated (RFC 9728 section 3.3). Previously anyone able to serve or tamper with the document chose where the client would authorize. The declaredresourcemust now cover the endpoint being used. - The token endpoint auth method follows server metadata. The client always used
client_secret_basic; a server advertising onlyclient_secret_postrejected the exchange. The method is now chosen fromtoken_endpoint_auth_methods_supported.
Added in alpha.3
BearerSource, plusHttpClientTransport::with_bearerandwith_bearer_source.turbomcp-authalready produced tokens, but the HTTP transport had no way to send them. The source is consulted per request, so a token refreshed out of band takes effect without rebuilding the transport or redoing the handshake.- The client half of the conformance suite, scored in CI, including discovery variants, dynamic registration, PKCE, the RFC 9207
isstable in both directions, scope step-up, and re-registration when a resource moves to a different authorization server. - Cross-SDK interop on
2026-07-28in both directions. Before this, the stateless revision was verified only by our own code on both ends. - CI checks that generated wire types match the pinned upstream schema and that the lockfile matches the manifests.
Changed in alpha.3
- Dependency majors:
tower-http0.7,jsonwebtoken11,syn3,prettyplease0.3,typify0.7, and the OpenTelemetry crates to 0.32. The changelog states no public API moved, and MSRV stays 1.88. - Every public type now implements
Debug. Twenty-nine did not, includingClient,ClientBuilder,ServerBuilderand all three transports. Types holding credentials redact: the OAuth credential store reports counts, the HTTP transport reports whether it is authenticated, andSessionStorereports a count.
Conformance status at alpha.3
At this release the changelog reports both suites running with an empty failure baseline: 732 client checks pass and 227 server checks pass, with zero failures on either side. The earlier attribution of the sse-retry failure to an upstream harness defect was wrong; it passed as soon as the stream came up on time.
Later alphas tightened how these numbers are counted (distinct scenario/check pairs, with hash-pinned fixture corrections for the client). Use the figures in the alpha.5 post for the current state rather than comparing these directly.
Upgrading
- Anything matching on
2026-07-28error codes should use-32020,-32021and-32022as above. ProtocolVersion::Draftand thedraftmodule still compile as deprecated aliases; move toV2026_07_28andv2026_07_28.Composite::mountnow takesimpl AsRef<str>for the prefix, which is source-compatible.VersionDispatcher::close_subscriptionsandclose_allare async.CachePoliciesgained adiscoversurface; the default staysNO_CACHE.
For the project’s position on the stable channel, see the product page. To discuss adopting v4 or staying on v3, get in touch.
- TurboMCP
- v4
- Alpha
- Rust
- MCP
- Conformance
- OAuth
- Release