Epistates/TurboMCP

A ground-up Rust SDK for the Model Context Protocol —
both halves of the protocol, server **and** client — with a macro-driven,
zero-boilerplate surface and strict spec compliance as a feature.
> **Status: 4.0.0-alpha.5 — a prerelease for community testing.** v4 is a
> from-scratch rewrite of TurboMCP; the stable line is 3.x. Edition 2024,
> MSRV 1.88. It interoperates with the official Rust, TypeScript, Python and Go
> SDKs in both directions, on both revisions, and both halves are scored against the official MCP conformance
> suite: 232 successful server assertions and 534 distinct successful client
> scenario/check pairs using pinned client fixture corrections, with zero failures, skips, or warnings. All three advertised revisions (2025-06-18, 2025-11-25,
> 2026-07-28) are dated and frozen; 2026-07-28 is generated from the
> released schema/2026-07-28/, not the RC.
> **Found something broken or unergonomic? Please open an issue.**
What you get
- **One macro defines a server.** #[server] over an impl block turns
#[tool] / #[resource] / #[prompt] methods into a fully-wired MCP server.
The macro generates schema derivation code; schema values are initialized once at runtime and cloned for callers, and
the advertised capabilities are *derived* from which markers are present — they
can't drift from the implementation.
- **Three protocol revisions, one handler.** The same server answers
2025-06-18, 2025-11-25, and 2026-07-28. Your handlers speak
version-neutral types; the version-specific wire shapes are conversions, not
signature changes — including dropping, per session, the fields a revision
predates. Pin the set with #[server(protocols("2025-11-25", …))].
- **Transports behind one builder.** stdio (default), Streamable HTTP (axum),
and WebSocket. MyServer.run_stdio(), or
.into_server().layer(…).serve(Http::bind(addr)): one runtime wires
sessions, DELETE and graceful shutdown, with or without middleware.
WebSocket rides the HTTP endpoint as a route, behind the same guards.
- **The client too.** A typed Client runs the handshake, negotiates the
version, and speaks the same neutral API — interoperating with the official
Rust SDK (rmcp) in both directions.
- **Production seams.** OAuth 2.1 on both halves (resource-server bearer
validation and the client auth-code + PKCE flow), identity-keyed rate
limiting, OpenTelemetry tracing + metrics, progress/logging, subscriptions,
response caching (SEP-2549), and bidirectional elicitation — each opt-in
behind a feature flag.
How this relates to rmcp, the official Rust SDK
rmcp is the official SDK,
maintained in the modelcontextprotocol organization. It is the reasonable
default, and this project is tested against it — cross-SDK interop tests run in
both directions, a TurboMCP client against an rmcp server and the reverse, on
every change, alongside the same matrix over HTTP against the official
TypeScript (v2), Python and Go SDKs.
TurboMCP's interoperability tests pin rmcp 3.5. TurboMCP serves three
revisions (2025-06-18, 2025-11-25, 2026-07-28) using separate generated
wire types and exhaustive conversions to a neutral handler API. It does not
serve 2024-11-05 or 2025-03-26.
The distinguishing APIs are macro-derived capabilities, typed per-RPC contexts,
composition, caller-specific visibility, and Tower middleware. Conformance and
interoperability are compatibility evidence; they do not establish performance