OAuth MCP proxy
OAuth 2.1 authentication library for Go MCP servers.
Supports both MCP SDKs:
- ✅
mark3labs/mcp-go - ✅
modelcontextprotocol/go-sdk(official)
One-time setup: Configure provider + add WithOAuth() to your server.
Result: All tools automatically protected with token validation and caching.
mark3labs/mcp-go
import "github.com/tuannvm/oauth-mcp-proxy/mark3labs"
oauthServer, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{
Provider: "okta",
Issuer: "https://your-company.okta.com",
Audience: "api://your-mcp-server",
})
mcpServer := server.NewMCPServer("Server", "1.0.0", oauthOption)
streamable := server.NewStreamableHTTPServer(mcpServer, /*options*/)
mux.HandleFunc("/mcp", oauthServer.WrapMCPEndpoint(streamable))
Official SDK
import mcpoauth "github.com/tuannvm/oauth-mcp-proxy/mcp"
mcpServer := mcp.NewServer(&mcp.Implementation{...}, nil)
_, handler, _ := mcpoauth.WithOAuth(mux, cfg, mcpServer)
http.ListenAndServe(":8080", handler)
Why Use This Library?
- Dual SDK support - Works with both mark3labs and official SDKs
- Simple integration - One
WithOAuth()call protects all tools - Automatic 401 handling - RFC 6750 compliant error responses with OAuth discovery
- Zero per-tool config - All tools automatically protected
- Fast token caching - 5-min cache with JWT expiry awareness
- Security hardened - State replay protection, DoS prevention, input validation
- Built-in rate limiting - Token-based rate limiter included
- CORS support - OPTIONS pass-through for browser clients
- Multiple providers - HMAC, Okta, Google, Azure AD
How It Works
Request Flow
sequenceDiagram
participant Client
participant MCP Server
box lightyellow oauth-mcp-proxy Library
participant Middleware
participant Cache
participant Provider
end
participant Your Tool Handler
Client->>MCP Server: Request + Bearer token
MCP Server->>Middleware: WithOAuth() intercepts
alt Token in cache and fresh
Middleware->>Cache: Check token hash
Cache-->>Middleware: Return cached user
else Token not cached or expired
Middleware->>Provider: Validate token (HMAC/OIDC)
Provider-->>Middleware: User claims
Middleware->>Cache: Store user for 5 minutes
end
Middleware->>Your Tool Handler: Pass request with user in context
Your Tool Handler->>Your Tool Handler: GetUserFromContext(ctx)
Your Tool Handler-->>Client: Send response
Token Validation Flow
flowchart TB
Start([Your MCP Server receives request]) --> Extract[oauth-mcp-proxy: Extract Token]
Extract --> Hash[oauth-mcp-proxy: SHA-256 Hash]
Hash --> CheckCache{oauth-mcp-proxy: Token Cached?}
CheckCache -->|Cache Hit| GetUser[oauth-mcp-proxy: Get Cached User]
CheckCache -->|Cache Miss| Validate{oauth-mcp-proxy: Validate}
Validate -->|Valid| Claims[oauth-mcp-proxy: Extract Claims]
Validate -->|Invalid| Reject([Return 401])
Claims --> Store[oauth-mcp-proxy: Cache]
Store --> GetUser
GetUser --> Context[oauth-mcp-proxy: Add User to Context]
Context --> Tool[Your Tool Handler: GetUserFromContext]
Tool --> Response([Your MCP Server: Return Response])
style Start fill:#e8f5e9
style Extract fill:#fff9c4
style Hash fill:#fff9c4
style CheckCache fill:#fff9c4
style Validate fill:#fff9c4
style Claims fill:#fff9c4
style Store fill:#fff9c4
style GetUser fill:#fff9c4
style Context fill:#fff9c4
style Tool fill:#e8f5e9
style Response fill:#e8f5e9
style Reject fill:#ffebee
What oauth-mcp-proxy does:
- Extracts Bearer tokens from HTTP requests
- Validates against your OAuth provider (with caching)
- Adds authenticated user to request context
- All your tools automatically protected
🔒 Security Features
Production-ready security hardening built-in:
State Replay Protection
- Timestamp + nonce validation - States include timestamp and nonce for replay attack prevention
- Automatic nonce cleanup - Expired nonces removed before replay check (prevents memory leaks)
- Rolling deploy compatible - Accepts legacy states without timestamp/nonce for zero-downtime upgrades
Token Security
- JWT expiry-aware caching - Cache respects token expiration time (uses min(token.expiry, now+5min))
- Constant-time HMAC comparison - Timing attack prevention for signature verification
- Secure nonce generation - Panics on crypto/rand failure (no weak fallback)
Input Validation & DoS Prevention
- Parameter length limits - code, state, code_challenge validated to prevent abuse
- Request body size limits - MaxBytesReader on token endpoint (1MB), registration (256KB)
- Issuer URL validation - Enforced HTTPS for non-localhost OIDC providers
Session Management (Official SDK)
- auth.TokenInfo population - Populates go-sdk auth context for session binding
- User-based session tracking - Prevents session hijacking via user ID verification
HTTP Security
- Security headers - CSP, X-Frame-Options, X-Content-Type-Options, Cache-Control
- CORS support - OPTIONS pass-through for browser clients
- RFC 6750 compliant - Proper WWW-Authenticate headers with resource_metadata
Built-in Rate Limiting
// Simple token-based rate limiter included
limiter := oauth.NewRateLimiter(time.Minute, 100)
if !limiter.Allow("client-ip") {
http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
}
Breaking Changes (Security Hardening)
v1.0.0 → v1.1.0
The following security improvements introduce breaking changes:
1. Issuer URL Validation (CRITICAL)
- Change: OIDC providers now enforce HTTPS validation for issuer URLs
- Impact: Invalid issuer URLs will cause
NewServer()to fail - Migration: Ensure your
Issuerconfig uses HTTPS (or localhost for testing)// ✅ Valid Issuer: "https://company.okta.com" Issuer: "http://localhost:8080" // Testing only // ❌ Invalid - will fail validation Issuer: "http://company.okta.com" // Not localhost Issuer: "company.okta.com" // Missing scheme
2. State Signing Key Initialization
- Change:
NewServer()now panics if state signing key cannot be generated - Impact: Server startup will fail if crypto/rand fails (should never happen on healthy systems)
- Migration: Ensure your system has a working CSPRNG. No code changes needed.
3. Nonce Generation Failure Behavior
- Change:
generateSecureNonce()now panics instead of falling back to weak timestamp-based nonces - Impact: OAuth authorization requests will fail if crypto/rand fails
- Migration: Ensure your system has a working CSPRNG. No code changes needed.
4. Error Message Simplification
- Change: Security-sensitive error messages are less verbose to prevent information leakage
- Impact: Debugging authentication failures may require checking logs
- Migration: Use server logs for detailed debugging; client errors are intentionally generic
No Migration Needed For
- Token cache expiry fix - Fully backwards compatible
- State replay protection - Legacy states without timestamp/nonce still accepted
- Input validation - Only affects malformed requests
- go-sdk adapter fixes - Fully backwards compatible
Quick Start
Using mark3labs/mcp-go
1. Install
go get github.com/tuannvm/oauth-mcp-proxy
2. Add to Your Server
import (
oauth "github.com/tuannvm/oauth-mcp-proxy"
"github.com/tuannvm/oauth-mcp-proxy/mark3labs"
)
mux := http.NewServeMux()
// Enable OAuth (one time setup)
oauthServer, oauthOption, _ := mark3labs.WithOAuth(mux, &oauth.Config{
Provider: "okta", // or "hmac", "google", "azure"
Issuer: "https://your-company.okta.com",
Audience: "api://your-mcp-server",
ServerURL: "https://your-server.com",
})
// Create MCP server with OAuth
mcpServer := mcpserver.NewMCPServer("Server", "1.0.0", oauthOption)
// Add tools - all automatically protected
mcpServer.AddTool(myTool, myHandler)
// Setup endpoint with automatic 401 handling
streamable := mcpserver.NewStreamableHTTPServer(
mcpServer,
mcpserver.WithHTTPContextFunc(oauth.CreateHTTPContextFunc()),
)
mux.HandleFunc("/mcp", oauthServer.WrapMCPEndpoint(streamable))
3. Access Authenticated User
func myHandler(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
user, ok := oauth.GetUserFromContext(ctx)
if !ok {
return nil, fmt.Errorf("authentication required")
}
// Use user.Username, user.Email, user.Subject
}
Using Official SDK
1. Install
go get github.com/modelcontextprotocol/go-sdk
go get github.com/tuannvm/oauth-mcp-proxy
2. Add to Your Server
import (
"github.com/modelcontextprotocol/go-sdk/mcp"
oauth "github.com/tuannvm/oauth-mcp-proxy"
mcpoauth "github.com/tuannvm/oauth-mcp-proxy/mcp"
)
mux := http.NewServeMux()
// Create MCP server
mcpServer := mcp.NewServer(&mcp.Implementation{
Name: "my-server",
Version: "1.0.0",
}, nil)
// Add tools
mcp.AddTool(mcpServer, &mcp.Tool{
Name: "greet",
Description: "Greet user",
}, func(ctx context.Context, req *mcp.CallToolRequest, params *struct{}) (*mcp.CallToolResult, any, error) {
user, _ := oauth.GetUserFromContext(ctx)
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: "Hello, " + user.Username},
},
}, nil, nil
})
// Add OAuth protection
_, handler, _ := mcpoauth.WithOAuth(mux, &oauth.Config{
Provider: "okta",
Issuer: "https://your-company.okta.com",
Audience: "api://your-mcp-server",
}, mcpServer)
http.ListenAndServe(":8080", handler)
Your MCP server now requires OAuth authentication.
Examples
See examples/README.md for detailed setup guide including Okta configuration.
Supported Providers
Documentation
Getting Started:
- Setup Guide - Complete server integration and client configuration
- Configuration Guide - All config options
- Provider Setup - OAuth provider guides
Advanced:
- Security Guide - Production best practices
- Troubleshooting - Common issues
License
MIT License - See LICENSE
