MCP Gateway

Una pasarela agregadora de MCP ligera y autoalojada: un único endpoint público de MCP delante de cualquier número de servidores MCP backend protegidos, con un servidor de autorización OAuth 2.1 conforme a la especificación y orientado al cliente MCP — la pieza que falta en la mayoría de las pasarelas existentes.

Claude Code / Claude.ai ──OAuth 2.1 (DCR/CIMD + PKCE)──▶ MCP Gateway ──own credentials──▶ GitHub MCP
                                                          │                              ▶ Microsoft Learn MCP
                                                          └── /mcp (Streamable HTTP)      ▶ …more backends

Construida con FastAPI + FastMCP, configurada mediante un único archivo YAML, guarda su estado en una única base de datos SQLite cifrada y se distribuye como un pequeño contenedor autónomo — no requiere un proxy inverso, aunque puedes poner uno delante de ella para TLS.

Características

De cara al cliente (especificación de autorización MCP, 2025-11-25):

• Flujo de código de autorización OAuth 2.1 con PKCE (S256) obligatorio

• Registro Dinámico de Clientes (RFC 7591) en /register — claude mcp add funciona sin credenciales precompartidas

• Documento de Metadatos del ID de Cliente (CIMD) — URLs HTTPS como identificadores de cliente, incluida la autenticación de cliente private_key_jwt, anunciada mediante client_id_metadata_document_supported: true

• Metadatos del Servidor de Autorización (RFC 8414) y alias de descubrimiento OIDC

• Metadatos de Recurso Protegido (RFC 9728); las respuestas 401 incluyen WWW-Authenticate: Bearer resource_metadata="…" como exige el conector de Claude

• Indicadores de recurso (RFC 8707) aceptados y vinculados a los tokens emitidos

• Tokens de acceso opacos de corta duración, tokens de actualización rotatorios, códigos de autorización de un solo uso — todos almacenados con hash; registros de cliente cifrados en reposo

• Los URI de redirección de loopback coinciden indistintamente del puerto (la CLI de Claude Code registra un puerto y autoriza con otro); los URI que no son de loopback requieren coincidencia exacta

• Pequeña interfaz de inicio de sesión y consentimiento en Svelte 5 (una única identidad local procedente del archivo de configuración)

De cara al backend:

• none — servidores públicos (por ejemplo, Microsoft Learn MCP)

• bearærer — inyección de token estático (Authorization: Bearer …, por ejemplo, PATs)

• headers — cabeceras estáticas arbitrarias (claves de API, por ejemplo)

• oauth — cliente OAuth completo según la especificación MCP: descubrimiento de metadatos, CIMD cuando el que el AS de origen (upstream) lo admite (la pasarela aloja su propio documento de metadatos de cliente), respaldo a DCR, PKCE, renovación automática de tokens. Se conecta una vez a través del navegador; los tokens se almacenan cifrados (Fernet) en el mismo sqlite.

• load (the nodes: and there may be an unscaped)?

Let's correct: This last bullet was incomplete.

Need all bullets complete. I need note and write final fully.

The translation I traduce word by word; the last bullet should be:

But we are done. Actually I'm in final response now; there is a broken bullet inserted accidentally. Need start over final with complete document. I was composing amidst. Will output with finalized text. Ensure no malformed bullets.

Let's craft final carefully:

MCP Gateway

Una pasarela agregadora de MCP ligera y autoalojada (self-hosted): un punto único público de MCP delante de cualquier número de servidores MCP de backend protegidos, con un servidor de autorización OAuth 2.1 conforme a la especificación y de cara al cliente MCP: la pieza que falta en la mayoría de las pasarelas existentes.

...

-- continue all.

Let's not miss any bullet.

I'll create the complete document now.

But mind the token budget; output large but fine. Let's output final.# MCP Gateway

Una pasarela agregadora de MCP ligera y autoalojada alojada: un único endpoint público de MCP delante de cualquier número de servidores MCP backend protegidos, con un servidor de autorización OAuth 2.1 conforme a la especificación y orientado al cliente MCP: la pieza que falta en la mayoría de las pasarelas existentes.

Claude Code / Claude.ai ──OAuth 2.1 (DCR/CIMD + PKCE)──▶ MCP Gateway ──own credentials──▶ GitHub MCP
                                                          │                              ▶ Microsoft Learn MCP
                                                          └── /mcp (Streamable HTTP)      ▶ …more backends

Construida con FastAPI + FastMCP, configurada mediante un único archivo YAML, guarda su estado en una única base de datos SQLite cifrada y se ejecuta como un pequeño contenedor autónomo — no se requiere un proxy inverso, aunque puedes colocar uno delante de ella para TLS.

Related MCP server: MCP OAuth Test

Características

De cara al cliente (especificación de autorización MCP, 2025-11-25):

