mcp-oauth

A provider-agnostic OAuth 2.1 Authorization Server library for Model Context Protocol (MCP) servers, with support for multiple identity providers.

MCP Specification Compliance

Specification Version	Support Status	Documentation
2025-11-25	Full Support	Migration Guide
2025-06-18 (previous)	Full Support	Backward compatible

Key Features

• Provider Abstraction - Google, GitHub, and Dex OAuth built-in, easy to add custom providers
• Storage Abstraction - In-memory storage included, simple interface for custom backends
• OAuth 2.1 Security - PKCE enforcement, refresh token rotation, secure defaults
• MCP 2025-11-25 - Protected Resource Metadata (RFC 9728), scope discovery, resource binding
• Silent Authentication - OIDC prompt parameter support for seamless token refresh without user interaction
• Client ID Metadata Documents - URL-based client IDs with dynamic metadata discovery
• Lifecycle Callbacks - Session creation, revocation, and token refresh event hooks
• Observability - OpenTelemetry instrumentation with Prometheus and OTLP support

Architecture

┌─────────────────┐
│   Your MCP App  │
└────────┬────────┘
         │
    ┌────▼─────┐
    │ Handler  │  HTTP layer
    └────┬─────┘
         │
    ┌────▼─────┐
    │  Server  │  Business logic
    └──┬───┬───┘
       │   │
   ┌───▼┐ ┌▼────────┐
   │Pro-│ │ Storage │
   │vider│ │         │
   └────┘ └─────────┘

• Handler: HTTP request/response handling
• Server: OAuth business logic (provider-agnostic)
• Provider: Identity provider integration (Google, GitHub, Dex, or custom)
• Storage: Token/client/flow persistence

Quick Start

package main

import (
    "net/http"
    "os"

    oauth "github.com/giantswarm/mcp-oauth"
    "github.com/giantswarm/mcp-oauth/providers/google"
    "github.com/giantswarm/mcp-oauth/storage/memory"
)

func main() {
    // 1. Choose a provider
    provider, _ := google.NewProvider(&google.Config{
        ClientID:     os.Getenv("GOOGLE_CLIENT_ID"),
        ClientSecret: os.Getenv("GOOGLE_CLIENT_SECRET"),
        RedirectURL:  "http://localhost:8080/oauth/callback",
        Scopes:       []string{"openid", "email", "profile"},
    })

    // 2. Choose storage
    store := memory.New()
    defer store.Stop()

    // 3. Create OAuth server
    server, _ := oauth.NewServer(
        provider,
        store, // TokenStore
        store, // ClientStore
        store, // FlowStore
        &oauth.ServerConfig{
            Issuer: "http://localhost:8080",
        },
        nil,
    )

    // 4. Create HTTP handler and routes
    handler := oauth.NewHandler(server, nil)
    mux := http.NewServeMux()
    
    handler.RegisterProtectedResourceMetadataRoutes(mux, "/mcp")
    mux.Handle("/mcp", handler.ValidateToken(yourMCPHandler))

    http.ListenAndServe(":8080", mux)
}

Installation

go get github.com/giantswarm/mcp-oauth

Documentation

Document	Description
Getting Started	Installation, providers, storage, first OAuth server
Configuration	All configuration options, CORS, interstitial pages, proxy settings
Security Guide	Security features, best practices, production checklist
Observability	OpenTelemetry, Prometheus metrics, distributed tracing
Discovery Mechanisms	OAuth discovery (RFC 8414, RFC 9728)
MCP 2025-11-25	New specification features and migration
Silent Authentication	OIDC prompt parameter for seamless re-authentication
Client ID Metadata Documents	URL-based client IDs with dynamic metadata discovery
Security Architecture	Deep-dive into security implementation

Examples

The examples/ directory contains runnable examples:

• basic - Minimal setup with Google
• github - GitHub OAuth with organization restriction
• dex - Dex provider with connector_id and groups support
• production - Full security features
• custom-scopes - Endpoint-specific scope requirements
• mcp-2025-11-25 - New MCP specification features
• cimd - Client ID Metadata Documents (URL-based client IDs)
• prometheus - Observability integration

Security

This library implements OAuth 2.1 with secure defaults:

• PKCE required (S256 only)
• Refresh token rotation with reuse detection
• Token encryption at rest (AES-256-GCM)
• Rate limiting and audit logging

Secret Management (CRITICAL for Production)

NEVER use environment variables for production secrets!

Production deployments MUST use a secret manager:

• HashiCorp Vault (recommended for Kubernetes)
• AWS Secrets Manager (for AWS deployments)
• Google Cloud Secret Manager (for GCP deployments)
• Azure Key Vault (for Azure deployments)

NEVER:

• Use environment variables for secrets in production
• Hardcode secrets in code or configuration files
• Commit secrets to version control
• Store secrets in container images or Dockerfiles

See Production Example - Secret Management for implementation guidance and examples.

Documentation

See the Security Guide for configuration and the Security Architecture for implementation details.

Vulnerability Reporting: See SECURITY.md for responsible disclosure.

Contributing

Contributions welcome. Especially:

• New provider implementations
• Storage backends
• Security enhancements

See CONTRIBUTING.md for guidelines.

License

Apache License 2.0