Conectar clientes MCP

Cualquier cliente MCP — Claude Desktop, Cursor, una extensión de IDE o tu propio agente — se conecta al bridge a través del Model Context Protocol. Apúntalo al endpoint que corresponde a las tools que debe ver.

Versión de protocolo soportada

El bridge negocia la versión del protocolo MCP a través del SDK oficial de TypeScript, que soporta desde 2024-10-07 hasta 2025-11-25 y usa 2025-03-26 por defecto cuando el cliente no indica versión. Los clientes que negocien una versión dentro de ese rango durante el init deberían interoperar automáticamente — vale la pena saberlo si te encuentras con una rareza específica del cliente.

Elige un endpoint

El bridge expone tres endpoints en dos planos. Para darle a un agente tus tools de backend, usa uno de los dos endpoints del plano de datos:

Endpoint	Le da al cliente	Úsalo cuando
/mcp/:clientName	Solo las tools de ese backend	Quieres un único backend (p. ej. /mcp/petstore)
/mcp-custom/:bundleName	Un subconjunto entre backends curado	Has curado exactamente las tools que un agente necesita — crea uno →

No hay un endpoint "todo aplanado junto": para exponer varios backends por una sola URL, cura un bundle. El tercer endpoint es el control plane:

Endpoint	Le da al cliente	Úsalo cuando
POST /mcp	Tools sys_* para gestionar el gateway — no tools de backend	Un agente debe operar el gateway mismo

Nota: POST /mcp no acepta una credencial MCP_API_KEYS normal — consulta la sección "Autenticación" más abajo para lo que realmente requiere.

Todos los endpoints hablan Streamable HTTP (el transporte SSE legacy GET /sse + POST /messages fue eliminado).

Nota: "client" está sobrecargado en esta página — :clientName en una URL es el nombre que diste a un backend en el registro (p. ej. petstore), no a la app que se conecta al bridge (Claude Desktop, Cursor, …). Este doc usa "client" para ambos; mira el contexto. Consulta Conceptos y glosario para el vocabulario completo.

Apuntar un cliente

La mayoría de los clientes aceptan una URL remota de servidor MCP — apúntalos a un shard de backend:

{
  "mcpServers": {
    "petstore": { "url": "https://bridge.example.com/mcp/petstore" }
  }
}

Para un bundle curado, cambia la URL a https://bridge.example.com/mcp-custom/support-agent; para operar el gateway mismo, usa https://bridge.example.com/mcp.

¿Prefieres no editar ese JSON a mano? gateway connect --client cursor --scope client --name petstore (y amigos para Claude Desktop, Windsurf, Continue) genera el mismo snippet desde el CLI — consulta Referencia CLI →.

Autenticación

Si configuraste MCP_API_KEYS (recomendado en producción), el cliente debe presentar una key como token Bearer:

Authorization: Bearer <mcp-api-key>

Los clientes que soportan headers custom pueden configurarlo directamente; para otros, pon el bridge detrás de un proxy que lo inyecte. Las keys pueden tener scope a clientes/tools específicos y recibir una expiración — consulta Control de acceso. El bridge también puede aceptar JWTs OAuth2/OIDC como credencial cuando JWT_JWKS_URL está configurado.

Esto aplica solo a los dos endpoints del plano de datos. POST /mcp (el control plane) tiene su propio check fail-closed (resolveSystemRole) que nunca consulta MCP_API_KEYS/JWTs: solo acepta el Bearer de entorno ADMIN_API_KEYS, o una key gestionada con un rol de sistema (adminRole) configurado — que se puede asignar desde la página Keys de la admin UI. Una key MCP_API_KEYS normal, o una key gestionada sin adminRole, se rechaza sin más contra /mcp, aunque funcione bien contra /mcp/:clientName o /mcp-custom/:bundleName.

Verificar la conexión

• GET /health debe devolver { "status": "ok" }.
• La lista de tools del cliente debe poblarse después de conectar; si está vacía, el cliente/tool puede estar deshabilitado o la key fuera de scope.
• GET /metrics (admin autenticado) expone mcp_tool_calls_total{outcome} una vez que las llamadas empiezan a fluir.

Siguiente: Registrar backends → para darles algo a los clientes, o Control de acceso → para hacer scope de quién puede llamar a qué.