Epistates/TurboMCP

TurboMCP 2.1.0 represents a major enhancement of the authentication and interoperability capabilities of the framework. This release introduces:

• ** turbomcp-proxy**: Universal MCP adapter/generator with introspection and code generation for ANY MCP server
• ** Complete OAuth 2.1 Stack**: PKCE, multi-provider support, JWT/JWKS, RFC 9728 helpers
• 5 RFC Implementations: RFC 7636, 7591, 8707, 9728, 9449
• 1,165+ Tests: 100% pass rate with comprehensive coverage
• Zero Breaking Changes: Drop-in replacement for 2.0.5

Major Features

1. turbomcp-proxy (NEW CRATE) 🆕

A production-grade universal MCP adapter that works with ANY MCP server implementation (TurboMCP, Python SDK, TypeScript SDK, or custom).

Capabilities

• Multi-Transport Proxying: 25 backend×frontend combinations

  • Backends: STDIO, HTTP, TCP, Unix Domain Sockets, WebSocket
  • Frontends: STDIO, HTTP, TCP, Unix Domain Sockets, WebSocket
  • All validated with 40+ integration tests

• CLI Commands:

  • inspect - Discover server capabilities
  • serve - Runtime proxy with transport conversion
  • generate - Generate optimized Rust proxy code
  • schema - Export OpenAPI/JSON schemas

• Authentication:

  • JWT with symmetric (secret) and asymmetric (JWKS) support
  • JWKS caching with key rotation
  • OAuth provider integration
  • Backend authentication headers

• Code Generation:

  • Type-safe Rust client code generation
  • Cargo project template generation
  • OpenAPI schema export

Files

• 43 source files implementing proxy, CLI, introspection, code generation
• 541-line comprehensive README
• 3 production examples (runtime_proxy.rs + benchmarks)
• 40+ integration tests covering all transport combinations

Example

# Inspect any MCP server
turbomcp-proxy inspect stdio --cmd "python my-server.py"

# Expose STDIO server over HTTP with JWT auth
turbomcp-proxy serve \
  --backend stdio --cmd "python my-server.py" \
  --frontend http --bind 0.0.0.0:3000 \
  --jwt-secret "your-secret-key" \
  --jwt-algorithm HS256

# Generate optimized Rust proxy
turbomcp-proxy generate \
  --backend stdio --cmd "python my-server.py" \
  --frontend http \
  --output ./my-proxy \
  --build --run

2. Complete OAuth 2.1 Authentication Stack 🔐

New Modules

• context.rs (991 lines) - AuthContext for request-scoped authentication
• introspection.rs (352 lines) - Token introspection endpoints
• jwt/mod.rs (86 lines) - JWT module coordination
• jwt/jwks.rs (417 lines) - JWKS caching & validation with TTL
• jwt/validator.rs (483 lines) - Token validation logic with claims extraction
• oauth2/dcr.rs (564 lines) - Dynamic Client Registration (RFC 7591)
• oauth2/resource.rs (295 lines) - Resource indicators (RFC 8707)
• oauth2/providers/oauth2.rs (295 lines) - OAuth2Provider implementation
• server.rs (460 lines) - RFC 9728 Protected Resource Metadata helpers

OAuth2Client Features

Authorization Code Flow with PKCE

let config = OAuth2Config {
    client_id: "my-client".to_string(),
    client_secret: "secret".to_string(),
    auth_url: "https://provider.example.com/oauth/authorize".to_string(),
    token_url: "https://provider.example.com/oauth/token".to_string(),
    redirect_uri: "http://localhost:8080/callback".to_string(),
    scopes: vec!["openid".to_string(), "profile".to_string()],
    flow_type: OAuth2FlowType::AuthorizationCode,
    ..Default::default()
};

let client = OAuth2Client::new(&config, ProviderType::Google)?;
let (auth_url, pkce_verifier) = client.authorization_code_flow()?;
// Redirect user to auth_url...
let token = client.exchange_code_for_token(auth_code, pkce_verifier).await?;

Token Refresh

let new_token = client.refresh_access_token(&token.refresh_token).await?;

Client Credentials Flow (Server-to-Server)

let token = client.client_credentials_flow(&["api:read", "api:write"]).await?;

OAuth2Provider (Full AuthProvider Implementation)