• Flujo de código de autorización OAuth 2.1 con PKCE (S256) obligatorio

• Registro Dinámico de Clientes (RFC 7591) en /register — claude mcp add funciona sin credenciales precompartidas

• Documentos de metadatos del ID de cliente (CIMD) — URLs HTTPS como IDs de cliente, incluida la autenticación de cliente private_key_jwt, anunciada mediante client_id_metadata_document_supported: true

• Metadatos del servidor de autorización (RFC 8414) y alias de descubrimiento OIDC

• Metadatos de recurso protegidos (RFC 9728); las respuestas 401 llevan WWW-Authenticate: Bearer resource_metadata="…" como exige el conector de Claude

• Indicadores de recurso (RFC 8707) aceptados y vinculados a los tokens emitidos

• Tokens de acceso opacos de corta duración, tokens de refresco rotatorios, códigos de autorización de un solo uso: todos almacenados haseeados; los registros de cliente están cifrados en reposo

• Las URI de redirección de bucle local coinciden ** independientemente del puerto** (la CLI de Claude Code registra un puerto y autoriza con otro); las URI que no son de bucle local requieren una coincidencia exacta

• Pequeña interfaz de iniciación sesión y consentimiento con Svelte 5 ( única identidad local del archivo de configuración)

De cara al backend:

• none — servidores públicos (por ejemplo, Microsoft Learn MCP)

• bearer — inyección de token estática (Authorization: Bearer …, por ejemplo, PATs)

• headers — cabeceras estáticas arbitrarias (claves de API)

• oauth — cliente OAuth completo según la especificación MCP: descubrimiento de metadatos, CIMD cuando el AS anterior lo admite (la pasarela aloja su propio documento de metadatos de cliente), respaldo de DCR, PKCE, actualización automática del token. Realizado una vez mediante el navegador; los tokens se almacenan cifrados (Fernet) en SQLite.

• El token de pasarela del cliente nunca se envía hacia el backend (no se traspasan tokens, como exige la especificación); los backends solo ven las credenciales que posee la pasarela.

Aggregación:

• Herramientas/recursos/promes con prefixo por backend: github_create_issue, msdocs_microsoft_docs_search, …

• Dinámico y robusto en tiempo real sobre Streamable HTTP; un backend caído o no conectado solo elimina sus propias herramientas en lugar de romper la pasarela

• Implemento integrado gateway_status

Inicio rápido

cp config.example.yaml config.yaml
$EDITOR config.yaml                                   # set public_url, users, backends
cp .env.example .env
$EDITOR .env                                           # set MCP_GATEWAY_ENCRYPTION_KEY (openssl rand -base64 32)
docker compose up -d

La pasarela se ejecuta de forma independiente y expone el puerto :8000; docker compose toma MCP_GATEWAY_ENCRYPTION_KEY de .env automáticamente. Puedes colocarla detrás del reverse proxy de tu elección para TLS o exponerlo el puerto directamente.

Genere un hash de contraseña para el archivo de configuración:

docker compose run --rm mcp-gateway mcp-gateway hash-password

Conectar Claude Code (CLI)

claude mcp add --transport http gateway https://mcp.example.com/mcp

Claude Code descubre el servidor de autorización, se registra mediante DCR (o usa su ID de cliente CIMD) en un flujo de identificación y abra tu navegador: inicia sesión con un usuario de config.yaml, aprueba, listo. No hay tokens que pegar.

Conectar Claude.ai / Claude Code web (conector personalizado)

Añade https://mcp.example.com/mcp como conector personalizado. El redirección del navegador a https://claude.ai/api/mcp/auth_callback pasa por el mismo flujo de inicio de sesión / consentimiento.

Conectar backends OAuth

Abre https://mcp.example.com/ui/backends, inicia sesión y pulsa Conectar junto a cada backend OAuth (por ejemplo, GitHub). Serás redirigido una vez al servidor de autorización del backend; a partir de ahí, la pasarela renueva los tokens automáticamente.

Configuración

Todo vive en un único archivo YAML (ver config.example.yaml). Los valores admiten la expansión de ${ENV_VAR} / ${ENV_VAR:-default}.

server:
  public_url: https://mcp.example.com   # behind your reverse proxy

auth:
  encryption_key: ${MCP_GATEWAY_ENCRYPTION_KEY}   # encrypts secrets at rest
  users:
    - username: admin
      password_hash: "$2b$12$…"          # mcp-gateway hash-password
  access_token_expiry_seconds: 3600
  refresh_token_expiry_seconds: 2592000

storage:
  path: /data/gateway.db                 # SQLite; the only state

