Host MCP

La plataforma actúa como host MCP (Model Context Protocol) para que asistentes compatibles —por ejemplo ChatGPT— puedan orquestar journeys completos usando herramientas, recursos y prompts del dominio de Agents Studio.

Toda la especificación funcional y catálogo de capabilities vive en docs/modules/mcp.md. Este documento resume cómo consumir el host desde clientes MCP.

Capacidades expuestas

Tools: operaciones atómicas sobre dominios de agentes, versiones e instrucciones.
Resources: catálogos legibles por la IA (e.g. blueprints disponibles, resumen de estados).
Resource templates: estructuras predefinidas que la IA puede completar para persistir datos.
Prompts: guías reutilizables para que el asistente genere contenido consistente.

El primer journey soportado es “crea tu primer agente”, que cubre:

Captura del nombre y descripción del agente.
Definición y sincronización del horario base junto con sus excepciones controladas.
Gestión opcional de etiquetas.
Selección/adaptación de un blueprint de personalidad.
Redacción de instrucciones iniciales.
Publicación de la versión básica (chat o voz).

Para el paso de disponibilidad, el host expone el prompt agents.schedule_guardrails y los tools agents_schedule_upsert, agents_schedule_exception_upsert y agents_schedule_exception_delete, lo que permite validar timezone, publicar horarios y mantener excepciones al día sin salir del journey.

Stages y triggers de blueprint

La versión más reciente del host añade herramientas MCP para gestionar la progresión conversacional del blueprint:

Tipo	Identificador	Descripción
Tool	`agent_stages_list`	Lista los stages vigentes de un agente con paginación y filtros opcionales.
Tool	`agent_stages_get`	Obtiene el detalle completo de un stage.
Tool	`agent_stages_create`	Crea stages nuevos con orden y metadatos opcionales.
Tool	`agent_stages_update`	Actualiza título, prompt, metadatos o transiciones de un stage.
Tool	`agent_stages_delete`	Elimina un stage (soft-delete) manteniendo integridad con triggers.
Tool	`agent_stages_reorder`	Reordena múltiples stages en una sola llamada.
Tool	`agent_stage_triggers_list`	Pagina triggers asociados a un stage.
Tool	`agent_stage_triggers_get`	Obtiene un trigger concreto incluyendo su condición y destino.
Tool	`agent_stage_triggers_create`	Declara un trigger nuevo ligando condición → stage siguiente.
Tool	`agent_stage_triggers_update`	Ajusta condición, metadata o destino del trigger.
Tool	`agent_stage_triggers_delete`	Elimina triggers que ya no son válidos.
Prompt	`agent_stages_guardrails`	Checklist para validar consistencia antes de editar stages/triggers.
Resource template	`blueprintStageDraft`	Entrega un JSON base con stages, orden y triggers listos para documentación colaborativa.

Recuerda habilitar los scopes blueprint-stages:* y stage-triggers:* al emitir la API Key que usará el host.

Cómo conectarte

Genera credenciales. Usa una API Key del workspace con los scopes mínimos necesarios (agents:*, agent-blueprints:*, blueprint-stages:*, stage-triggers:*, etc.). Consulta la tabla de scopes para elegir los permisos correctos.
Identifica la URL base. El host MCP comparte dominio con la Public API. En producción: https://api-prod.studio.getsupervisor.ai. Revisa apps/public-api/src/mcp/mcp.config.ts para confirmar los endpoints habilitados si estás en otro entorno.
Configura tu cliente MCP. Define los endpoints GET /mcp/sse y POST /mcp, incluyendo los headers X-API-Key y X-Workspace-Id.
Ejecuta el handshake. La primera llamada debe ser el método handshake (JSON-RPC) para recibir la lista de tools, resources, prompts y templates disponibles.
Mantén la sesión viva. Usa SSE para recibir eventos en tiempo real y las llamadas HTTP para invocaciones puntuales. Rota la API Key siguiendo tus políticas internas.

Ejemplo de configuración (`mcp.json`)

{
  "servers": [
    {
      "name": "agents-studio",
      "url": "https://api-prod.studio.getsupervisor.ai/mcp",
      "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
      "headers": {
        "X-API-Key": "${API_KEY}",
        "X-Workspace-Id": "${WORKSPACE_ID}"
      }
    }
  ]
}

Sustituye ${API_KEY} por tu credencial. Algunos clientes MCP (por ejemplo, mcp-cli) permiten interpolar variables de entorno directamente.

Clientes populares

Windsurf
Claude Desktop
VS Code
Cursor

Copia la configuración en ~/.windsurf/mcp/servers.json (o el archivo que uses para tus conexiones):