• Token validation via userinfo endpoints
• Token caching (5-minute default) for performance
• Refresh token handling
• Automatic userinfo parsing for Google, GitHub, Microsoft, GitLab

RFC 9728 Server-Side Helpers

ProtectedResourceMetadataBuilder

let metadata = ProtectedResourceMetadataBuilder::new()
    .add_scope("api:read")
    .add_scope("api:write")
    .add_bearer_method(BearerMethod::Header)
    .build();

WwwAuthenticateBuilder

let response = WwwAuthenticateBuilder::new()
    .add_scope("api:read")
    .add_error("invalid_token")
    .build();

BearerTokenValidator

let token = BearerTokenValidator::extract_from_header(&auth_header)?;

Multi-Provider Support

• Google OAuth 2.0
• GitHub OAuth 2.0
• Microsoft OAuth 2.0
• GitLab OAuth 2.0
• Generic OAuth 2.1

3. JWT & JWKS Support 🔑

JWT Module Features:

• Token signing with configurable algorithms
• Token validation with claims extraction
• JWKS caching with TTL support
• Key rotation support
• Provider introspection integration

JWKS Middleware:

• 503 lines of production-grade JWKS caching
• Automatic key rotation
• TTL-based cache management
• Token validation pipeline
• Multi-provider support

4. DPoP Enhancements 🚀

New Helpers Module (461 lines)

• DPoP proof generation utilities
• Signature validation helpers
• Integration patterns with OAuth2

Type Enhancements (143 lines)

• Improved DPoP types
• Provider-specific configurations
• Algorithm selection helpers

Proof Generation Refactoring (523 lines)

• Improved algorithm support
• Enhanced replay attack prevention
• HSM integration refinements

5. Transport & Middleware Enhancements 📡

Auth Router (228 lines)

• OAuth2 authorization endpoints
• Token validation middleware
• JWT signing and verification
• JWKS endpoint support

JWKS Middleware (503 lines)

• JSON Web Key Set caching
• Key rotation support
• Token validation
• Provider introspection
• TTL-based cache management

Enhanced Auth Middleware (474 lines)

• Improved bearer token handling
• JWT validation pipeline
• Multi-provider support
• Context injection
• Enhanced error messages

📊 RFC Compliance Matrix

| RFC | Title | Status | Implementation |
|-----|-------|--------|-----------------|
| 7636 | PKCE | ✅ Complete | Authorization Code Flow with automatic challenge/verifier generation |
| 7591 | DCR | ✅ Complete | Dynamic Client Registration for OAuth providers |
| 8707 | Resource Indicators | ✅ Complete | Canonical URI validation for MCP resources |
| 9728 | Protected Resource Metadata | ✅ Complete | Server-side helpers (ProtectedResourceMetadataBuilder, WwwAuthenticateBuilder) |
| 9449 | DPoP | ✅ Complete | Proof-of-Possession implementation with HSM support |

Zero Breaking Changes ✅

• All existing 2.0.5 APIs remain unchanged
• All new features are purely additive
• Existing authentication methods still work
• All transports remain compatible
• Drop-in replacement for 2.0.5

Migration Required: NONE

Simply upgrade the version in Cargo.toml:

# Before
turbomcp = "2.0.5"

# After
turbomcp = "2.1"

All code continues to work unchanged.

🔐 Security Enhancements

New Security Features

• ✅ OAuth 2.1 PKCE support preventing authorization code interception
• ✅ JWT JWKS validation with cache security
• ✅ Bearer token validation with structured error messages
• ✅ RFC 9728 compliant protected resource metadata
• ✅ DPoP proof-of-possession binding preventing token theft
• ✅ Security attack scenario testing included

Security Testing

• 7 test suites with security-specific scenarios
• Attack vector testing (injection, traversal, CSRF)
• Token lifecycle security verification
• JWKS caching robustness testing
• Multi-provider security scenarios

Vulnerability Status

• ✅ Zero known runtime vulnerabilities
• ✅ Same excellent security posture as 2.0.5
• ✅ Enhanced with additional RFC compliance

⚡ Performance Optimizations

Binary Size Reduction

• Selective tokio features reduce binary by 5-10MB
• No functionality loss
• All 244 unit tests pass with optimized features

Caching Improvements

