Skip to main content
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:
  1. Captura del nombre y descripción del agente.
  2. Definición y sincronización del horario base junto con sus excepciones controladas.
  3. Gestión opcional de etiquetas.
  4. Selección/adaptación de un blueprint de personalidad.
  5. Redacción de instrucciones iniciales.
  6. 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:
TipoIdentificadorDescripción
Toolagent_stages_listLista los stages vigentes de un agente con paginación y filtros opcionales.
Toolagent_stages_getObtiene el detalle completo de un stage.
Toolagent_stages_createCrea stages nuevos con orden y metadatos opcionales.
Toolagent_stages_updateActualiza título, prompt, metadatos o transiciones de un stage.
Toolagent_stages_deleteElimina un stage (soft-delete) manteniendo integridad con triggers.
Toolagent_stages_reorderReordena múltiples stages en una sola llamada.
Toolagent_stage_triggers_listPagina triggers asociados a un stage.
Toolagent_stage_triggers_getObtiene un trigger concreto incluyendo su condición y destino.
Toolagent_stage_triggers_createDeclara un trigger nuevo ligando condición → stage siguiente.
Toolagent_stage_triggers_updateAjusta condición, metadata o destino del trigger.
Toolagent_stage_triggers_deleteElimina triggers que ya no son válidos.
Promptagent_stages_guardrailsChecklist para validar consistencia antes de editar stages/triggers.
Resource templateblueprintStageDraftEntrega un JSON base con stages, orden y triggers listos para documentación colaborativa.
Recuerda habilitar los scopes stages:* y stage-triggers:* al emitir la API Key que usará el host.

​
Cómo conectarte

  1. Genera credenciales. Usa una API Key del workspace con los scopes mínimos necesarios (agents:*, agent-blueprints:*, stages:*, stage-triggers:*, etc.). Consulta la tabla de scopes para elegir los permisos correctos.
  2. 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.
  3. Configura tu cliente MCP. Define los endpoints GET /mcp/sse y POST /mcp/http, incluyendo los headers X-API-Key y Workspace-Id.
  4. 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.
  5. 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/http",
      "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
      "headers": {
        "X-API-Key": "${API_KEY}",
        "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/http",
      "sse": "https://api-prod.studio.getsupervisor.ai/mcp/sse",
      "headers": {
        "X-API-Key": "${API_KEY}",
        "Workspace-Id": "${WORKSPACE_ID}"
      }
    }
  ]
}
Reinicia Windsurf para que el host aparezca en la lista y actívalo desde la barra lateral de MCP.

​
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: agents.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: agents.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

  1. Conéctate vía SSE u obtén el manifiesto inicial mediante POST /mcp/http con el método handshake.
  2. Revisa la documentación funcional en docs/modules/mcp.md para conocer descripciones, inputs/outputs y ejemplos por capability.
  3. 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.).