> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Host MCP

> Cómo interactuar con las capabilities MCP del backend de Agents Studio.

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`](../../../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:

| 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

1. **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](./keys#scopes-disponibles) 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`, incluyendo los headers `X-API-Key` y `X-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`)

```json theme={null}
{
  "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

<Tabs>
  <Tab title="Windsurf">
    Copia la configuración en `~/.windsurf/mcp/servers.json` (o el archivo que uses para tus conexiones):

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Claude Desktop">
    Abre `Settings → MCP` y añade un nuevo servidor:

    ```json theme={null}
    {
      "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*.
  </Tab>

  <Tab title="VS Code">
    Instala la extensión oficial de MCP, luego edita `settings.json` del workspace:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Cursor">
    Ve a `Settings → MCP`, agrega un host personalizado y pega:

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

## 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.

```http theme={null}
GET /mcp/sse HTTP/1.1
Host: api-prod.studio.getsupervisor.ai
X-API-Key: <api-key>
Accept: text/event-stream
```

Respuesta (fragmento):

```text theme={null}
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.

```http theme={null}
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:

```json theme={null}
{
  "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`](../../../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.).