Conectar un agente

WhyStack lo usa un agente: un modelo de lenguaje que investiga tu infraestructura llamando a tools. La superficie por la que llega es un servidor MCP (Model Context Protocol), y esta página explica cómo apuntar un cliente hacia él.

El camino completo tiene tres saltos, y conviene tener la imagen en la cabeza antes de configurar nada:

your MCP client  ──HTTP + bearer──▶  MCP server (control plane)  ──mTLS tunnel──▶  WhyStack Agent (your infra)

Este endpoint está de nuestro lado de la frontera

El servidor MCP corre en el control-plane, no en tu infraestructura. No guarda ninguna de tus credenciales y no habla con ninguna de tus fuentes: enruta la llamada al Agent que corre dentro de tu infra, que es quien ejecuta y quien redacta. La frontera está exactamente donde siempre estuvo (ver Visión general).

Dirección y transporte

El servidor habla Streamable HTTP, el transporte HTTP de MCP, y es stateful por sesión: initialize abre la sesión, la respuesta trae un Mcp-Session-Id, y el cliente repite ese id en cada solicitud posterior.

La dirección es una URL de tu deployment. Quien lo opera te dice cuál. No hay una ruta fija: el servidor responde en el host y el puerto que exponga el proxy, así que tanto https://mcp.example.com/ como https://example.com/mcp son posibles, según el enrutamiento que haya delante.

El listener no hace TLS por sí solo

El proceso del servidor MCP escucha en HTTP plano (MCP_SERVER_PORT, por defecto 8444) y no termina TLS. Lo termina un reverse proxy o un load balancer delante de él, y el listener plano nunca debe quedar expuesto directamente a internet: su lugar es una red privada, alcanzable solo por el proxy.

Es lo opuesto al Agent, que habla mTLS con un certificado por organización en un listener separado. Dos fronteras distintas, con posturas distintas a propósito: el Agent prueba su identidad de plataforma en el enrollment; el agente LLM es un cliente común autenticado por un token.

Autenticación

Bearer en el header, con un PAT (personal access token, con el prefijo rpmcp_):

Authorization: Bearer rpmcp_...

El token se resuelve a una organización en cada solicitud, no solo cuando se abre la sesión. Token inválido, revocado o huérfano → 401. Una sesión solo responde al tenant que la abrió: presentar el token de otra organización con el Mcp-Session-Id de otra persona da 403.

Cómo emitir, acotar y revocar ese token está en la página hermana: Tokens MCP.

Configurar el cliente

Casi todos los clientes MCP aceptan un servidor HTTP remoto con un header. En el formato de archivo más común (.mcp.json):

{
  "mcpServers": {
    "whystack": {
      "type": "http",
      "url": "https://mcp.example.com/",
      "headers": { "Authorization": "Bearer ${WHYSTACK_MCP_TOKEN}" }
    }
  }
}

Si tu cliente expande variables de entorno (la mayoría lo hace), úsalo. El motivo está en el párrafo siguiente.

Este archivo lleva una credencial

Un .mcp.json con el token literal adentro es, en la práctica, acceso de lectura a tu infraestructura en texto plano, y vive en un directorio de proyecto, que es exactamente el tipo de archivo que termina en un commit. Es una de las filtraciones que la allowlist de origen de red existe para mitigar, y la mitigación es parcial: reduce la ventana, no la cierra. Ver también qué hacer ante una sospecha de filtración.

La sesión es la unidad de investigación

Una sesión MCP es una investigación entera: se abre, acumula llamadas a tools y se cierra. Desde el punto de vista del producto, no es descartable: se convierte en un registro.

• El id de la sesión es el id del trace. Mientras está abierta, aparece en vivo en Actividad en el control-plane; cuando se cierra, se convierte en un trace durable en el mismo lugar.
• Lo que queda registrado es lo que el agente llamó: por llamada, el nombre de la tool, los argumentos, si funcionó y un resumen redactado del resultado; y, para la sesión completa, el costo (cuántas operaciones fueron al borde, cuántos bytes volvieron). El contenido ya llega redactado: la redacción de PII ocurre en el Agent, antes de que salga cualquier byte (ver Redacción de PII).
• Quién puede verlo: los owners y admins de la organización, en Actividad. Es el mismo rastro que responde “¿qué ha estado mirando esta cosa en nuestra infra?” sin que tengas que confiar en nuestra palabra.

