Saltar al contenido principal
Un servidor MCP remoto es solo un endpoint HTTP en el que tus agentes llaman a herramientas — y la mayoría se sienta detrás de un token, un cliente OAuth o autenticación básica. Cuando registras ese servidor detrás del gateway MCP del Firewall, le entregas a OrcaRouter la credencial una vez, eliges cómo se autentica, y el gateway la inyecta en tiempo de despacho. El secreto se cifra en reposo y nunca viaja al modelo ni al código de tu agente. Esta página cubre el lado de autenticación del registro de un servidor: las cuatro formas de auth_mode y qué le pasa a tu credencial. Para todo lo que el gateway hace a cada tools/call después de que la conexión está levantada — política por llamada, espacios de nombres, protección SSRF — ver la referencia del gateway MCP.

​
1. Por qué autenticar en el gateway

Sin un gateway, cada agente que habla con un servidor MCP lleva su propia copia del token de ese servidor, disperso por configuraciones y prompts. Enruta el servidor a través de OrcaRouter en su lugar y la credencial vive en exactamente un lugar:
  • Un secreto almacenado por servidor. Registras la credencial una vez, en el registro del espacio de trabajo. Los agentes se conectan al gateway con una clave de OrcaRouter — nunca ven el token del servidor upstream.
  • Cifrado en reposo, enmascarado en lectura. La credencial se cifra cuando se almacena. Cada vez que vuelves a leer el servidor a través de la consola o el SDK, el secreto vuelve enmascarado — no hay ninguna API que lo devuelva en claro.
  • Inyectado en el despacho. El gateway descifra la credencial solo en el momento en que reenvía un tools/call al servidor real, luego la adjunta a esa solicitud saliente. Nunca se devuelve al modelo ni al cliente.
Una credencial que no puedes volver a leer es una característica, no una carencia. Como las lecturas siempre están enmascaradas, una sesión de consola o token de SDK filtrado no puede exfiltrar los secretos de tu servidor MCP — solo puede reapuntarlos o rotarlos.

​
2. Elige un auth_mode

Cada registro de servidor lleva un auth_mode. Es un conjunto cerrado de cuatro valores, y decide la forma de la credencial que suministras en auth_json:
El servidor es abierto (o confía en el gateway por red). Deja auth_json vacío. Este es el valor por defecto cuando no estableces auth_mode.
El caso más común para servidores MCP hospedados. Suministra un token; el gateway lo envía como credencial bearer en cada llamada.
{ "token": "ghp_…" }
Para servidores protegidos por OAuth. Suministra un access_token que ya acuñaste; el gateway lo envía como credencial bearer, exactamente como bearer. El intercambio automático de client-credentials (canjear un client_id/client_secret por un token fresco) aún no está disponible — un registro oauth sin un access_token se rechaza.
{ "access_token": "…" }
Autenticación básica HTTP.
{ "username": "…", "password": "…" }
auth_json es requerido siempre que auth_mode sea cualquier cosa distinta de none. Registrar un servidor bearer/oauth/basic con una credencial vacía se rechaza — el gateway no persistirá una conexión configurada a medias.

​
3. Registrar un servidor MCP seguro — un ejemplo

El registro de un servidor MCP es una acción de consola: se ejecuta bajo tu token de sesión / acceso contra /api/workspace/firewall/mcp_servers, y escribir un servidor requiere el rol Developer+. (Esto es diferente de la clave de relay sk-orca-… que usas para las llamadas de modelo /v1/* — esa clave nunca gestiona la configuración del espacio de trabajo.) Registra un servidor con autenticación bearer desde la consola del firewall, o con tu token de sesión directamente: 
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "endpoint": "https://api.githubcopilot.com/mcp",
    "auth_mode": "bearer",
    "auth_json": "{\"token\":\"ghp_x\"}",
    "enabled": true
  }'
El name es único por espacio de trabajo (un duplicado devuelve HTTP 409), y no puede contener un . — ese carácter pone las herramientas en el espacio de nombres <server>.<tool>. A la entrada, OrcaRouter cifra auth_json y almacena solo el texto cifrado. Cuando vuelves a leer el servidor, obtienes la forma enmascarada.
Haz eco del valor enmascarado directamente de vuelta en una actualización para mantener el secreto almacenado sin cambios — envía un auth_json real solo cuando realmente quieras rotarlo. Ver rotación de credenciales para el flujo de rotación.

​
4. Comprueba que la conexión funciona

La autenticación no está hecha hasta que el gateway pueda realmente alcanzar el servidor con la credencial que almacenaste. Sondéalo: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-token>"
El gateway se conecta al endpoint usando la credencial descifrada, lista las herramientas del servidor y registra un status de alcanzabilidad:
statusSignificado
okAlcanzado y autenticado; herramientas descubiertas.
degradedAlcanzable pero no del todo saludable.
downNo se pudo conectar ni autenticar.
Un resultado down justo después del registro casi siempre significa una credencial mala o el auth_mode equivocado — corrige auth_json y sondea de nuevo. Sondear es una acción Developer+; el servidor incluido en proceso no tiene endpoint y no es sondeable.
Un servidor deshabilitado es el interruptor de apagado limpio: sus herramientas desaparecen del gateway y su credencial nunca se descifra. Deshabilita un servidor mientras resuelves su autenticación, luego rehabilítalo una vez que un sondeo vuelva ok.

​
5. Leer servidores desde un agente

Tus agentes no leen credenciales. Cuando un proxy de SDK necesita el registro en tiempo de ejecución llama a GET /api/v1/firewall/mcp_servers con una clave con alcance de gateway de firewall — una clave dedicada, no tu clave de relay ni tu sesión. Esa ruta sirve solo servidores habilitados, y el gateway sigue siendo dueño de la inyección de credenciales de extremo a extremo. Conectar un agente al endpoint MCP unificado se cubre en la referencia del gateway.

​
6. Dónde ir a continuación

Conecta tu primer servidor

El recorrido completo de registro, de un espacio de trabajo vacío a una herramienta en vivo.

Rotar credenciales

Cambia un secreto filtrado o que expira sin dejar caer la conexión.

Lista de permitidos de herramientas MCP

Decide cuáles de las herramientas de un servidor pueden realmente llamar tus agentes.

Limitar el egress

Restringe dónde se permite que las herramientas de un servidor alcancen en la red.
Para los conceptos detrás de esto — cómo se sienta el gateway en el camino de la solicitud y por qué las credenciales nunca tocan el modelo — ver Cómo inspecciona OrcaRouter y Asegurar agentes de IA. Para las amenazas que esto cierra, ver Envenenamiento de herramientas MCP y exfiltración de datos.