MCP server

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.

Agents Studio expone un servidor MCP (Model Context Protocol) que le da a un asistente compatible —Claude, ChatGPT, Codex, Cursor— las mismas operaciones que tu equipo hace en el dashboard: crear un agente, escribirle la personalidad, armar el flujo conversacional, conectarle herramientas y bases de conocimiento, y publicarlo. Úsalo cuando quieras que un asistente opere tu workspace sin darle acceso a una terminal ni escribir integraciones contra la Public API a mano. Endpoint:

https://api-prod.studio.getsupervisor.ai/mcp

El endpoint MCP no lleva el prefijo /v1 que usa el resto de la Public API. Los clientes MCP y el descubrimiento de OAuth asumen /mcp en la raíz del dominio, así que está excluido del prefijo a propósito. Si encuentras una configuración con /v1/mcp, está desactualizada.

Authentication

Elige la opción que soporte tu cliente MCP:

Browser sign-in: configuras sólo la URL, el cliente te abre el navegador, inicias sesión y eliges el workspace.
API key: creas una API Key del workspace en Agents Studio y la mandas como header.

Las dos opciones dan acceso a las mismas herramientas, con una excepción: workspaces_enable lee su credencial del header x-api-key, así que por browser sign-in falla siempre. Es una operación administrativa, no parte del arranque normal — ver Tools.

Header de API Key

x-api-key: TU_API_KEY

La API Key va en x-api-key, nunca en Authorization: Bearer. El header Authorization está reservado para el token de sesión de Auth0, que se valida como JWT RS256 — una API Key ahí se rechaza con 401. Es la diferencia más común con otros servidores MCP, y falla de forma silenciosa hasta que el cliente intenta la primera llamada.

Credencial	Header	Cuándo
API Key del workspace (`sk_…`)	`x-api-key: TU_API_KEY`	Integraciones, automatizaciones, agentes sin navegador
Token de sesión de Auth0	`Authorization: Bearer TU_JWT`	Browser sign-in (lo gestiona el cliente por ti)

Connect

Para clientes que soportan inicio de sesión en el navegador, basta la URL: el servidor responde el 401 con la metadata de OAuth y el cliente arranca el flujo solo.

codex mcp add agents-studio --url https://api-prod.studio.getsupervisor.ai/mcp
codex mcp login agents-studio

claude mcp add --transport http agents-studio https://api-prod.studio.getsupervisor.ai/mcp
# Luego, dentro de Claude Code:
/mcp

{
  "mcpServers": {
    "agents-studio": {
      "url": "https://api-prod.studio.getsupervisor.ai/mcp"
    }
  }
}

Cuando se abra Agents Studio en el navegador, inicia sesión y autoriza la conexión.

API key

Exporta tu API Key del workspace:

export AGENTS_STUDIO_API_KEY="tu_api_key"

Como la credencial va en x-api-key y no en el Bearer, la configuración es la de headers personalizados en los tres clientes. Codex no tiene flag --header, así que el suyo va en ~/.codex/config.toml:

[mcp_servers.agents-studio]
url = "https://api-prod.studio.getsupervisor.ai/mcp"
env_http_headers = { "x-api-key" = "AGENTS_STUDIO_API_KEY" }

claude mcp add --transport http agents-studio https://api-prod.studio.getsupervisor.ai/mcp \
  --header "x-api-key: $AGENTS_STUDIO_API_KEY"

{
  "mcpServers": {
    "agents-studio": {
      "url": "https://api-prod.studio.getsupervisor.ai/mcp",
      "headers": {
        "x-api-key": "${env:AGENTS_STUDIO_API_KEY}"
      }
    }
  }
}

Elegir workspace

A diferencia del resto de la Public API, el servidor MCP no exige el header X-Workspace-Id: el workspace se elige con una herramienta, no con una cabecera.