Cuando el análisis de sesiones está habilitado en el deployment, el trace también alimenta el ciclo de mejora del producto. Lo que de ahí se convierte en aprendizaje cross-tenant se anonimiza por construcción y depende de un opt-in de tu organización, desactivado por defecto.

Límites de la sesión

Límite	Por defecto	Qué pasa cuando lo alcanzas
Tiempo de inactividad	10 min	La sesión termina sola; si hizo al menos una llamada, el trace se guarda
Sesiones vivas por organización	100	429 en initialize, antes de que se cree la sesión
Llamadas a tools por sesión	500	La llamada vuelve como error, sin tocar tu infra
Tamaño del cuerpo de la solicitud	1 MiB	413

Los números importan menos que el síntoma, porque cada uno falla de una forma distinta y se parece a otra cosa:

• Inactividad. Diez minutos sin solicitudes y la sesión se cierra de nuestro lado. La siguiente llamada con ese Mcp-Session-Id responde 404 unknown session. Un cliente bien hecho la reabre solo y casi no lo notas; lo que se pierde es el contexto acumulado de la investigación, no datos. Este reaper existe porque el close() de la mayoría de los clientes no termina la sesión en el servidor (solo un DELETE explícito lo hace), y sin él una sesión quedaría abierta para siempre y nunca se convertiría en un trace.
• Sesiones vivas. El 429 es sobre toda la organización, no sobre ti, y ninguna sesión ya abierta se ve afectada. Cuando aparece sin motivo aparente, casi siempre es una pila de sesiones que nadie cerró; se resuelven solas a medida que el reaper de inactividad las recoge.
• Presupuesto de llamadas. Este es el que mejor se disfraza: la llamada vuelve como error, y un error parece una lectura fallida. No lo es. La llamada nunca salió del control-plane, no se consultó nada en tu infra. Es un presupuesto, y es por sesión: abrir una sesión nueva lo reinicia. Donde el descubrimiento bajo demanda está habilitado, search_tools no lo consume, porque no es ejecución (ver lo que lee el agente).

Cuando no hay ningún Agent conectado

Es la primera confusión de toda instalación nueva, y merece leerse antes de que ocurra.

Si en ese momento no hay ningún WhyStack Agent de tu tenant conectado, la llamada no muere con una excepción suelta, y tampoco devuelve una lista vacía. Devuelve el mismo envelope de ceguera que el producto usa para cualquier lectura que no pudo ver (abreviado aquí):

{
  "visibility": "none",
  "error": "no_visibility",
  "_sources": { "aws": "unavailable" },
  "_hint": "No WhyStack Agent is connected for this tenant right now, so nothing could be read — this is not a statement about the infrastructure. Call check_fleet_health for the fleet state; retry once an agent is up."
}

La frase del _hint es literal, y es todo el punto: esto no es una afirmación sobre tu infraestructura. Una respuesta vacía sin esa distinción se leería como “no hay nada ahí”, que es el peor resultado posible: un error hace que alguien investigue, una respuesta tranquilizadora no. La tool check_fleet_health reporta el estado real de la flota, y es por donde empezar.

Lo mismo vale un nivel más abajo: con el Agent conectado pero una integración caída, la respuesta dice qué fuente no respondió en lugar de fingir que está completa. Eso se describe en lo que lee el agente.

Lo que esta página no cubre

• Emitir y revocar el token: Tokens MCP.
• Qué puede ver el agente, y por qué dos clientes ven conjuntos distintos de tools: Lo que lee el agente.
• Qué puede escribir, y dónde se aplica cada garantía: Lo que escribe el agente.
• Restringir desde dónde puede venir la conexión: Restringir MCP por origen de red.