Skip to content
← Blog

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:

  • serverInfo moved back out of DiscoverResult into the result’s _meta.
  • ttlMs and cacheScope became required on DiscoverResult.
  • SubscriptionsListenResult returned, which gives a listen stream a defined ending, so a graceful teardown is distinguishable from a dropped connection.
  • elicitationId and notifications/elicitation/complete were removed from the revision, making both 2025-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). protocolVersion and clientCapabilities are required in a request’s _meta; a missing one answers -32602.
  • Methods that do not exist on 2026-07-28 stop being served. initialize, ping, logging/setLevel and resources/{subscribe,unsubscribe} answer -32601 and HTTP 404, and Client::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 -32021 with HTTP 400 and names what is missing, rather than becoming a tool-level isError.
  • RUSTSEC-2026-0258 (h2 queued empty DATA frames without limit) was addressed by bumping h2 to 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 localhost or 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, every authorization_servers entry, and the caller’s redirect URI. Loopback keeps plaintext, as the spec grants for redirect URIs. The allowlist also rejects javascript:, data:, file: and vbscript: authorization URLs.
  • Protected Resource Metadata’s resource is now validated (RFC 9728 section 3.3). Previously anyone able to serve or tamper with the document chose where the client would authorize. The declared resource must now cover the endpoint being used.
  • The token endpoint auth method follows server metadata. The client always used client_secret_basic; a server advertising only client_secret_post rejected the exchange. The method is now chosen from token_endpoint_auth_methods_supported.

Added in alpha.3

  • BearerSource, plus HttpClientTransport::with_bearer and with_bearer_source. turbomcp-auth already 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 iss table in both directions, scope step-up, and re-registration when a resource moves to a different authorization server.
  • Cross-SDK interop on 2026-07-28 in 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-http 0.7, jsonwebtoken 11, syn 3, prettyplease 0.3, typify 0.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, including Client, ClientBuilder, ServerBuilder and all three transports. Types holding credentials redact: the OAuth credential store reports counts, the HTTP transport reports whether it is authenticated, and SessionStore reports 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-28 error codes should use -32020, -32021 and -32022 as above.
  • ProtocolVersion::Draft and the draft module still compile as deprecated aliases; move to V2026_07_28 and v2026_07_28.
  • Composite::mount now takes impl AsRef<str> for the prefix, which is source-compatible.
  • VersionDispatcher::close_subscriptions and close_all are async.
  • CachePolicies gained a discover surface; the default stays NO_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

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.