Con API Key no tienes que hacer nada: la llave ya identifica a su workspace.
Con browser sign-in, las dos primeras herramientas que llamas después del handshake son workspaces_list y luego workspaces_select. A partir de ahí, todas las demás operan sobre el workspace elegido.

Transportes

Transporte	Método y ruta
Streamable HTTP (recomendado)	`POST https://api-prod.studio.getsupervisor.ai/mcp`
SSE (compatibilidad)	`GET https://api-prod.studio.getsupervisor.ai/mcp/sse`

Scopes

La API Key necesita los scopes de las operaciones que vaya a ejecutar el asistente. Para el journey completo de creación de un agente:

agents:read              agents:write
agent-versions:read      agent-versions:write
agent-instructions:read  agent-instructions:write
agent-blueprints:read    agent-blueprints:write
blueprint-stages:read    blueprint-stages:write
stage-triggers:read      stage-triggers:write
agent-schedules:read     agent-schedules:write
knowledge-bases:read     knowledge-bases:write
catalogs:read
tools:read               tools:connections:write

No hay comodines. El guard compara cadenas exactas (availableScopes.has(scope) en apps/public-api/src/auth/scopes.guard.ts), así que una llave emitida con agents:* no autoriza nada: hay que listar agents:read y agents:write por separado. Un scope que no existe se guarda sin error y falla después con un 403 que no dice cuál falta.

tools:read y tools:connections:write no son opcionales en este journey aunque no vayas a tocar herramientas: conectar una base de conocimiento se implementa por dentro como una conexión de tool, así que agent_knowledge_bases_connect lista y escribe conexiones. Si además vas a subir archivos para crear una base de conocimiento, el presign exige dos scopes a la vez —el del destino y el del carril de subida—: knowledge-bases:write y uploads:write. Tener sólo uno devuelve 403 nombrando el que falta. La tabla completa está en API Keys → Scopes disponibles. Emite siempre la llave con el conjunto mínimo: un scope que no aparece en esa tabla no otorga nada, porque ningún guard lo consulta.

Tools

El servidor expone 45 herramientas planas: una por operación, cada una con su propio esquema de entrada. No hay un parámetro action que agrupe verbos.

Dominio	Herramientas
Workspaces	`workspaces_list`, `workspaces_select`, `workspaces_enable`
Agentes	`agents_list`, `agents_get`, `agents_create`, `agents_update`, `agents_delete`, `agents_generate_draft`, `agents_fork_from_template`
Teléfonos	`agents_connect_phone`, `agents_disconnect_phone`
Versiones	`agent_versions_create`, `agent_versions_clone`, `agent_versions_publish`, `agent_versions_update_notes`
Instrucciones	`agent_version_instructions_list`, `agent_version_instructions_create`, `agent_version_instructions_update`, `agent_version_instructions_delete`
Blueprints	`agent_blueprints_create`, `agent_blueprints_update`
Stages	`agent_stages_list`, `agent_stages_get`, `agent_stages_create`, `agent_stages_update`, `agent_stages_delete`, `agent_stages_reorder`
Triggers	`agent_stage_triggers_list`, `agent_stage_triggers_get`, `agent_stage_triggers_create`, `agent_stage_triggers_update`, `agent_stage_triggers_delete`
Horarios	`agents_schedule_upsert`, `agents_schedule_exception_upsert`, `agents_schedule_exception_delete`
Bases de conocimiento	`knowledge_bases_list`, `knowledge_bases_create`, `agent_knowledge_bases_connect`
Herramientas del agente	`tools_list`, `tools_execute`, `tool_connections_upsert`, `tool_connections_execute`
Catálogos	`catalog_items_list`, `catalog_templates_list`

workspaces_enable es una operación administrativa, no parte del arranque normal: al crear un workspace queda habilitado solo. El endpoint que ejecuta (POST /v1/workspaces/enable) exige el scope backoffice:workspaces:write —que no figura en la tabla de scopes de las API Keys de workspace— y sólo acepta API Key: por browser sign-in la herramienta falla antes de llamar al API. Para elegir workspace usa workspaces_list y workspaces_select.