{
  "servers": [
    {
      "name": "agents-studio",
      "url": "https://api-prod.studio.getsupervisor.ai/mcp",
      "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
      "headers": {
        "X-API-Key": "${API_KEY}",
        "X-Workspace-Id": "${WORKSPACE_ID}"
      }
    }
  ]
}

Reinicia Windsurf para que el host aparezca en la lista y actívalo desde la barra lateral de MCP.

Abre Settings → MCP y añade un nuevo servidor:

{
  "name": "agents-studio",
  "url": "https://api-prod.studio.getsupervisor.ai/mcp",
  "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
  "headers": {
    "X-API-Key": "TU_API_KEY",
    "X-Workspace-Id": "TU_WORKSPACE_ID"
  }
}

Especifica la ruta SSE y coloca los headers en el apartado Custom Headers.

Instala la extensión oficial de MCP, luego edita settings.json del workspace:

{
  "mcp.servers": [
    {
      "name": "agents-studio",
      "url": "https://api-prod.studio.getsupervisor.ai/mcp",
      "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
      "headers": {
        "X-API-Key": "${API_KEY}",
        "X-Workspace-Id": "${WORKSPACE_ID}"
      }
    }
  ]
}

Guarda y recarga la ventana; la conexión quedará disponible en el panel de la extensión.

Ve a Settings → MCP, agrega un host personalizado y pega:

{
  "name": "agents-studio",
  "url": "https://api-prod.studio.getsupervisor.ai/mcp",
  "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
  "headers": {
    "X-API-Key": "${API_KEY}",
    "X-Workspace-Id": "${WORKSPACE_ID}"
  }
}

Cursor soporta variables de entorno en los headers (${}), facilitando el manejo seguro de API Keys.

Endpoints HTTP / SSE

Aunque MCP puede funcionar por STDIO, el backend expone dos endpoints HTTP para facilitar integraciones:

`GET /mcp/sse`

Establece un stream text/event-stream compatible con SSE. Cada evento sigue el formato JSON-RPC definido por MCP.

GET /mcp/sse HTTP/1.1
Host: api-prod.studio.getsupervisor.ai
X-API-Key: <api-key>
Accept: text/event-stream

Respuesta (fragmento):

id: 1
event: mcp-handshake
data: {"jsonrpc":"2.0","method":"handshake","params":{"protocol":"2025-06-18","capabilities":{"tools":[...]} }}

`POST /mcp/http`

Canal JSON-RPC sobre HTTP para invocar métodos MCP puntuales.

POST /mcp/http HTTP/1.1
Host: api-prod.studio.getsupervisor.ai
X-API-Key: <api-key>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "sync-tags",
  "method": "agents_sync_tags",
  "params": {
    "agentId": "4a1f...",
    "tags": ["ventas", "latam"]
  }
}

Respuesta de ejemplo:

{
  "jsonrpc": "2.0",
  "id": "sync-tags",
  "result": {
    "agentId": "4a1f...",
    "tags": ["ventas", "latam"],
    "journey": "create-first-agent"
  }
}

Autenticación

Los endpoints reutilizan el header X-API-Key descrito en la API REST. Usa la misma API Key y scopes que permitirían operar sobre agentes, versiones e instrucciones.

Cómo descubrir capabilities

Conéctate vía SSE u obtén el manifiesto inicial mediante POST /mcp/http con el método handshake.
Revisa la documentación funcional en docs/modules/mcp.md para conocer descripciones, inputs/outputs y ejemplos por capability.
Sigue el recurso journeys.create-first-agent expuesto por el host para guiar a los usuarios finales paso a paso.

Próximos pasos

Extender secciones de documentación con ejemplos prácticos para partners y clientes finales.
Añadir métricas y trazabilidad de llamadas MCP.
Publicar kits de integración para hosts populares (CLI, VSCode, ChatGPT MCP, etc.).

Documentación

API Reference

MCP

Conocimiento

Blueprint

Plantillas

Misceláneos

Notificaciones

Capacidades expuestas

Stages y triggers de blueprint

Cómo conectarte

Ejemplo de configuración (`mcp.json`)

Clientes populares

Endpoints HTTP / SSE

`GET /mcp/sse`

`POST /mcp/http`

Autenticación

Cómo descubrir capabilities

Próximos pasos

​Capacidades expuestas

​Stages y triggers de blueprint

​Cómo conectarte

​Ejemplo de configuración (mcp.json)

​Clientes populares

​Endpoints HTTP / SSE

​GET /mcp/sse

​POST /mcp/http

​Autenticación

​Cómo descubrir capabilities

​Próximos pasos

Capacidades expuestas

Stages y triggers de blueprint

Cómo conectarte

Ejemplo de configuración (`mcp.json`)

Clientes populares

Endpoints HTTP / SSE

`GET /mcp/sse`

`POST /mcp/http`

Autenticación

Cómo descubrir capabilities

Próximos pasos