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

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

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