Para darle conocimiento a un agente usa siempre agent_knowledge_bases_connect, no tool_connections_upsert. Escribir el vínculo en la conexión equivocada deja al agente publicado sin su base de conocimiento y sin ningún error visible.

El servidor también publica resources (catálogos y esquemas que el asistente puede leer: blueprints disponibles, referencia de catálogos, resumen de journeys), resource templates (estructuras en blanco que el asistente rellena antes de persistir) y prompts (guías de validación como agents.schedule_guardrails y agents.stages_guardrails). Tu cliente los descubre solo, cada uno con su propio método: resources/list, resources/templates/list y prompts/list. Los resource templates no salen en resources/list; si tu cliente sólo llama ese método, no verás blueprintStageDraft ni los demás.

Examples

Pídele a tu asistente que explore el workspace:

Usa el MCP de agents-studio para listar mis agentes y decirme cuáles están publicados.

Que arranque un agente desde una plantilla:

Con agents-studio, busca plantillas de catálogo para cobranza, clona la que mejor encaje
y déjame el agente en borrador con el nombre "Cobranza LATAM".

Que arme el flujo conversacional:

Con agents-studio, lista los stages del blueprint del agente "Cobranza LATAM" y agrégale
un stage de despedida al final, con su trigger desde el stage de negociación.

Que le conecte conocimiento y lo publique:

Con agents-studio, lista mis bases de conocimiento, conéctale la de políticas de crédito
al agente "Cobranza LATAM" y publica la versión en borrador.

Verificar la conexión

Si un cliente no conecta, prueba el handshake a mano. La primera llamada del protocolo es initialize:

curl -sX POST https://api-prod.studio.getsupervisor.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: $AGENTS_STUDIO_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

Una conexión sana responde con la identidad del servidor:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "listChanged": true },
      "prompts": { "listChanged": true }
    },
    "serverInfo": { "name": "agents-studio-mcp", "version": "1.0.0" }
  }
}

Respuesta	Qué significa
`401 Unauthorized`	Falta la credencial, o la mandaste en `Authorization: Bearer` en lugar de `x-api-key`.
`401` con `www-authenticate: Bearer resource_metadata=…`	Normal sin credenciales: es la señal con la que el cliente arranca el browser sign-in.
`403 Insufficient scope for this operation`	La llave es válida pero le falta el scope de esa herramienta. Ver Scopes.

El handshake no termina en la respuesta de initialize: el protocolo pide que el cliente confirme con una notificación antes de pedir nada más. Es una notificación, no una petición, así que no lleva id y el servidor responde 202 sin cuerpo:

curl -sX POST https://api-prod.studio.getsupervisor.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: $AGENTS_STUDIO_API_KEY" \
  -d '{ "jsonrpc": "2.0", "method": "notifications/initialized" }'

Recién entonces, para listar las herramientas, repite la primera llamada con "method": "tools/list" y "params": {}.

Nuestro servidor corre en modo stateless, así que no rechaza un tools/list que llegue sin esa notificación. Aun así vale la pena mandarla al depurar: los clientes MCP sí la emiten, y probar a mano un flujo distinto del que usa tu cliente es cómo se persigue un fallo que no existe.

Empezar

Referencia de endpoints

Agentes

Herramientas del agente

Telefonía

Webhooks

MCP

Documentation Index

Authentication

Header de API Key

Connect

API key

Elegir workspace

Transportes

Scopes

Tools

Examples

Verificar la conexión

​Documentation Index

​Authentication

​Header de API Key

​Connect

​Browser sign-in

​API key

​Elegir workspace

​Transportes

​Scopes

​Tools

​Examples

​Verificar la conexión

Documentation Index

Authentication

Header de API Key

Connect

Browser sign-in

API key

Elegir workspace

Transportes

Scopes

Tools

Examples

Verificar la conexión