backends:
  github:                                # → tools namespaced github_*
    url: https://api.githubcopilot.com/mcp/
    auth:
      type: oauth
      # GitHub's authorization server supports neither CIMD nor DCR, so
      # register a GitHub OAuth App and provide its credentials directly:
      client_id: ${GITHUB_OAUTH_CLIENT_ID}
      client_secret: ${GITHUB_OAUTH_CLIENT_SECRET}
  microsoft-docs:                        # → tools namespaced microsoft-docs_*
    url: https://learn.microsoft.com/api/mcp
    auth: { type: none }
  something-with-a-pat:
    url: https://example.com/mcp
    auth: { type: bearer, token: "${SOME_PAT}" }

Añadir un nuevo backend es solo configura: no requiere cambios en el código.

Referencia de autenticación de backends

Para backends de tipo oauth, la pasarela aloja su propio Documento de Metadatos del ID de Cliente en <public_url>/oauth/client-metadata.json y lo usa como su client_id cada vez que el AS admite CIMD (requiere public_url sobre HTTPS); en caso contrario, recurre al Registro Dinámico de Clientes. Si el AS del backend no soporta ninguno de los dos (por ejemplo, el AS de GitHub) establece client_id (y client_secret, si la aplicación es confidencial) para usar una aplicación OAuth preregistrada: CIMD/DCR se evitan por completo.

Registro

La pasarela registra eventos en stdout/stderr (docker logs, docker compose logs -f), a INFO por defecto: inicio/salto, resumen de configuración, intentos de inicio de sesión, autorización/consentimiento de OAuth, solicitudes de tokens, conexión/desconexión de backends y estado de montaje de backends. El nivel DEBUG añade más detalle: construcción del cliente, rotación de tokens, renovación automática de CIMD y mantenimiento del almacenamiento. Los datos sensibles nunca se registran.

Establece el nivel mediante la variable de entorno MCP_GATEWAY_LOG_LEVEL (debug, info, warning, error o critical):

# .env (picked up by docker compose)
MCP_GATEWAY_LOG_LEVEL=debug

# or inline
docker compose run --rm -e MCP_GATEWAY_LOG_LEVEL=debug mcp-gateway

docker-compose.yml ya envía esta variable al contenedor, con info como valor predeterminado si no se establece.

Fuera de Docker, --log-level de mcp-gateway run funciona igual y tiene prioridad sobre la variable de entorno:

mcp-gateway run -c config.yaml --log-level debug

Lugares de acceso

Notas de seguridad

• PKCE (S256) es obligatorio; los códigos de autorización son de un solo uso y expiran en 5 minutos.

• Los tokens de actualización rotan cada vez que se usan (requisito de cliente público OAuth 2.1).

• Access / refresh tokens y códigos de autorización se almacenan solo como hashes SHA-256.

• Los registros de clientes registrados y las credenciales de backends se cifran con Fernet en reposo (auth.encryption_key; se aplican derivaciones con scrypt + salt específico por base de datos).

• La pantalla de consentimiento muestra el nombre del cliente y el destino de redirección exacto, y advierte sobre redirecciones de bucle local (normativa de la suplantación del localhost en CIMD).hasta how la respuesta de acceso de tokens no se envía a backends, y viceversa.

• Las sesiones se protegen mediante firma (itsdangerous), HttpOnly, SameSite=Lax, Secure en HTTPS.

• No se registran credenciales.

Desarrollo

uv venv && uv pip install -e ".[dev]"     # or: pip install -e ".[dev]"
(cd ui && npm install && npm run build)   # build the Svelte UI
pytest                                    # 35 tests incl. full e2e OAuth flows
mcp-gateway run -c config.yaml

La suite de pruebas levanta instancias reales de la pasarela (y un segunda instancia que actúa como upstream protegido por OAuth) y ejecuta flujos DCR/CIMD + PKCE completos a través de HTTP.

Arquitectura

• src/mcp_gateway/oauth_server.py — el AS a cliente. Se apoya en los manejadores de servidor de autorización del SDK de MCP y en el gestor de CIMD de FastMCP en lugar de reinventar el protocolo; añade la persistencia en SQLite, el flujo de inicio de sesión/consentimiento y la política de emisión y rotación de tokens.

• src/mcp_gateway/upstream.py — clientes de backend y backend. Los de OAuth usan el OAuthClientProvider oficial del SDK (descubrimiento, CIMD/DCR, renovación), con almacenamiento de tokens cifrado en sqlite y flujo de conexión vía navegador.

• src/mcp_gateway/gateway.py — servidor FastAPI; cada backend se monta como un proxy en vivo bajo su espacio de nombre.

• src/mcp_gateway/app.py / web.py — app FastMCP: API REST para la UI, callback de upstream, documento CIMD y app Svelte estática; la app FastAPI se monta en la raíz.

• ui/ — Svelte 5 + Vite SPA (login, consentimiento, backends).

Una sola instancia por diseño (SQLite + flujos de conexión en memoria). Funciona como aplicación independiente; coloca un reverse proxy si deseas la terminación de TLS y respalda un solo archivo.