{"id":51855962,"url":"https://github.com/carlxsmg/mcpbridge","last_synced_at":"2026-07-24T01:00:17.548Z","repository":{"id":372876422,"uuid":"1309898990","full_name":"CarlxsMG/mcpbridge","owner":"CarlxsMG","description":"Self-hosted MCP gateway that turns any REST, GraphQL, or MCP server into secure, governed AI tools — OpenAPI auto-discovery, per-tool guardrails, RBAC, circuit breaking, and a real admin UI.","archived":false,"fork":false,"pushed_at":"2026-07-23T23:09:59.000Z","size":6512,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-24T00:15:27.538Z","etag":null,"topics":["ai-agents","ai-tools","anthropic","api-gateway","bun","claude","graphql","llm","llm-tools","mcp","mcp-gateway","mcp-proxy","mcp-server","model-context-protocol","openapi","rest-api","self-hosted","sqlite","swagger","typescript"],"latest_commit_sha":null,"homepage":"https://carlxsmg.github.io/mcpbridge/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CarlxsMG.png","metadata":{"files":{"readme":"README.es.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":null},"created_at":"2026-07-23T12:07:20.000Z","updated_at":"2026-07-23T23:09:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CarlxsMG/mcpbridge","commit_stats":null,"previous_names":["carlxsmg/mcpbridge"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/CarlxsMG/mcpbridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarlxsMG%2Fmcpbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarlxsMG%2Fmcpbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarlxsMG%2Fmcpbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarlxsMG%2Fmcpbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CarlxsMG","download_url":"https://codeload.github.com/CarlxsMG/mcpbridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CarlxsMG%2Fmcpbridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35822076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-tools","anthropic","api-gateway","bun","claude","graphql","llm","llm-tools","mcp","mcp-gateway","mcp-proxy","mcp-server","model-context-protocol","openapi","rest-api","self-hosted","sqlite","swagger","typescript"],"created_at":"2026-07-24T01:00:15.810Z","updated_at":"2026-07-24T01:00:17.399Z","avatar_url":"https://github.com/CarlxsMG.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n  Versión en español. El repo canónico en inglés sigue siendo README.md.\n  Esta duplicación se mantiene sincronizada a mano; si haces un cambio\n  significativo en cualquiera de los dos, replica el cambio aquí.\n--\u003e\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/public/favicon.svg\" width=\"72\" height=\"72\" alt=\"Logo de MCP REST Bridge\" /\u003e\n\n# MCP REST Bridge\n\n### Convierte cualquier servidor REST, GraphQL o MCP en herramientas de IA seguras y gobernadas.\n\n**El gateway MCP auto-hospedado con una UI de administración real** — auto-descubrimiento\nOpenAPI-a-MCP, guardrails por herramienta, RBAC, circuit breaking. Un único binario. Sin\nKubernetes.\n\n[![CI](https://github.com/CarlxsMG/mcpbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/CarlxsMG/mcpbridge/actions/workflows/ci.yml)\n[![Bun](https://img.shields.io/badge/runtime-Bun-black?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Model Context Protocol](https://img.shields.io/badge/Model_Context_Protocol-compatible-00a99a)](https://modelcontextprotocol.io)\n[![Licencia: MIT](https://img.shields.io/badge/license-MIT-informational)](LICENSE)\n[![PRs bienvenidos](https://img.shields.io/badge/PRs-welcome-00a99a)](#-contribuir)\n[![Mutation tested con Stryker](https://img.shields.io/badge/mutation_tested-Stryker-a2c4c9)](https://stryker-mutator.io)\n[![Estrella en GitHub](https://img.shields.io/github/stars/CarlxsMG/mcpbridge?style=social)](https://github.com/CarlxsMG/mcpbridge)\n\n[**🎮 Demo en vivo**](https://carlxsmg.github.io/mcpbridge/demo/) ·\n[**Web y docs**](https://carlxsmg.github.io/mcpbridge/) ·\n[Primeros pasos](#-quickstart-de-60-segundos) ·\n[Funcionalidades](#-funcionalidades) ·\n[¿Por qué esto frente a las alternativas?](#-mcp-rest-bridge-vs-las-alternativas)\n\n\u003c/div\u003e\n\n---\n\n**MCP REST Bridge** es un **gateway/proxy/agregador MCP** open-source para el\n[Model Context Protocol](https://modelcontextprotocol.io) (negocia la versión del protocolo\nMCP a través del **SDK oficial**, que soporta desde `2024-10-07` hasta `2025-11-25` y\nusa `2025-03-26` por defecto cuando el cliente no indica versión). Apúntalo a un spec OpenAPI/Swagger, un endpoint GraphQL, un comando `curl`\no una colección Postman y convierte tu API en herramientas MCP automáticamente. Registra un\nservidor MCP existente y lo re-expone a través del mismo\npipeline gobernado. Cada llamada pasa por protección SSRF, sanitización de prompt-injection,\nrate limits por herramienta, circuit breakers, RBAC y un log de auditoría a prueba de\nmanipulaciones — y todo lo gestionas desde una **UI de administración integrada**, no desde\nun montón de YAML. Probado contra **Claude Desktop**, **Cursor** y agentes MCP personalizados.\n\n\u003cdiv align=\"center\"\u003e\n\n![MCP REST Bridge admin UI — servidores, herramientas y salud registrados](docs/public/screenshots/servers.png)\n\n**▶ [Prueba la demo en vivo](https://carlxsmg.github.io/mcpbridge/demo/)** — la UI\nde administración completa funcionando con datos mock, sin instalar nada.\n\n\u003c/div\u003e\n\n## 🔌 Convierte cualquier cosa a MCP\n\nSeis formas de convertir un backend en tools MCP gobernadas — una llamada `POST /register`, y\nluego cada llamada pasa por la misma guard pipeline:\n\n| Tu backend                   | Regístralo con            | Se convierte en                      |\n| ---------------------------- | ------------------------- | ------------------------------------ |\n| API REST (OpenAPI / Swagger) | `openapi_url`             | una tool MCP por operación           |\n| API GraphQL                  | `graphql_url`             | una tool por query y mutation        |\n| Un comando `curl`            | `curl_input`              | una tool desde la request            |\n| Colección Postman (v2.1)     | `postman_collection`      | una tool por request                 |\n| Sin spec — a mano            | `tools[]`                 | exactamente las tools que definas    |\n| Servidor MCP existente       | `kind: \"mcp\"` + `mcp_url` | sus tools, re-expuestas y gobernadas |\n\nConsulta **[Registrar backends →](https://carlxsmg.github.io/mcpbridge/es/guide/registering-backends)**\npara el payload de cada uno, y **[Bundles →](https://carlxsmg.github.io/mcpbridge/es/guide/bundles)**\npara servir varios backends por un solo endpoint.\n\n## ✨ Por qué MCP REST Bridge\n\n- **Una UI de admin real, no ficheros de config.** Un dashboard Vue 3 completo para\n  registrar servidores, curar bundles de herramientas, definir guardrails, rotar keys,\n  supervisar el uso y leer el log de auditoría.\n- **Bidireccional en un binario.** REST, GraphQL y OpenAPI → MCP **y** MCP → gateway MCP.\n  Agrega muchos backends detrás de un endpoint curado (un bundle).\n- **Testeado de verdad, no solo verde.** Una suite de 330+ ficheros en el backend, Vitest\n  para el admin UI, e2e con Playwright, y **mutation testing con [Stryker](https://stryker-mutator.io)**\n  que inyecta fallos para probar que los tests atrapan bugs de verdad.\n- **Seguro por defecto.** Protección SSRF + DNS-rebinding con anclaje de IP, sanitización\n  de prompt-injection, detección de secretos y restricciones fail-closed de keys por\n  herramienta — integrado, no como plugin.\n- **Funcionalidades enterprise sin peso enterprise.** RBAC, equipos, audit hash-chain +\n  SIEM, canary/failover, tracing OpenTelemetry, versionado de config — **sin Kubernetes y\n  sin base de datos externa.**\n- **Ejecuta en cualquier sitio.** Proceso único Bun + `bun:sqlite`. Una imagen Docker, o\n  `bun src/index.ts`.\n\n## 🚀 Quickstart de 60 segundos\n\n### Docker\n\n```bash\ndocker build -t mcpbridge .\n\nexport ADMIN_API_KEY=$(openssl rand -hex 24)\n\ndocker run -p 3000:3000 \\\n  -e NODE_ENV=development \\\n  -e SESSION_COOKIE_SECURE=false \\\n  -e BOOTSTRAP_ADMIN_USERNAME=admin \\\n  -e BOOTSTRAP_ADMIN_PASSWORD=change-me-min-12-chars \\\n  -e ADMIN_API_KEYS=$ADMIN_API_KEY \\\n  -v \"$PWD/data:/app/data\" \\\n  mcpbridge\n```\n\nAbre la UI de admin en **http://localhost:3000/admin** e inicia sesión con las credenciales\nbootstrap. `$ADMIN_API_KEY` es el token Bearer que usan los ejemplos `curl`/CLI de abajo —\nmantenlo exportado en el mismo shell. (`NODE_ENV=development` + `SESSION_COOKIE_SECURE=false`\nson solo para HTTP local — en producción ejecuta sobre HTTPS y elimina ambas.)\n\n\u003e **¿Prefieres no compilar desde el código?** Cuando se publique la primera release, cada\n\u003e release publicará una imagen prebuilt, multi-arch y firmada en GHCR — entonces podrás quitar\n\u003e el paso `docker build` y usar `ghcr.io/carlxsmg/mcpbridge:latest` como imagen en\n\u003e `docker run`. Hasta entonces, compila en local con el `docker build` de arriba. Consulta\n\u003e [Despliegue](https://carlxsmg.github.io/mcpbridge/es/guide/deployment).\n\n### Bun (desarrollo local, con hot reload)\n\n```bash\nbun install\ncp .env.example .env                 # luego configura BOOTSTRAP_ADMIN_PASSWORD (mín 12 chars)\ncd admin-ui \u0026\u0026 bun install \u0026\u0026 cd ..\n\nbun run dev:all                      # backend :8790 + admin UI :8791\n# → abre http://localhost:8791/admin/\n```\n\n\u003e **Nota:** el modo dev usa a propósito puertos distintos (8790/8791) que el 3000 por\n\u003e defecto de Docker/producción — puertos altos y poco comunes para que un servidor dev local\n\u003e no choque con 3000 (o con una instancia real de gateway) que también puedas tener\n\u003e ejecutándose. Consulta [Configuración](https://carlxsmg.github.io/mcpbridge/es/guide/configuration)\n\u003e para la referencia completa de puertos.\n\n\u003e **Todos los ejemplos de `curl`, config de cliente y `cli --url` de abajo usan\n\u003e `http://localhost:3000`** (el puerto de Docker). En la ruta Bun el backend está en `:8790` en\n\u003e su lugar — define `export BASE=http://localhost:8790` y sustituye `$BASE` por\n\u003e `http://localhost:3000`, o simplemente reemplaza el puerto a mano.\n\n### Registra tu primera API REST (auto-descubierta desde OpenAPI)\n\nDesde la UI: **Añadir servidor → REST**, pega una URL de OpenAPI, listo. O vía API:\n\n```bash\ncurl -X POST http://localhost:3000/register \\\n  -H \"Authorization: Bearer $ADMIN_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"petstore\",\n    \"health_url\": \"https://petstore3.swagger.io/\",\n    \"openapi_url\": \"https://petstore3.swagger.io/api/v3/openapi.json\"\n  }'\n```\n\n### Registra un servidor MCP existente como upstream\n\n```bash\ncurl -X POST http://localhost:3000/register \\\n  -H \"Authorization: Bearer $ADMIN_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"github\",\n    \"kind\": \"mcp\",\n    \"mcp_url\": \"https://your-mcp-server.example.com/mcp\",\n    \"mcp_transport\": \"streamable-http\"\n  }'\n```\n\n### Apunta un cliente MCP al bridge\n\nApúntalo a un shard de backend — el `petstore` que registraste está en `/mcp/petstore`:\n\n```json\n{\n  \"mcpServers\": {\n    \"petstore\": { \"url\": \"http://localhost:3000/mcp/petstore\" }\n  }\n}\n```\n\nSirve tools de backend de dos maneras: por cliente `/mcp/:name` (un backend) o un bundle\ncurado `/mcp-custom/:bundle` (varios tras un endpoint). La raíz `/mcp` es el control plane\n(tools `sys_*` de gestión del gateway), no tools de backend — todo sobre Streamable HTTP.\n\n### CLI (config-as-code)\n\n¿Prefieres gestionar la configuración como un fichero YAML revisable en lugar de hacer clic\nen la UI? Un CLI `gateway` viene en el repo — sin instalación separada, solo\n`bun run cli -- \u003ccommand\u003e`:\n\n```bash\nbun run cli -- login --url http://localhost:3000 --token $ADMIN_API_KEY\nbun run cli -- pull    # escribe la config en vivo a gateway.yaml\nbun run cli -- plan    # muestra drift vs. gateway.yaml, exit no-cero si hay (CI-friendly)\nbun run cli -- apply   # registra servidores + aplica config desde gateway.yaml\nbun run cli -- connect --client claude-desktop --scope system   # imprime la config del cliente MCP para pegar\n```\n\nFlags globales, independientes de cualquier subcomando: `help` / `-h` / `--help` (también el\ncomportamiento por defecto sin ningún comando) y `version` / `-v` / `--version`, ambos\nsaliendo con `0`.\n\nConsulta **[CLI docs →](https://carlxsmg.github.io/mcpbridge/es/guide/cli)** para la\nreferencia completa de comandos y el formato de `gateway.yaml`.\n\n## 🧩 Funcionalidades\n\n**Conecta cualquier cosa**\n\n- Auto-descubrimiento **OpenAPI / Swagger → MCP** — apunta a un spec, obtén tools al instante\n- **GraphQL → MCP** — introspecciona el schema, una tool por query y mutation\n- **Import cURL / Postman** — deriva tools de un `curl` pegado o una exportación Postman v2.1\n- **Definiciones manuales de tools** cuando no hay spec\n- Gateway / agregador **MCP → MCP** (upstreams Streamable HTTP + SSE)\n- Dos modos de servir de datos: por cliente `/mcp/:name` y bundles curados `/mcp-custom/:bundle` (la raíz `/mcp` es el control plane del sistema)\n\n**Gobernar y asegurar**\n\n- Protección SSRF + DNS-rebinding, **anclaje de IP** por upstream\n- **Guardrails**: sanitización de prompt-injection, detección de secretos, reglas de denegación de inputs\n- **Rate limits, timeouts, restricciones de keys permitidas** por herramienta + **circuit breakers** por cliente\n- **RBAC** (admin / operator / auditor / viewer) + **multi-tenancy por equipos**\n- **Log de auditoría a prueba de manipulaciones** (encadenado por hash) + streaming a SIEM\n\n**Opera con confianza**\n\n- **UI de admin** (Vue 3): dashboard, servidores, bundles, keys, uso, alertas, programaciones, auditoría\n- **CLI** (`bun run cli`) para config-as-code: `login` / `pull` / `plan` / `apply` contra `gateway.yaml`, más `connect` para generar configs de cliente MCP — consulta [CLI docs](https://carlxsmg.github.io/mcpbridge/es/guide/cli)\n- Monitorización de salud + auto-eliminación; **canary / failover** secundarios\n- **Versionado de config + rollback**, import / export\n- Prometheus `/metrics` + tracing **OpenTelemetry (OTLP)** por llamada de tool\n- Alertas de **anomalía / pico de uso** vía webhooks\n- Tools compuestas / macro, una meta-tool `search_tools` y un playground de requests\n\n**Ejecuta en cualquier sitio**\n\n- Proceso único Bun, almacenamiento `bun:sqlite` — **sin DB externa, sin Kubernetes**\n- Una imagen Docker, o `bun src/index.ts`\n\n## 🔀 Cómo funciona\n\n\u003cp align=\"center\"\u003e\n  \u003cimg\n    alt=\"Los clientes AI envían llamadas de tools por MCP; el bridge ejecuta cada una por SSRF, guardrails, breaker, dispatch y audit, y luego despacha a tus backends REST o MCP\"\n    src=\"docs/public/screenshots/how-it-works.png\"\n    width=\"860\"\n  /\u003e\n\u003c/p\u003e\n\nEl bridge anuncia una lista unificada de tools a cualquier cliente MCP, luego redirige cada\nllamada al backend correcto a través de la pila completa de guards (chequeo SSRF →\nguardrails → política por herramienta → circuit breaker → dispatch → sanitización de\nresponse → audit).\n\n## ⚖️ MCP REST Bridge vs. las alternativas\n\n|                                                 | CLIs OpenAPI→MCP | Gateways pesados (k8s) | **MCP REST Bridge** |\n| ----------------------------------------------- | :--------------: | :--------------------: | :-----------------: |\n| REST / GraphQL / OpenAPI → MCP                  |        ✅        |        parcial         |         ✅          |\n| Gateway MCP → MCP                               |        ❌        |           ✅           |         ✅          |\n| UI de admin                                     |        ❌        |        algunos         |     ✅ Vue SPA      |\n| Seguridad integrada (SSRF, inyección, secretos) |        ❌        |        algunos         |         ✅          |\n| RBAC + audit + equipos                          |        ❌        |           ✅           |         ✅          |\n| Ejecuta sin Kubernetes                          |        ✅        |           ❌           |         ✅          |\n| Sin base de datos externa                       |        ✅        |           ❌           |  ✅ (Bun + SQLite)  |\n\n_Las capacidades varían según el proyecto; esto es posicionamiento general, no un scorecard\nde ninguna herramienta específica._\n\n## 📚 Documentación\n\nLas docs completas viven en la **[web del proyecto](https://carlxsmg.github.io/mcpbridge/)**:\n[Primeros pasos](https://carlxsmg.github.io/mcpbridge/es/guide/getting-started) ·\n[Funcionalidades](https://carlxsmg.github.io/mcpbridge/es/guide/features) ·\n[¿Por qué MCP REST Bridge?](https://carlxsmg.github.io/mcpbridge/es/guide/why-mcp-rest-bridge)\n\n¿Prefieres aprender con ejemplos? El directorio **[`examples/`](examples/)** trae muestras listas\npara copiar y ejecutar: un body de `POST /register` por cada modo de registro, un `gateway.yaml`\nconfig-as-code, y configs drop-in de clientes MCP.\n\n## 🛠️ Stack técnico\n\n[Bun](https://bun.sh) · TypeScript (strict) · Express 5 ·\n[`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) ·\n`bun:sqlite` · Vue 3 + Vite (admin UI). Sin ORM, dependencias mínimas.\n\n## 🤝 Contribuir\n\n¡Contribuciones bienvenidas! El bridge está cubierto por **varios sistemas de test, no uno** —\n**Bun** para la suite de 330+ ficheros del backend, **Vitest** para el admin UI, **Playwright**\nend-to-end, y encima **mutation testing con [Stryker](https://stryker-mutator.io)** (que inyecta\nfallos para probar que los tests atrapan bugs de verdad, no solo ejecutan líneas). Después de\ncualquier cambio:\n\n```bash\ntsc --noEmit                            # type-check del backend\nbun run test                            # tests del backend (deberían estar 100% verdes)\nbun run test:e2e                        # end-to-end con Playwright (e2e/)\nbun run test:mutate                     # mutation testing con Stryker (acota a los ficheros cambiados)\ncd admin-ui \u0026\u0026 bun run typecheck        # type-check del admin UI\ncd admin-ui \u0026\u0026 bun run test             # tests del admin UI (Vitest)\ncd admin-ui \u0026\u0026 bun run build            # build de producción del admin UI\n```\n\nAbre un issue para discutir cambios grandes primero. Las buenas primeras contribuciones\nestán etiquetadas en el tracker. Consulta la **[guía de contribución en español](docs/es/guide/contributing.md)**\npara los detalles completos (el [`CONTRIBUTING.md`](CONTRIBUTING.md) raíz es la versión canónica, en inglés).\n\n## 📄 Licencia\n\nMIT — consulta [`LICENSE`](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Palabras clave:** MCP gateway · MCP proxy · MCP aggregator · Model Context Protocol ·\nOpenAPI to MCP · REST to MCP · self-hosted MCP · MCP admin UI · MCP RBAC · AI tool gateway\n\nSi este proyecto te ayuda, por favor ⭐ **[destácalo en GitHub](https://github.com/CarlxsMG/mcpbridge)**\n— es la mayor señal que ayuda a otros a descubrirlo.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlxsmg%2Fmcpbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlxsmg%2Fmcpbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlxsmg%2Fmcpbridge/lists"}