Mcp Oauth

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](./docs/mcp-2025-11-25.md) | | 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
• Access Token Formats - Opaque (default) or signed JWT (RFC 9068) with published JWKS for local validation by MCP-aware proxies
• 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/handler"
    "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
    h := handler.New(server, nil)
    mux := http.NewServeMux()

    h.RegisterProtectedResourceMetadataRoutes(mux, "/mcp")
    mux.Handle("/mcp", h.ValidateToken(yourMCPHandler))

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

Installation

go get github.com/giantswarm/mcp-oauth

Documentation

| Document | Description | |----------|-------------| | [Getting Started](./docs/getting-started.md) | Installation, providers, storage, first OAuth server | | [Configuration](./docs/configuration.md) | All configuration options, CORS, interstitial pages, proxy settings | | [Security Guide](./docs/security.md) | Security features, best practices, production checklist | | [Observability](./docs/observability.md) | OpenTelemetry, Prometheus metrics, distributed tracing | | [Discovery Mechanisms](./docs/discovery.md) | OAuth discovery (RFC 8414, RFC 9728) | | [MCP 2025-11-25](./docs/mcp-2025-11-25.md) | New specification features and migration | | [Silent Authentication](./docs/silent-authentication.md) | OIDC prompt parameter for seamless re-authentication | | [Client ID Metadata Documents](./docs/cimd.md) | URL-based client IDs with dynamic metadata discovery | | [DPoP (RFC 9449)](./docs/dpop.md) | Sender-constraint setup, middleware wiring, multi-pod replay cache | | [Token Exchange (RFC 8693)](./docs/token-exchange.md) | Service-to-service and Kubernetes SA token exchange | | [Client Management (RFC 7592)](./docs/client-management.md) | Per-client read/update/delete for dynamically registered clients | | [Security Architecture](./SECURITY_ARCHITECTURE.md) | Deep-dive into security implementation |

Examples

The [examples/](./examples) directory contains runnable examples:

• [basic](./examples/basic) - Minimal setup with Google
• [github](./examples/github) - GitHub OAuth with organization restriction
• [dex](./examples/dex) - Dex provider with connector_id and groups support
• [production](./examples/production) - Full security features
• [custom-scopes](./examples/custom-scopes) - Endpoint-specific scope requirements
• [mcp-2025-11-25](./examples/mcp-2025-11-25) - New MCP specification features
• [cimd](./examples/cimd) - Client ID Metadata Documents (URL-based client IDs)
• [prometheus](./examples/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](./examples/production/README.md#secret-management-required-for-production) for implementation guidance and examples.

Documentation

See the [Security Guide](./docs/security.md) for configuration and the [Security Architecture](./SECURITY_ARCHITECTURE.md) for implementation details.

Vulnerability Reporting: See [SECURITY.md](./SECURITY.md) for responsible disclosure.

Contributing

Contributions welcome. Especially:

• New provider implementations
• Storage backends
• Security enhancements

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

License

Apache License 2.0

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: giantswarm
• Source: giantswarm/mcp-oauth
• License: Apache-2.0
• Homepage: https://pkg.go.dev/github.com/giantswarm/mcp-oauth

Install and usage instructions live in the source repository linked above.