Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
turbomcp-proxy
Universal MCP Adapter/Generator - Introspection, proxying, and code generation for any MCP server
turbomcp-proxy is a universal tool that works with ANY MCP server implementation (TurboMCP, Python SDK, TypeScript SDK, custom implementations). It discovers server capabilities via the MCP protocol and dynamically generates adapters for different transports and protocols.
Quick Start
# Inspect any MCP server
# Expose STDIO server over HTTP/SSE (development)
# Connect to TCP server and expose over HTTP
# Connect to Unix socket and expose over HTTP
# Expose with JWT authentication (production - symmetric)
# Expose with JWKS (production - asymmetric, OAuth providers)
# Generate optimized Rust proxy
# Export OpenAPI 3.1 schema
# Export GraphQL schema
# Export Protobuf definition
Features
Universal Compatibility
Works with any MCP implementation:
- TurboMCP (Rust)
- Python SDK
- TypeScript SDK
- Custom implementations
Introspection-Based
- Zero configuration - discovers capabilities automatically
- Extracts tools, resources, prompts with JSON schemas
- Caches results for fast repeated use
Multiple Modes
- Runtime Mode: Fast prototyping, no compilation needed
- Codegen Mode: Production binaries with 0ms overhead
- Schema Mode: Export OpenAPI, GraphQL, Protobuf
Transport Support
- Backends: STDIO (subprocess), Streamable HTTP, TCP, Unix domain sockets, WebSocket
- Frontends: Streamable HTTP and STDIO (
serve), plus WebSocket throughRuntimeProxy
Every frontend serves the same ProxyService through turbomcp-server's own
transports, so the handshake, protocol-version negotiation (2025-06-18 and
2025-11-25), ping, and notifications behave exactly as they do for any
TurboMCP server.
What the proxy relays
The proxy forwards tools/call, resources/read, and prompts/get to the
upstream and serves the upstream's catalogue (tools, resources, resource
templates, prompts, with icons, _meta, and annotations intact) from what it
discovered at startup. Upstream errors come back unchanged, data included.
It does not relay traffic the upstream originates: sampling and
elicitation requests, log messages, progress, and list_changed /
resources/updated notifications. It therefore advertises only the tools,
resources, and prompts capabilities, with no listChanged or subscribe,
and no logging or completions. A catalogue change upstream takes a proxy
restart to show.
Authentication & Security
- JWT Authentication (RFC 7519 validation)
- Symmetric algorithms: HS256, HS384, HS512
- Asymmetric algorithms: RS256, RS384, RS512, ES256, ES384
- JWKS support for OAuth providers (Google, GitHub, Auth0, etc.)
- Automatic key caching with TTL
- Claims validation (exp, nbf, iat, iss, aud)
- Clock skew tolerance (60s default)
- An audience is required:
--jwt-secretrefuses to start without--jwt-audience - RFC 9728 protected-resource metadata: when the first audience is the
proxy's own
https://URL and an issuer is anhttps://URL, the proxy serves the metadata and its 401s point at it (resource_metadata)
- API Key Authentication (configurable header)
- Command allowlist (prevents shell injection)
- SSRF protection (blocks private, CGNAT, and metadata addresses in every spelling, including IPv4-mapped and NAT64 IPv6)
- Path traversal protection (canonical path resolution)
- Auth token security (automatic secret zeroization)
- Request limiting (DoS protection, 10 MB default)
- Timeout enforcement (prevents hanging requests)
Use Cases
1. Expose STDIO Server Over HTTP (Most Common Use Case)
Problem: You have a CLI MCP server, but need HTTP clients to access it
# Your CLI server
# Expose it over HTTP (development)
# Expose with JWT authentication (production)
# Expose with API key authentication (production)
# Now accessible via HTTP
2. Connect to HTTP Server from STDIO Client
Problem: Your tool expects STDIO, but server is HTTP
# Connect to HTTP server, expose as STDIO
|
# With backend authentication (Bearer token for HTTP backend)
3. Serve an MCP Server as a REST API
Problem: Want plain HTTP/JSON endpoints for an MCP server (requires the
rest feature: cargo install turbomcp-proxy --features rest)
# Endpoints:
# GET /api/tools → the tool catalogue
# POST /api/tools/{name} → tools/call, JSON body = arguments
# GET /api/resources → the resource catalogue
# GET /api/resources/{uri} → resources/read (the rest of the path is the URI)
# GET /api/prompts → the prompt catalogue
# POST /api/prompts/{name} → prompts/get
# GET /openapi.json → a minimal OpenAPI description
# GET /health
4. Code Generation for Production
Problem: Need optimized binary for production deployment
# Generate standalone Rust project
# Run it: the upstream command comes from the environment
BACKEND_CMD=python BACKEND_ARGS=my-server.py \
The generated crate is an ordinary TurboMCP server: ProxyRouter implements
McpHandler and is served by turbomcp-server's stdio, Streamable HTTP, or
WebSocket transport (--frontend). It routes the tools and prompts it was
generated for by their upstream names, fetches the upstream's catalogue at
startup, and logs to stderr. BIND_ADDR sets the listen address for the HTTP
and WebSocket frontends; BACKEND_WORKING_DIR sets the upstream's working
directory. Generation currently supports STDIO backends only.
Architecture
┌─────────────────────────────────────────────────────────┐
│ Introspection Layer │
│ • McpIntrospector: Discovers server capabilities │
│ • ServerSpec: Complete server description │
│ • Backends: STDIO, HTTP, WebSocket │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Generation Layer │
│ • RuntimeProxyBuilder: Dynamic, no codegen │
│ • RustCodeGenerator: Optimized Rust source │
│ • Schema Generators: OpenAPI, GraphQL, Protobuf │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Adapter Layer │
│ • Transport Adapters: STDIO ↔ HTTP/SSE ↔ WebSocket │
│ • Protocol Adapters: MCP → REST API / GraphQL │
└─────────────────────────────────────────────────────────┘
Installation
From crates.io:
From source:
Documentation
CLI Reference
Commands
turbomcp-proxy <COMMAND> [OPTIONS]
Commands:
inspect Discover MCP server capabilities
serve Run runtime proxy (no codegen)
generate Generate optimized proxy source code
schema Export schemas (OpenAPI, GraphQL, Protobuf)
adapter Run protocol adapter (MCP → REST/GraphQL)
help Print help
inspect - Discover Capabilities
)
)
)
)
)
)
()
serve - Runtime Proxy
)
)
)
)
)
)
)
)
)
)
)
)
)
)
; )
)
)
# STDIO → HTTP (development, localhost only)
# STDIO → HTTP with JWT authentication (production)
# STDIO → HTTP with API key authentication (production)
# HTTP → STDIO with backend authentication
# TCP → HTTP (high-performance network)
# Unix socket → HTTP (IPC security)
generate - Code Generation
)
)
)
)
)
)
)
)
)
)
)
)
)
# Generate and build
schema - Schema Export
Export MCP server capabilities as standard schema formats.
)
)
)
)
)
)
# Export OpenAPI from STDIO server
# Export GraphQL from TCP server
# Export Protobuf from Unix socket
# Export to stdout
adapter - Protocol Adapters
Expose MCP servers through standard web protocols. rest needs the rest
feature; graphql is not implemented and returns an error.
)
)
)
)
;
Development Status
Current Version: 3.5.0 (tracks the TurboMCP workspace) Transport Coverage:
- Backends: STDIO, Streamable HTTP, TCP, Unix domain sockets, WebSocket
- Frontends: Streamable HTTP, STDIO, WebSocket (
RuntimeProxy) - TCP / Unix frontends:
TcpFrontendandUnixFrontendaccept connections but do not route requests yet
Authentication & Security:
- JWT Authentication (RFC 7519, symmetric and JWKS validation)
- API Key Authentication (configurable header and key)
- Environment Variable Support (TURBOMCP_JWT_SECRET)
- Security Warnings (alerts when binding publicly without auth)
- Command Allowlist (prevents shell injection)
- SSRF Protection (blocks private IPs, metadata endpoints)
- Path Traversal Protection (canonical path resolution)
- Auth Token Security (automatic secret zeroization)
Quality Assurance:
- 40+ Comprehensive Tests (transport combinations, security validations)
- Security-Focused Regression Coverage
- Zero TODO Markers (production-ready)
- 100% Safe Rust (no unsafe code)
Core Components:
- BackendConnector: Supports 5 transport types with type-erased enum dispatch
- ProxyService:
turbomcp-serverhandler for Streamable HTTP integration - IdTranslator: Bidirectional message ID mapping for session correlation
- Introspection: Complete server capability discovery (tools, resources, prompts)
- RuntimeProxyBuilder: Security-first builder with comprehensive validation
- Authentication: JWT and API key support in the proxy frontend
What's not done yet
- Server-to-client relay — sampling, elicitation, logging, progress, and change notifications from the upstream are not forwarded (see "What the proxy relays").
- Per-user backend identity — the frontend credential is checked, but
every client shares one backend connection that authenticates as the proxy
(
--auth-token).JwtSignerexists as a building block and is not wired intoserve. - Swagger UI for the REST adapter —
--openapi-uiis accepted but serves nothing yet. - Full GraphQL adapter — scaffolded behind the
graphqlfeature flag; noasync-graphqldependency is pinned yet, so the feature on its own does not produce a working adapter. - Inspect over non-STDIO backends — the
inspectcommand rejects HTTP, TCP, Unix, and WebSocket today. Useschema(which does support all backends) if you need introspection output over those transports.
Contributing
Contributions welcome through the top-level TurboMCP repository.
License
Licensed under MIT.
Why turbomcp-proxy?
Problem
MCP servers are often CLI tools (STDIO), but clients need network access (HTTP). Manually bridging this gap requires:
- Writing transport code
- Handling sessions
- Mapping message IDs
- Writing schemas/docs
Solution
turbomcp-proxy does this automatically via introspection:
- Connect to any MCP server
- Discover capabilities via protocol
- Generate adapters dynamically or statically
- Expose over any transport/protocol
Result: Zero-configuration, universal MCP adapter that works with any implementation.
Built by the TurboMCP team