convez.ai
MCP ServerSegurançaAvançado
giantswarm

MCP OAuth 2.1 Authorization Server

giantswarm/mcp-oauth

OAuth 2.1 agnóstico para servidores MCP com segurança e observabilidade

Ver no GitHub
BomPluginScore · de 0 a 100

Biblioteca agnóstica de provedores para implementar OAuth 2.1 em servidores MCP (Model Context Protocol), com suporte a Google, GitHub, Dex e provedores customizados. Oferece armazenamento abstrato, PKCE enforcement, rotação de refresh tokens e integração OpenTelemetry para observabilidade.

Instalação

$npx convez-ai giantswarm/mcp-oauth

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
17
Forks
3
Acompanhando
0
Saúde
87%
Último commit
há 1 dia
Versão
v1.14.2
Issues abertas
10
Contribuidores
11

Casos de uso

  • Proteger endpoints MCP com autenticação OAuth 2.1
  • Integrar múltiplos provedores de identidade em aplicações MCP
  • Implementar fluxos silenciosos de autenticação OIDC
  • Monitorar sessões e tokens com OpenTelemetry

Veredito

Solução robusta e bem-documentada para autorização em servidores MCP, com conformidade completa à especificação 2025-11-25. Recomendada para sistemas que exigem OAuth 2.1 seguro com múltiplos provedores e observabilidade em produção.

README

A tradução para o português deste README ainda está na fila.

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 VersionSupport StatusDocumentation
2025-11-25Full SupportMigration Guide
2025-06-18 (previous)Full SupportBackward 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

DocumentDescription
Getting StartedInstallation, providers, storage, first OAuth server
ConfigurationAll configuration options, CORS, interstitial pages, proxy settings
Security GuideSecurity features, best practices, production checklist
ObservabilityOpenTelemetry, Prometheus metrics, distributed tracing
Discovery MechanismsOAuth discovery (RFC 8414, RFC 9728)
MCP 2025-11-25New specification features and migration
Silent AuthenticationOIDC prompt parameter for seamless re-authentication
Client ID Metadata DocumentsURL-based client IDs with dynamic metadata discovery
DPoP (RFC 9449)Sender-constraint setup, middleware wiring, multi-pod replay cache
Token Exchange (RFC 8693)Service-to-service and Kubernetes SA token exchange
Client Management (RFC 7592)Per-client read/update/delete for dynamically registered clients
Security ArchitectureDeep-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

Ver o original no GitHub

Bom para

Relacionados