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

# MCP

> Conecte Zelto a Claude Code, Codex, Cursor y otros clientes MCP.

Zelto expone un [Protocolo de contexto modelo](https://modelcontextprotocol.io/)
servidor en `https://api.zelto.ai/mcp`. Cualquier cliente compatible con MCP puede conectarse y obtener acceso de lectura a sus agentes, conversaciones, transcripciones, reseñas y hallazgos, además de un pequeño conjunto de herramientas de escritura para el flujo de trabajo de revisión basado en bucket.

La mayoría de las herramientas de lectura y escritura reflejan un público [API REST](/es/api-reference/agents/list-agents)
Sin embargo, algunas herramientas van más allá de la superficie REST: colas de revisión, cambios, población de cubos, conexión/importación de proveedores de voz y configuración de la organización son exclusivas de MCP. El **Espejos** En cada columna de la tabla siguiente se indica cuál es cuál (`— (MCP-only)` significa que no hay equivalente de RESTO).

> ¿Nuevo aquí? [A bordo con un agente](/es/docs/onboarding-with-an-agent) impulsa toda la configuración: conecta un proveedor, recibe llamadas, crea un monitor y enruta hallazgos [herramientas de onboarding](#incorporación) abajo.

## Obtener una clave de API

Acuña uno en
`https://dashboard.zelto.ai/org/<your-slug>/settings/integrations` →
**Carga de llamadas API**. La clave se muestra **una vez** copiarlo inmediatamente. La misma clave funciona para el [API REST](/es/api-reference/agents/list-agents) Acuñar y revocar claves es una acción de propietario/administrador; si tiene la `member`
de un rol, pregunte a un propietario o administrador por uno (y vea
[Tu papel decide lo que puedes hacer](#tu-papel-decide-lo-que-puedes-hacer)).

Exportarlo para los fragmentos a continuación:

```bash theme={null}
export ZELTO_API_KEY=<paste-key>
export ZELTO_BASE_URL=https://api.zelto.ai   # or http://localhost:3000 for local dev
```

## Iniciar sesión con OAuth

Clientes que apoyan **MCP remoto OAuth** Claude, Cursor, VS Code y otros pueden conectarse sin acuñar una clave. Apunte al cliente a la URL del servidor e inicie sesión a través de su navegador:

```
https://api.zelto.ai/mcp
```

Si usted pertenece a más de una organización, usted elige a cuál de las conexiones está enfocada en la pantalla de consentimiento el cliente solo ve los datos de esa organización, exactamente como una organización enfocada en el ámbito de la organización. [Clave API](#obtener-una-clave-de-api)Los tokens de acceso duran poco (una hora), se actualizan solo mientras la sesión de Zelto es válida y dejan de funcionar tan pronto como pierde el acceso a esa organización.

Bajo el capó, el servidor es un servidor de autorización OAuth 2.1 estándar como lo define la especificación MCP: publica
[Metadatos de recursos protegidos](https://api.zelto.ai/.well-known/oauth-protected-resource), admite el registro dinámico de clientes y requiere PKCE para que un cliente compatible descubra todo lo que necesita solo desde la URL. Las claves de API siguen funcionando en paralelo; use lo que su cliente admita.

## Clientes

### Código Claude

Añadir el servidor a `~/.claude.json` (Crear el archivo si no existe):

```json theme={null}
{
  "mcpServers": {
    "zelto": {
      "url": "https://api.zelto.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Reiniciar Claude Code (o ejecutar `/mcp` (Elemento). `zelto:` herramientas aparecen en el selector; `zelto:health` devuelve su id de la organización como prueba de humo.

> La página de Integraciones también muestra este fragmento pre-llenado con el host actual ir a **Configuración → Integraciones → AI agente access** y abrir el **Claude** tarjeta.

### OpenAI Codex CLI

Codex CLI soporta servidores MCP a través de `~/.codex/config.toml`. Añadir una entrada de servidor bajo `[mcp_servers.zelto]`:

```toml theme={null}
[mcp_servers.zelto]
url = "https://api.zelto.ai/mcp"
headers = { Authorization = "Bearer YOUR_API_KEY" }
```

Luego corre `codex` y le pregunta algo que necesite sus datos, p. ej.
*"Enumera mis últimas 20 conversaciones y fracasos de grupo por agente".* El Codex descubre el `zelto:` herramientas automáticamente.

### Cursor

`~/.cursor/mcp.json` acepta la misma forma que Claude Code:

```json theme={null}
{
  "mcpServers": {
    "zelto": {
      "url": "https://api.zelto.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

A continuación, abra el panel MCP del cursor y cambie el `zelto` Las herramientas aparecen en la barra lateral del chat.

### Continuar, Zed y otros clientes Streamable-HTTP

El servidor habla HTTP Streamable, por lo que cualquier cliente que acepte una URL +
`Authorization` header funciona. Continuar usos `config.yaml`:

```yaml theme={null}
mcpServers:
  - name: zelto
    transport:
      type: http
      url: https://api.zelto.ai/mcp
      headers:
        Authorization: Bearer YOUR_API_KEY
```

Zed utiliza `~/.config/zed/settings.json` bajo `context_servers.zelto`
con el mismo `url` + `headers` forma.

### Prueba rápida de humo (`curl`)

Si un cliente se comporta mal, verifique su clave y conectividad con la API REST: la misma clave autentica ambos:

```bash theme={null}
curl -H "Authorization: Bearer $ZELTO_API_KEY" \
  "$ZELTO_BASE_URL/v1/agents"
```

A `200` con un `{ "data": [...] }` página significa que el servidor y su clave son buenos el problema está en la configuración del cliente. Desde dentro de un cliente conectado, el `health` herramienta devuelve `{ "status": "ok", "orgId": "…" }` como el mismo cheque.

A `401` significa que la credencial es el problema: la clave se eliminó o la persona a la que pertenece perdió el acceso a la organización (se eliminó o se prohibió su cuenta). Acuñar una clave nueva solo ayuda si su propia cuenta aún tiene acceso a esa organización.

## Autenticación

Cada petición lleva un `Authorization: Bearer <token>` donde se encuentra el token **o bien** un [Clave API](#obtener-una-clave-de-api) **o** un token de acceso OAuth obtenido por [firmando](#iniciar-sesión-con-oauth). Solicitudes sin token o con devolución de token caducada/no válida `401` De cualquier manera, el token se resuelve en un solo servidor de la organización: una clave de API de su organización integrada, un token OAuth de la organización que eligió al dar su consentimiento, y una herramienta solo ve los datos de esa organización.

### Tu papel decide lo que puedes hacer

La autenticación prueba *que* organización sobre la que se puede actuar, no *¿Qué* Las herramientas que administran la propia organización requieren el uso de la `owner` o
`admin` [función](/es/docs/settings#miembros-e-invitaciones) la misma puerta se aplica al salpicadero:

`update_org_settings` · `invite_member` · `remove_member` ·
`save_usage_report_config` · `set_voice_tool_access` · `delete_agent` ·
`set_findings_delivery` · `merge_findings` · `delete_finding` ·
`approve_finding_candidate` · `reject_finding_candidate` · `update_finding`
(Sólo cuando pases `title` los campos de clasificación permanecen abiertos a cualquier miembro)

`update_member_role` es más estricto aún: **Propietario solamente**, y se niega a cambiar su propio papel. `remove_member` También se niega a eliminar su propia membresía, sea cual sea su función, pregunte a otro propietario o administrador.

Un token perteneciente a `member` alcanza cada herramienta de lectura y cada escritura no administrativa, pero las herramientas anteriores regresan
`Only an organization owner or admin can perform this action.` En lugar de actuar (`update_member_role` devoluciones `Only an organization owner can perform this
action.`). Esto es cierto para ambos tipos de credenciales: una clave o token actúa como la persona detrás de ella, y esta puerta lee el papel de esa persona en el momento de la llamada en lugar de en el momento de la publicación. Para sacar una credencial del servicio por completo, revoquela: vea
[Claves de API](/es/docs/settings#claves-de-api). Quitar a esa persona de la organización (o prohibir su cuenta) hace lo mismo implícitamente: cada solicitud vuelve a verificar al propietario, por lo que sus claves y tokens OAuth dejan de funcionar en la próxima llamada.

### Alcance de lectura y escritura

Un cliente OAuth pide un alcance de acceso al dar el consentimiento, y el
servidor lo aplica antes de que se ejecute la herramienta:

* **`write`** — todas las herramientas, incluidas las que modifican datos.
  Implica `read`.
* **`read`** — solo las herramientas de lectura. Un token con alcance `read` que
  llama a una herramienta de escritura recibe un error de herramienta en lugar de
  un resultado:
  `This credential is read-only and cannot call "<tool>". Reconnect with the
  "write" scope to allow changes.` La llamada nunca llega a la herramienta, y el
  intento queda registrado en la actividad MCP de la organización.
* **Sin alcance de acceso** — los tokens emitidos antes de que existieran los
  alcances conservan acceso completo.

Las claves API tienen acceso completo; una clave no se restringe por alcance.
Sea cual sea la credencial, la restricción por rol
([Tu papel decide lo que puedes hacer](#tu-papel-decide-lo-que-puedes-hacer))
se aplica además.

Envíe un mensaje JSON-RPC por cada `POST /mcp`. Un lote (array) JSON-RPC que
contenga una invocación de herramienta se rechaza con `400`; los cuerpos de
solicitud de más de 4 MiB se rechazan con `413`.

## Herramientas

### Leer herramientas

| Herramienta | Entradas | Espejos |
| - | - | - |
| `health` | — | (prueba de humo con alcance orgánico) |
| `list_agents` | `limit?`, `cursor?` | `GET /v1/agents` |
| `get_agent` | `id` | `GET /v1/agents/[id]` |
| `list_conversations` | `agentId?`, `limit?`, `cursor?` | `GET /v1/conversations` |
| `get_conversation` | `id` | `GET /v1/conversations/[id]` |
| `get_transcript` | `conversationId` | `GET /v1/conversations/[id]/transcript` |
| `list_reviews` | `status?`, `limit?`, `cursor?` | `GET /v1/reviews` |
| `get_review` | `id` | `GET /v1/reviews/[id]` |
| `list_buckets` | `agentId?`, `limit?`, `cursor?` | `GET /v1/buckets` |
| `get_bucket` | `id` | `GET /v1/buckets/[id]` |
| `list_bucket_conversations` | `bucketId`, `limit?`, `cursor?` | `GET /v1/buckets/[id]/conversations` |
| `list_findings` | `status?`, `priority?`, `tags?`, `limit?`, `cursor?` | `GET /v1/findings` |
| `get_finding` | `id` | `GET /v1/findings/[id]` |
| `list_finding_conversations` | `findingId`, `limit?`, `cursor?` | `GET /v1/findings/[id]/conversations` |
| `list_finding_conversation_comments` | `findingId`, `conversationId` | `GET /v1/findings/[id]/conversations/[conversationId]/comments` |
| `list_experiments` | — | `GET /v1/experiments` |
| `list_experiment_monitor_groups` | — | `GET /v1/experiments/monitor-groups` |
| `get_experiment` | `id` | `GET /v1/experiments/[id]` |
| `get_experiment_evaluation` | `experimentId`, `runId` | `GET /v1/experiments/[id]/evaluations/[runId]` |
| `list_experiment_conversations` | `id`, `limit?` | `GET /v1/experiments/[id]/conversations` |
| `read_docs` | `path?` | (solo MCP) |

`read_docs` es solo MCP llámelo sin argumentos para listar cada página de documentación (slug + título + descripción), luego pase un `path` (p. ej.
`findings` o `integrations/slack`) para leer la página completa de Markdown.

`status` enums: opiniones aceptar `pending` / `reviewed` / `flagged`; hallazgos aceptar `open` / `acknowledged` / `resolved` / `ignored`. hallazgo `priority`
acepta `none` / `low` / `medium` / `high` / `urgent`.

### Escribir herramientas

| Herramienta | Entradas | Espejos |
| - | - | - |
| `create_ai_agent` | `name`, `description?`, `systemPrompt` | `POST /v1/agents` ai) |
| `create_human_agent` | `name`, `description?` | `POST /v1/agents` (humano) |
| `update_agent` | `id`, `name?`, `description?`, `systemPrompt?` | (solo MCP) |
| `flag_call_for_review` | `conversationId`, `notes?` | upserts `reviews.status = "pending"` para el llamado |
| `create_bucket` | `agentId`, `name`, `type?`, `filters?` | `POST /v1/buckets` |
| `add_conversation_to_bucket` | `bucketId`, `conversationId` | `POST /v1/buckets/[id]/conversations` |
| `remove_conversation_from_bucket` | `bucketId`, `conversationId` | `DELETE /v1/buckets/[id]/conversations/[conversationId]` |
| `create_finding` | `title`, `description?`, `priority?`, `tags?`, `findingType?` | `POST /v1/findings` |
| `update_finding` | `id`, `title?`, `description?`, `status?`, `priority?`, `tags?`, `findingType?`, `assigneeUserId?` | `PATCH /v1/findings/[id]` |
| `add_conversation_to_finding` | `findingId`, `conversationId` | `POST /v1/findings/[id]/conversations` |
| `preflight_experiment` | definición del experimento | `POST /v1/experiments/preflight` |
| `create_experiment` | definición del experimento, `monitorGroupId` o `newMonitorGroupName` opcional | `POST /v1/experiments` |
| `update_experiment_settings` | `id`, `settings` (objeto con los ajustes modificables) | `PATCH /v1/experiments/[id]` |
| `conclude_experiment` | `id` | `POST /v1/experiments/[id]/conclude` |
| `start_experiment_evaluation` | `id` | `POST /v1/experiments/[id]/evaluations` |
| `delete_experiment` | `id` | `DELETE /v1/experiments/[id]` |

<Note>
  `annotate_finding_conversation` (añadir una anotación de audio de autoría del sistema, opcionalmente a una llamada dentro de un hallazgo) requiere un **API key** y el `X-Organization-Id` cabecera no se puede llamar con una clave org estándar. Las claves org regulares pueden escribir la misma anotación sobre REST en
  `POST /v1/findings/[id]/conversations/[conversationId]/comments` (atribuido al usuario que llama), o leerlos a través de `list_finding_conversation_comments` y editar/eliminar con `update_finding_conversation_comment` /
  `delete_finding_conversation_comment`.
</Note>

Idempotente: `add_conversation_to_bucket`  `add_conversation_to_finding`
Devuelve la fila existente con `alreadyExisted: true` La conversación debe pertenecer al mismo agente que el cubo. `create_bucket`
acepta sólo `type: "static"` La creación de agente de IA ejecuta el indicador del sistema a través del flujo de auditoría antes de insertarlo.

`create_finding` presenta cada hallazgo como un **Candidato** revisión de la plataforma pendiente: no aparece en la lista de hallazgos de la organización y no se vincula automáticamente a las llamadas hasta que un administrador de la plataforma lo apruebe (o lo rechace) desde el **Candidatos** en la página de Hallazgos.

`update_agent` cambios solo los campos que pases enviar `description: null` Para limpiarlo, omita un campo para dejarlo intacto. `systemPrompt` es aceptado solo para agentes de IA (los agentes humanos no tienen ninguno) y está escrito tal cual: a diferencia de la creación, es
**no** El tipo y el proveedor de un agente son inmutables y no se pueden cambiar.

### Revisar colas

A **cola** es un conjunto guardado de filtros que definen una colección dinámica de conversaciones a revisar. Estas herramientas son solo MCP.

| Herramienta | Entradas | Espejos |
| - | - | - |
| `list_queues` | `limit?`, `cursor?` | (solo MCP) |
| `get_queue` | `id` | (solo MCP) |
| `list_queue_conversations` | `queueId`, `limit?`, `cursor?` | (solo MCP) |
| `create_queue` | `name`, `description?`, `filters?` | (solo MCP) |
| `update_queue` | `id`, `name?`, `description?`, `filters?` | (solo MCP) |
| `delete_queue` | `id` | (MCP-solamente, destructivo) |

Los `filters` objeto acepta: `agentIds`, `agentType` (`ai` / `human`),
`durationMinSeconds`, `durationMaxSeconds`, `endedReasons`, `dateFrom`
(`YYYY-MM-DD`), `dateTo` (`YYYY-MM-DD`), `alreadyReviewed`, `hasAudio`,
`isInteresting`, `findingTypes`. Un vacío/omitido `filters` coincide con cada conversación en la org. On `update_queue`, pasando `filters` **Reemplaza todo el objeto** no se fusione con la existente.

### Cambios

A **cambio** es una sugerencia atómica, agente-alcance que se dirige a un conjunto de hallazgos. Cada nuevo cambio comienza como un **proyecto** (no hay estado de flujo de trabajo, oculto de la lista principal) hasta que un humano lo publique. Estas herramientas son solo MCP.

<Note>
  Para la estabilidad de la API, los nombres de las herramientas MCP conservan el original `solution` término (`create_solution`, `list_solutions`, ...) aunque el producto ahora los llama **cambios**. Las herramientas y la interfaz de usuario operan en los mismos registros.
</Note>

| Herramienta | Entradas | Espejos |
| - | - | - |
| `list_solutions` | `agentId?`, `status?`, `draft?`, `limit?`, `cursor?` | (solo MCP) |
| `get_solution` | `id` | (solo MCP) |
| `list_solution_findings` | `solutionId` | (solo MCP) |
| `create_solution` | `agentId`, `findingIds`, `title?`, `description?`, `type?` | (solo MCP) |
| `update_solution` | `id`, `title?`, `description?`, `status?`, `assigneeUserId?` | (solo MCP) |
| `publish_solution` | `id` | (solo MCP) |
| `discard_solution` | `id` | (solo MCP) |
| `delete_solution` | `id` | (MCP-solamente, destructivo) |
| `link_finding_to_solution` | `solutionId`, `findingId` | (solo MCP) |
| `unlink_finding_from_solution` | `solutionId`, `findingId` | (solo MCP) |

`create_solution` insertos exactamente **uno** borrador por llamada nunca agrupe múltiples ideas en un solo cuerpo; llámelo de nuevo para cada sugerencia distinta. `status` es uno de `backlog` / `todo` /
`in_progress` / `done` / `cancelled`No puedes establecer `status` sobre un borrador: salir primero del borrador con `publish_solution` (→ `backlog`) o
`discard_solution` (→ `cancelled`). Eliminar un cambio elimina sus enlaces de hallazgo por cascada, pero nunca elimina los hallazgos subyacentes.

### Reportes

A **informe** es un analista de forma libre escrito en el mismo editor de texto enriquecido que Hallazgos y Cambios. `prompt` Sostiene la pregunta o breve; `description` mantiene el cuerpo como un documento JSON TipTap/ProseMirror.
`status` seguimiento del ciclo de vida de generación (`pending` / `generating` /
`completed` / `failed`) un reporte que creas se sienta en `pending` a menos que pases un cuerpo terminado y establecido `completed`. Estas herramientas son MCP-solamente.

| Herramienta | Entradas | Espejos |
| - | - | - |
| `list_reports` | `status?`, `limit?`, `cursor?` | (solo MCP) |
| `get_report` | `id` | (solo MCP) |
| `create_report` | `title`, `prompt?`, `description?`, `status?` | (solo MCP) |
| `update_report` | `id`, `title?`, `prompt?`, `description?`, `status?` | (solo MCP) |

En marcha `update_report`, pasando `description` **Reemplaza todo el cuerpo** no se fusione con el documento existente. Pase `prompt: null` para aclarar la petición.

### Población de cubo

Estas herramientas capturan las conversaciones en depósitos desde colas o filtros sin procesar.

| Herramienta | Entradas | Espejos |
| - | - | - |
| `create_bucket_from_queue` | `queueId`, `namePrefix?` | (solo MCP) |
| `populate_bucket_from_queue` | `bucketId`, `queueId` | (solo MCP) |
| `populate_bucket_from_filters` | `bucketId`, `filters` | (solo MCP) |

Debido a que las colas pueden abarcar múltiples agentes, pero los depósitos están agente-scopeados,
`create_bucket_from_queue` crea **un cubo por agente emparejado** y devuelve una matriz. `populate_*` Las herramientas son idempotentes la re-ejecución agrega cero filas nuevas y las coincidencias que pertenecen a un agente diferente al depósito se omiten y se cuentan en `skippedOtherAgentCount`.

### Mutaciones de cubo y Hallazgo

Las mutaciones restantes de solo MCP, más la desvinculación de conversación de Hallazgo que refleja un punto final de REST.

| Herramienta | Entradas | Espejos |
| - | - | - |
| `update_bucket` | `id`, `name?`, `type?`, `filters?` | (solo MCP) |
| `delete_bucket` | `id` | (MCP-solamente, destructivo) |
| `delete_finding` | `id` | (MCP-solamente, destructivo) |
| `remove_conversation_from_finding` | `findingId`, `conversationId` | `DELETE /v1/findings/[id]/conversations/[conversationId]` (destructivo) |
| `update_finding_conversation_comment` | `id`, `body?`, `annotationStartMs?`, `annotationEndMs?` | (solo MCP) |
| `delete_finding_conversation_comment` | `id` | (MCP-solamente, destructivo) |

`type` acepta sólo `"static"`. Cada eliminación en cascada sus propias filas de enlaces (tareas de cubo, enlaces de conversación de Hallazgo, comentarios) pero nunca elimina las conversaciones subyacentes.

### Importación de proveedores

Conecte un proveedor de voz y tire de sus agentes y llamadas directamente a Zelto lo mismo conecte el flujo de relleno de importación → → como **Configuración → Integraciones**Estas herramientas son solo MCP y cubren a todos los proveedores con capacidad de extracción: **Vapi**, **Retell**, **Speechify**, **Telnyx AI**, **ElevenLabs** y **Kapso** (WhatsApp). Cada uno toma un `provider` argumento (`vapi` / `retell` / `speechify` / `telnyx` /
`elevenlabs` / `kapso`).

| Herramienta | Entradas | Espejos |
| - | - | - |
| `connect_provider` | `provider`, `label?` | (solo MCP) |
| `check_provider_connection` | `token` | (solo MCP) |
| `list_provider_agents` | `provider`, `limit?` | (solo MCP) |
| `get_retell_agent` | `agentId` | (solo para MCP; incluye el mensaje actual) |
| `import_provider_agent` | `provider`, `agentId`, `sinceDays?` | (solo MCP) |
| `import_provider_conversations` | `provider`, `agentId`, `since` | (solo MCP) |

`connect_provider` utiliza un **Handoff del navegador para que la clave de la API nunca pase por el agente**: devuelve una sola vez `url` (válido 15 minutos). Usted entrega esa URL al usuario; la abren mientras inician sesión en Zelto y pegan su clave allí, por lo que la clave va directamente al servidor, nunca a su contexto o registros. **No le pidas al usuario su clave de API.** Cuando terminen, poll
`check_provider_connection` con el retorno `token` hasta `status` es
`completed` (Regresa `agentsFound`) o `expired` (comienzo). `label`
por defecto a `Default` y debe ser único por proveedor; el usuario puede cambiarlo en la página de conexión.

<Warning>
  Nunca acepte una clave de API de proveedor como argumento de herramienta, ya que se capturaría en los registros de conversación y cliente del agente. `connect_provider` es un traspaso exactamente por esta razón: la clave solo viaja al servidor → del navegador.
</Warning>

`list_provider_agents` devuelve cada agente/asistente en la(s) cuenta(s) conectada(s), cada una con anotaciones `alreadyImported` (y `importedAgentId` importados). `agentId` es el id externo del proveedor; para **Vapi** y **Telnyx AI** es el id del *asistente*; para **Kapso** es el `phone_number_id` de WhatsApp (cada número es un agente; consulta [Kapso](/es/docs/integrations/kapso)).

`get_retell_agent` lee un agente de Retell directamente sin importarlo. Devuelve el valor actual `general_prompt` para los agentes de LLM Retell y `global_prompt`
para agentes de flujo de conversación.

`import_provider_agent` importa un agente y **falla si ya se ha importado**: llama a `list_provider_agents` primero. Rellena las llamadas recientes del agente (`sinceDays`, por defecto 14, máx. 30) y lo inscribe en la importación automática continua, para que las nuevas llamadas sigan llegando sin otra extracción. `import_provider_conversations`
importa las llamadas de ese agente de `since` (una marca de tiempo ISO 8601, p. ej.
`2026-03-01T00:00:00Z`) hasta ahora, en segundo plano: el agente ya debe importarse y volver a ejecutarse con una ventana superpuesta es seguro (las llamadas ya importadas se omiten).

### Incorporación

Pon una nueva organización de punta a punta desde tu editor: conecta un proveedor de llamadas, crea un monitor y enruta pasillos. Estas herramientas son solo MCP. El [A bordo con un agente](/es/docs/onboarding-with-an-agent) guía camina un agente a través de todo el flujo de usarlos.

| Herramienta | Entradas | Espejos |
| - | - | - |
| `get_onboarding_status` | — | (solo MCP) |
| `list_integrations` | — | (solo MCP) |
| `connect_integration` | `provider`, `apiKey`, `label?` | (solo MCP) |
| `list_starter_monitors` | — | (solo MCP) |
| `create_monitor` | `name?`, `instruction?`, `starterKey?`, `agentIds?`, `companyIds?`, `metric?`, `modelTier?` | (solo MCP) |
| `list_monitors` | — | (solo MCP) |
| `set_findings_delivery` | `channels` | (solo MCP) |

Una carrera sin cabeza en orden:

1. `get_onboarding_status` leer `nextIncomplete` Reanudar desde el paso correcto.
2. `connect_integration` — `provider` es uno de `vapi`, `retell`, `speechify`,
   `telnyx`, `elevenlabs`, `kapso`; `apiKey` es la clave de ese proveedor. Para Vapi / Retell / Speechify la respuesta es `webhook.webhookUrl` debe pegarse en el panel del proveedor (un paso humano) antes de que fluyan las llamadas; ElevenLabs y Telnyx AI se sincronizan automáticamente, y Kapso registra su propio webhook en cada número de WhatsApp que importes con `import_provider_agent`. Confirma con `list_conversations`.
3. `create_monitor` pasar a `starterKey` Desde `list_starter_monitors`, o a
   `name` + un booleano de lenguaje natural `instruction`. Omitir tanto `agentIds` como `companyIds` lo aplica a todos los agentes actuales. Confirmar con `list_monitors`. Comprobaciones de ejecución de herramientas (`tool_check` lo hizo `submit_order` En realidad, el fuego es el autor
   [Monitores](/es/docs/monitors#comprobaciones-de-herramientas) editor; `create_monitor` todavía crea una rúbrica AI sí/no.
4. `set_findings_delivery` — `channels` ¿Es cualquiera de `email` / `slack` (Slack también necesita la aplicación de Slack conectada a través de OAuth en la interfaz web).

Estos son **escribir** herramientas (excepto la `list_*` / `get_*` leer) y devolver un objeto JSON que pueda llevar un `error` key inspeccione, y porque las escrituras se establecen de forma asíncrona, confirme cada paso con la herramienta de lectura emparejada antes de avanzar.

### monitores y cuadros de mando

Gestionar los jueces de IA que superficie hallazgos (`create_monitor` /
`list_monitors` / `list_starter_monitors` están bajo [Incorporación](#incorporación)).

| Herramienta | Entradas |
| - | - |
| `create_pipeline_monitor` | `name`, `pipeline`, `agentIds?`, `companyIds?`, `headlineStageId?`, `metric?`, `modelTier?`, `affectedScoreLine?`, `sampleRate?`, `affectedLabel?`, `notAffectedLabel?`, `affectedTone?`, `analysisStart?` monitor avanzado desde un canal explícito por etapas (filtros + `ai_analyze`/`flow_check`/`tool_check`), para cualquier cosa una sola rubrica `create_monitor` No puedo expresarlo. `tool_check`, llamada `list_agent_tools` primero y utilice los nombres exactos de las herramientas observadas. Pase `analysisStart` a `YYYY-MM-DD` Fecha UTC) para rellenar el historial de ese día para que los gráficos se completen de llamadas pasadas, limitadas por el nivel de la organización (una organización piloto: hasta 30 días / 1M llamadas; estándar: las llamadas más nuevas de  5,000); omítelo (o pasa el tiempo de espera). `now`) para comenzar con la siguiente llamada. Un histórico `analysisStart` requiere un propietario/administrador de la organización; se rechaza una fecha no válida o fuera de ventana. |
| `get_monitor` | `monitorId` (UUID) — obtiene la configuración completa del monitor: identidad, descripción, etiqueta del cliente, tipo, estado habilitado, versión, alcance por agentes/empresas y versiones fijadas de los agentes, pipeline/prompts y ajustes de las etapas, puntuación, etiquetas y tono de resultados, muestreo, proveedor/modelo, ajustes de audio y configuración de alertas. |
| `get_monitor_results` | `monitorId`, `limit?` (por defecto 20, máx. 100), `offset?` (por defecto 0), `filter?` (`all`/`affected`/`not_affected`) leer las salidas de un monitor: los recuentos exactos juzgados/afectados + tasa afectada (`summary`), y una página de veredictos por llamada con el razonamiento del modelo (`results`), más reciente-juzgado primero. Compruebe un monitor o confirme un relleno poblado. Los monitores booleanos reportan afectados/no afectados con las etiquetas del monitor y sin puntuación. |
| `update_monitor` | `id`, `name?`, `enabled?`, `customerLabel?`, `agentIds?`, `companyIds?`, `sampleRate?`, `stageContext?` — renombrar/pausar/etiquetar, reemplazar el conjunto de agentes (`[]` = todos los agentes de la organización; también para monitores de audio), reemplazar la selección de empresas, cambiar la tasa de muestreo (1–100) o editar las opciones de contexto de cada etapa de IA. Editar la rúbrica = borrar + `create_monitor` / `create_pipeline_monitor` |
| `set_monitor_enabled` | `id`, `enabled` |
| `delete_monitor` | `id` (idempotent) |
| `promote_finding_to_monitor` | `findingId`, `agentId` convertir un hallazgo en un monitor de pie |
| `save_monitor_alert` | `monitorId`, `enabled`, `comparator`, `threshold`, `windowDays`, `sustainedDays?`, `slackChannelId?`, `notifyEmails?` |
| `delete_monitor_alert` | `monitorId` (idempotent) |
| `save_scorecard` | `agentId`, `name`, `description?`, `criteria` crear/reemplazar una tarjeta de puntuación de agente |

Usa `list_monitors` para encontrar un ID y pásalo a `get_monitor` como
`monitorId`. Devuelve `{ monitor: { ...configuration, alert } }`. El pipeline
también se resuelve para monitores antiguos; las fechas (`analysisStartAt`,
`updatedAt`) son cadenas ISO y `sourceFindingId` identifica el hallazgo de origen
cuando existe. `alert` incluye el estado habilitado, comparador, umbral, ventana,
días sostenidos, ID del canal de Slack y destinatarios de correo; es `null` si
no hay una alerta configurada. Nunca se devuelven claves de API; `hasApiKey`
indica si hay una configurada. Las lecturas no usan caché y se limitan a tu
organización. Los IDs inexistentes o de otra organización devuelven un error de
monitor no encontrado. Usa `get_monitor_results` por separado para consultar
los resultados de las evaluaciones.

Pasa `companyIds` a `create_monitor`, `create_pipeline_monitor` o
`update_monitor` para evaluar llamadas atribuidas a las empresas seleccionadas,
incluidas las de futuros agentes. La función Empresas debe estar habilitada para
crear un alcance por empresas; los IDs deben pertenecer a tu organización y
se requiere al menos una empresa. No pases `agentIds` junto con `companyIds`.
Omitir ambos al actualizar conserva el alcance guardado; `list_monitors` expone
su `scopeType` y las `companies` seleccionadas. Cambiar las empresas modifica el
historial visible sin eliminar resultados guardados; las evaluaciones históricas
faltantes siguen requiriendo que actives expresamente el análisis.

Cada etapa `ai_analyze` de `create_pipeline_monitor` acepta `useAgentPrompt`
y `useCallContext` (datos CRM disponibles); ambos valen `false` en etapas nuevas.
Para editar el contexto, consulta los IDs con `get_monitor` y llama a `update_monitor`
con `stageContext: [{ stageId: "step-id", useAgentPrompt: false, useCallContext: true }]`.
Cada entrada requiere un ID único de etapa de IA existente y al menos una opción
booleana; las opciones omitidas se conservan. Todos los cambios se aplican de forma
atómica. Cambiar el contexto aumenta la versión para evaluaciones futuras y reinicia
el estado de incumplimiento de alertas; conserva los resultados históricos. La respuesta
incluye `version` y, si se envía contexto, el `pipeline` actualizado.

### Flujo de trabajo de Hallazgos

Más allá `create_finding` / `update_finding`, estos impulsan el ciclo de vida abierto y el dedup de → candidato.

| Herramienta | Entradas |
| - | - |
| `approve_finding_candidate` | `findingId` promover un candidato (por ejemplo, de `create_finding`) a un hallazgo abierto |
| `reject_finding_candidate` | `findingId` |
| `merge_findings` | `sourceFindingId`, `targetFindingId` devuelve el identificador de Hallazgo sobreviviente |
| `set_finding_version_scope` | `findingId`, `agentVersionId` (nulable) pin a un brazo A/B, o nulo para borrar |

Todo en esta tabla, excepto `set_finding_version_scope` requiere el `owner`
o `admin` El rol, como `delete_finding` y renombrando a través `update_finding`
Véase [Tu papel decide lo que puedes hacer](#tu-papel-decide-lo-que-puedes-hacer).

### Revisión de llamadas

`flag_call_for_review` solo pone en cola una llamada; estos registran la revisión real.

| Herramienta | Entradas |
| - | - |
| `review_call` | `conversationId`, `status?` (`pending`/`reviewed`/`flagged`), `notes?`, `result?`, `findings?`, `visibleToUsers?`, `bucketId?` |
| `mark_call_reviewed` | `conversationId` marcas revisadas sin abofetear a `flagged` estado |

### agentes (ciclo de vida)

`create_ai_agent` / `create_human_agent` / `update_agent` más:

| Herramienta | Entradas |
| - | - |
| `delete_agent` | `id` soft-delete, idempotente. Propietario/administrador [función](#tu-papel-decide-lo-que-puedes-hacer); los agentes sincronizados con el proveedor requieren además una clave de administración |
| `retry_agent_analyses` | `id` regenerar el gráfico de auditoría / flujo |
| `backfill_agent_prompt` | `id` jale el indicador del sistema del último webhook Vapi del agente |

`merge_agents` / `unmerge_agents` También existen pero requieren una clave de administrador (cross-org), que coincida con las herramientas de fusión solo de personal en la interfaz de usuario web.

### Receptores (números de teléfono)

| Herramienta | Entradas |
| - | - |
| `add_receiver_phone_number` | `receiverId`, `phoneNumber`, `label?` |
| `remove_receiver_phone_number` | `receiverId`, `phoneNumber` (Rechaza el primario) |
| `set_primary_receiver_phone_number` | `receiverId`, `phoneNumber` |
| `update_receiver_phone_label` | `receiverId`, `phoneNumber`, `label` (nullable) |
| `merge_receivers` | `sourceId`, `targetId` (mismo agente) |

### Integración & conectores

El proveedor conecta/importa bajo [Importación de proveedores](#importación-de-proveedores). Estos configuran una integración ya conectada.

| Herramienta | Entradas |
| - | - |
| `disconnect_integration` | `provider`, `id?` una cuenta, o todas para el proveedor |
| `set_voice_tool_access` | `provider`, `access` (`disabled`/`admins`/`everyone`) propietario/administrador [función](#tu-papel-decide-lo-que-puedes-hacer) |
| `set_elevenlabs_webhook_signing_secret` | `id`, `secret` (Despejados vacíos) |
| `connect_google_chat` | `webhookUrl` |
| `disconnect_google_chat` | — |

**Slack** (post-connect; la instalación de OAuth permanece en la interfaz web): `add_slack_channel`,
`remove_slack_channel`, `set_default_slack_channel`,
`set_slack_channel_chat_enabled`, `send_slack_channel_test`,
`set_agent_slack_channel` cada uno toma un identificador de canal de Slack (`C…`), y
`set_agent_slack_channel` También un `agentId`.

**Linear** (post-connect; la instalación de OAuth permanece en la interfaz web):
`list_linear_teams`, `set_default_linear_team` (`teamId`, nullable),
`create_linear_issue_for_finding` (`findingId`),
`create_linear_issue_for_solution` (`solutionId`), `unlink_linear_issue`
(`findingId?` / `solutionId?`).

### Organización & Miembros

| Herramienta | Entradas |
| - | - |
| `update_org_settings` | `name?`, `timezone?`, `defaultLocale?` |
| `invite_member` | `email`, `role` |
| `remove_member` | `memberId` otro miembro; se rechazan tanto el último propietario como la autoextracción |
| `update_member_role` | `memberId`, `role` de otro miembro; **Propietario solamente** |
| `save_usage_report_config` | campos de configuración de usement-reporte |
| `upload_conversation` | `agentId`, `name`, `turns?` y/o `transcript?`, `referenceId?`, `language?` Ingerir una llamada desde una pila no compatible (solo transcripción; la carga de audio permanece en la interfaz de usuario web) |

Todas las herramientas de esta tabla excepto `upload_conversation` requiere el `owner` o
`admin` papel, y `update_member_role` requiere `owner` Véase [Tu papel decide lo que puedes hacer](#tu-papel-decide-lo-que-puedes-hacer).

Las entradas anteriores son los campos primarios; el servidor MCP anuncia el esquema completo y autorizado para cada herramienta a través de `tools/list`.

Las entradas de correo electrónico utilizan patrones de esquema JSON en lenguaje regular, por lo que los esquemas de herramientas anunciados siguen siendo compatibles con proveedores de salida estructurada estrictos, incluido OpenAI.

### Formas de salida y paginación

Las respuestas de la herramienta coinciden exactamente con la API REST.
[Referencia API](/es/api-reference/agents/list-agents) para las formas JSON de `Agent`,
`Conversation`, `Transcript`, `Review`, `Bucket`, y `Finding`, más el `{ data, nextCursor }` sobre de paginación.

`limit` 200 (por defecto 50). `cursor` es opaco devolver el
`nextCursor` valor de una respuesta anterior para buscar la página siguiente.

## Solución de problemas

* **`401` de cada herramienta** el token portador está equivocado o revocado. Pruebe la clave directamente: `curl -H "Authorization: Bearer
  $ZELTO_API_KEY" https://api.zelto.ai/v1/agents`. Si eso también regresa `401`, menta una nueva llave.
* **`This credential is read-only and cannot call "<tool>".`** — al token OAuth
  solo se le concedió el alcance `read`. Vuelva a conectar y conceda `write`, o
  use una clave API. Vea
  [Alcance de lectura y escritura](#alcance-de-lectura-y-escritura).
* **`400` con `Batched tool calls are not supported`** — el cliente envió un
  array JSON-RPC. Envíe un mensaje por `POST`.
* **`Only an organization owner or admin can perform this action.`** la herramienta funcionó, tu rol no. Tu credencial se resuelve en la `member` Pídale a un propietario o administrador que lo ejecute o que eleve su rol; vea la sección de la sección de administración de la página. [Tu papel decide lo que puedes hacer](#tu-papel-decide-lo-que-puedes-hacer).
* **La lista de herramientas está vacía en el cliente** la mayoría de los clientes almacenan en caché la lista de herramientas. Reiniciar el cliente (Claude Code: `/mcp`; Cursor: activar/desactivar el servidor; Codex: reiniciar la CLI).
* **`429` tasa limitada** retroceder y volver a intentarlo. Utilice el `cursor`
  paginación en lugar de buscar páginas grandes.
* **Acceso a Cross-org denegado** las claves están incluidas en la organización en la que fueron acuñadas. Cambiar de organización en la aplicación web y acuñar una nueva clave de esa organización **Configuración → Integraciones**.

## Acceso a grabaciones

Los campos de URL de grabación apuntan a rutas de reproducción autenticadas.
Envía la misma clave de API de la organización o token OAuth al solicitar audio;
el navegador requiere una sesión con membresía vigente. Esto se aplica a las
grabaciones mixtas y multicanal. Las grabaciones almacenadas por Zelto redirigen
a URL firmadas que caducan a los 15 minutos. Sigue la redirección para reproducir
o descargar; cuando caduque, solicita de nuevo la ruta autenticada original.
Las URL públicas históricas dejan de funcionar al activar el almacenamiento privado.