MCP Gateway

Un plano de control autohospedado para servidores de Model Context Protocol. Define cada servidor MCP que uses en un solo lugar, gestiónalos desde una interfaz web y dale a tus agentes un único endpoint — por servidor o para un grupo completo de servidores con herramientas con espacios de nombres.

 Claude Code · Claude Desktop · Cursor · VS Code · your agent
        │  Streamable HTTP  /mcp/servers/<id>   /mcp/groups/<id>      (+ API key)
        ▼
 ┌────────────────────── MCP Gateway ──────────────────────┐
 │  web GUI  ·  admin REST API  ·  sessions  ·  logs        │
 │  groups: namespaced tools  pg-analytics__execute_sql …   │
 │  upstream manager: start/stop, restart w/ backoff,       │
 │  health checks, idle stop, tool filters & renames        │
 └───────┬──────────────────┬──────────────────┬───────────┘
   stdio (npx/uvx/docker)   Streamable HTTP     legacy SSE
   Postgres, filesystem…    remote MCP servers  older servers

Escenario. Un agente necesita dos bases de datos Postgres. Añades pg-analytics y pg-orders en la interfaz (desde la plantilla PostgreSQL (DBHub)), los pones en un grupo databases y apuntas el agente a http://gateway:8808/mcp/groups/databases. El agente ve pg-analytics__execute_sql y pg-orders__execute_sql; la puerta de enlace gestiona los procesos, las credenciales, los reinicios y los registros. Una versión completa y ejecutable está en examples/postgres-scenario.

Características

• Cualquier transporte ascendente — procesos stdio (npx, uvx, docker run, lo que sea), HTTP Streamable y remotos SSE heredados con autenticación bearer/basic/header.

• Gestión del ciclo de vida — inicio automático/perezoso, detención por inactividad, reinicio con retroceso exponencial y un límite, pings de comprobación de estado, tiempos de espera de inicio/solicitud/llamada a herramienta, stderr capturado.

• Grupos — varios servidores detrás de un único endpoint; herramientas y prompts con espacios de nombres (prefix__tool, . o -), o de paso directo con gestión de conflictos; filtros por miembro; instrucciones combinadas; grupo all implícito.

• Política de herramientas — globs de inclusión/exclusión, ocultar, renombrar y re-describir herramientas por servidor.

• Proxy MCP completo — herramientas, recursos (+plantillas, suscripciones), prompts, completados, registro, progreso, cancelación, propagación de list_changed, y muestreo / elicitación / raíces de servidor→cliente enrutados de vuelta a la sesión de origen.

• Transportes descendentes — HTTP Streamable (con estado y flujos reanudables, o sin estado), SSE heredado, además de mcp-gateway-connect, un puente stdio para clientes como Claude Desktop.

• Seguridad — claves API (hash, con ámbito para servidores/grupos, con caducidad), token de administrador para la GUI/API, redacción de secretos, interpolación ${ENV} para que los secretos nunca tengan que escribirse en la configuración, protección contra rebinding de DNS, lista de permisos CORS.

• GUI — panel de control, catálogo de servidores con 16 plantillas (Postgres ×3, MySQL, SQLite, filesystem, GitHub, Playwright, Context7, fetch, memory, …), editor con pestañas con Test connection, explorador de herramientas con Try it, navegadores de recursos/prompts, registros en vivo, métricas, fragmentos de conexión por cliente, sesiones, ajustes, importación/exportación (archivos mcpServers de Claude Desktop / Cursor / VS Code).

Related MCP server: Master MCP Server

Capturas de pantalla

El panel de control — servidores en ejecución, grupos, sesiones activas y un feed de eventos en vivo:

El catálogo de servidores, con transporte, estado, recuentos de herramientas y recuentos de reinicios de un vistazo:

La vista de detalle de un servidor — datos de ejecución y endpoint, además del explorador de herramientas para llamar herramientas directamente desde la GUI:

Inicio rápido

Requisitos: Node.js ≥ 20 (además de npx/uvx/docker para los servidores ascendentes que ejecutes).

git clone <this repo> mcp-gateway && cd mcp-gateway
npm install
npm run build
npm start                     # → http://127.0.0.1:8808

Luego en la GUI: Servers → Add server → PostgreSQL (DBHub) → pega un DSN → Test connection → Create server. Abre la pestaña Connect del servidor y copia el fragmento para tu cliente, p. ej.

claude mcp add --transport http pg-analytics http://127.0.0.1:8808/mcp/servers/pg-analytics