• JWKS Caching: TTL-based with automatic key rotation
• Token Caching: 5-minute default for performance
• Auth Context: Request-scoped token management

Compile-Time Optimization

• Zero-cost compile-time dispatch in proxy (dispatch_client! macro)
• Type erasure for efficient runtime dispatch
• 100% safe Rust (zero unsafe code)

📚 Documentation

README Updates

• Main README.md: Updated with 2.1.0 features
• crates/turbomcp/README.md: Version refs updated
• crates/turbomcp-client/README.md: OAuth 2.1 support highlighted
• crates/turbomcp-auth/README.md: NEW - 184 lines comprehensive guide
• crates/turbomcp-proxy/README.md: NEW - 541 lines complete guide
• crates/turbomcp-dpop/README.md: Updated with helpers documentation

Examples

• oauth2_auth_code_flow.rs (85 lines) - Complete OAuth2.1 client flow
• protected_resource_server.rs (130 lines) - RFC 9728 server implementation
• runtime_proxy.rs (124 lines) - Proxy usage example
• 2 benchmark suites (introspection, runtime_proxy)

CHANGELOG

• 144 lines of comprehensive release information
• All major features documented
• RFC compliance matrix included
• Test coverage listed
• Migration path provided

🚀 Getting Started with New Features

Using turbomcp-proxy

# Add to Cargo.toml
turbomcp-proxy = "2.1"

# Or use as CLI
cargo install turbomcp-proxy

# Inspect a server
turbomcp-proxy inspect stdio --cmd "my-server"

# Serve with JWT auth
turbomcp-proxy serve \
  --backend stdio --cmd "my-server" \
  --frontend http --bind 0.0.0.0:3000 \
  --jwt-secret "secret" \
  --jwt-algorithm HS256

Using OAuth 2.1 Authentication

use turbomcp_auth::{OAuth2Client, config::OAuth2Config};

// Create config
let config = OAuth2Config {
    client_id: "my-client".to_string(),
    client_secret: "secret".to_string(),
    auth_url: "https://accounts.google.com/o/oauth2/v2/auth".to_string(),
    token_url: "https://oauth2.googleapis.com/token".to_string(),
    redirect_uri: "http://localhost:8080/callback".to_string(),
    scopes: vec!["openid".to_string(), "profile".to_string()],
    ..Default::default()
};

// Use OAuth2 flows
let client = OAuth2Client::new(&config, ProviderType::Google)?;
let token = client.authorization_code_flow().await?;

Using JWT/JWKS Validation

use turbomcp_auth::jwt::JwtValidator;

let validator = JwtValidator::new("https://provider.example.com/.well-known/jwks.json")?;
let claims = validator.validate_token(&token).await?;

📋 Installation & Upgrade

Fresh Installation

[dependencies]
turbomcp = "2.1"
turbomcp-auth = "2.1"  # Optional: OAuth 2.1 authentication
turbomcp-proxy = "2.1" # Optional: Universal MCP proxy
turbomcp-dpop = "2.1"  # Optional: DPoP proof-of-possession

Upgrading from 2.0.5

cargo update turbomcp
cargo test  # All existing tests should pass unchanged

No code changes required! All new features are opt-in.

🔄 Migration Guide

For 2.0.5 Users

No migration needed! Simply update your dependencies:

# Before
turbomcp = "2.0.5"

# After
turbomcp = "2.1"

All your code continues to work exactly as before.

To Use New Features (Optional)

If you want to use the new features:

1. OAuth 2.1: Add turbomcp-auth dependency
2. Universal Proxy: Add turbomcp-proxy dependency
3. DPoP: Add turbomcp-dpop feature flag

🎯 Known Issues & Limitations

None Identified ✅

• No known bugs
• No known regressions
• All 1,165+ tests passing
• Zero clippy warnings

📞 Support & Resources

Documentation

• Main README
• turbomcp-auth README
• turbomcp-proxy README
• API Docs

Examples

• OAuth2 Authorization Code Flow: crates/turbomcp-auth/examples/oauth2_auth_code_flow.rs
• Protected Resource Server: crates/turbomcp-auth/examples/protected_resource_server.rs
• Proxy Runtime: crates/turbomcp-proxy/examples/runtime_proxy.rs

Issues & Contributions

• GitHub Issues
• GitHub Discussions