docs.rs failed to build turbomcp-proxy-3.1.3
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.
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
Universal Transport Support
- STDIO ↔ HTTP/SSE (bidirectional)
- HTTP ↔ STDIO (bidirectional)
- TCP (high-performance network)
- Unix Domain Sockets (IPC, high-security)
- WebSocket (browser-friendly, real-time)
- 25+ Transport Combinations (5 backends × 5 frontends)
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)
- API Key Authentication (configurable header)
- OAuth 2.1 Support (via turbomcp-auth integration)
- DPoP Token Binding (RFC 9449, optional)
- Command allowlist (prevents shell injection)
- SSRF protection (blocks private IPs, metadata endpoints)
- 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. Generate REST API from MCP Server
Problem: Want REST API with Swagger docs
# Generate and serve REST API
# Endpoints automatically created:
# POST /tools/{tool_name} → tools/call
# GET /resources/{uri} → resources/read
# GET /openapi.json → Auto-generated spec
# GET /docs → Swagger UI
4. Code Generation for Production
Problem: Need optimized binary for production deployment
# Generate standalone Rust project
# Deploy optimized binary (0ms overhead)
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 (Phase 6 - Scaffolded)
Expose MCP servers through standard web protocols. Adapter framework is ready for full implementation.
)
)
)
)
)
)
# REST API (framework ready)
# GraphQL API (framework ready)
Development Status
Current Version: 3.1.3 (tracks the TurboMCP workspace)
Status: Production-ready for STDIO/HTTP/TCP/Unix/WebSocket proxying,
code generation, and OpenAPI/GraphQL/Protobuf schema export. Protocol
adapters (adapter rest, adapter graphql) are scaffolded — see
"Protocol Adapters" below.
Transport Coverage:
- STDIO (subprocess, CLI tools)
- HTTP/SSE (web services, APIs)
- TCP (high-performance network)
- Unix Domain Sockets (IPC, same-host)
- WebSocket (real-time, browser-friendly)
- 25 Transport Combinations (5 backends × 5 frontends)
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
- Full REST adapter implementation — the
adapter restcommand structure is in place; end-to-end request routing and Swagger UI wiring are a work in progress. - 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