Modo de desarrollo (Vite con recarga en caliente en :5173, puerta de enlace en :8808): npm run dev.

Docker

docker compose up -d --build              # GUI on http://localhost:8808, data in ./data

La imagen incluye node/npx, uvx y git, por lo que los servidores MCP basados en npm y Python pueden lanzarse dentro del contenedor. Establece GATEWAY_ADMIN_TOKEN en el entorno cuando el puerto sea accesible para otros. Para precargar una configuración, monta un archivo y establece GATEWAY_SEED_CONFIG=/path/to/config.json — se copia al volumen de datos en el primer inicio.

Cómo encaja

La configuración es un único archivo JSON (data/config.json, modo 0600, escrituras atómicas, se conserva .bak) — consulta docs/CONFIG.md para conocer todos los campos. La configuración del cliente para cada herramienta está en docs/CLIENTS.md; el diseño completo está en docs/SPEC.md. La GUI también tiene una página Docs integrada (/docs, junto a Ajustes) que explica cómo funciona la puerta de enlace y cómo añadir, personalizar y conectar servidores.

CLI

mcp-gateway serve [--host 127.0.0.1] [--port 8808] [--data-dir ./data] [--config <file>] [--public-url <url>] [--log-level info]
mcp-gateway import <file> [--format gateway|mcpServers] [--mode merge|replace]    # into the config file (restart to apply)
mcp-gateway export [--format gateway|mcpServers] [--secrets] [--out <file>]
mcp-gateway hash-token <token>                                                     # sha256 for settings.auth.adminTokenHash
mcp-gateway connect <url> [--api-key K] [--header 'Name: v'] [--sse]              # stdio ⇄ HTTP bridge
mcp-gateway-connect <url> …                                                        # same bridge as a standalone package (@mcp-gateway/connect)

Entorno: GATEWAY_HOST, GATEWAY_PORT, GATEWAY_DATA_DIR, GATEWAY_CONFIG, GATEWAY_ADMIN_TOKEN, GATEWAY_PUBLIC_URL, GATEWAY_LOG_LEVEL, GATEWAY_REQUIRE_API_KEY, GATEWAY_WEB_DIR, GATEWAY_SEED_CONFIG (Docker). Precedencia: flags de CLI > entorno > config.json > valores predeterminados.

Endpoints

La lista completa de rutas con las formas de solicitud/respuesta está en docs/SPEC.md §7.

Notas de seguridad

• Sin token de administrador, la GUI/API están abiertas: mantén el enlace de loopback predeterminado o establece GATEWAY_ADMIN_TOKEN.

• Activa Require API key antes de exponer /mcp más allá de localhost; limita las claves a los servidores/grupos que necesite cada agente.

• Secretos: prefiere referencias ${VAR} a valores literales; los valores bajo claves de apariencia secreta se redactan en las respuestas de la API y en las exportaciones (?secrets=1 / la exportación with secrets los incluye).

• Pon un proxy inverso con terminación TLS delante para cualquier cosa expuesta a internet (necesario para el conector MCP de la API de Anthropic).

• La puerta de enlace ejecuta los comandos que configures: cualquiera con acceso de administrador puede ejecutar procesos arbitrarios en el host.

Desarrollo

npm run dev          # gateway (tsx watch) + Vite dev server
npm run typecheck    # all workspaces
npm test             # vitest: shared unit tests, server integration tests (real stdio/HTTP fixtures), bridge tests
npm run build        # server bundle (esbuild), connect bundle, web (vite)

Estructura: packages/shared (esquema de configuración zod, DTOs, plantillas, ayudantes de nombres — seguro para navegador), packages/server (Express 5 + @modelcontextprotocol/sdk: gestor ascendente, servidor proxy, sesiones, rutas REST/MCP, CLI), packages/web (React 19 + Vite), packages/connect (puente stdio), examples/postgres-scenario (demo con docker-compose).

Limitaciones / hoja de ruta

• OAuth para servidores ascendentes no está implementado (usa autenticación bearer/basic/header); OAuth para clientes descendentes no está implementado (se usan claves API en su lugar).

• Los recursos no tienen espacios de nombres en los grupos: los URI se enrutan a su servidor propietario; los URI idénticos entre miembros se resuelven al primer miembro.

• Sin limitación de velocidad; pon un proxy inverso delante si lo necesitas.

• Sesiones y registros en memoria de un solo proceso (un reinicio pierde las sesiones; los clientes se reinicializan).

Licencia

Apache License 2.0 — consulta LICENSE y NOTICE.