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

# MCP Server

> Use Avala con Claude, Claude Code, Cursor, VS Code y ChatGPT a traves del Model Context Protocol

El [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) es un estandar abierto que permite a los asistentes de IA interactuar con herramientas y fuentes de datos externas. El MCP server de Avala expone sus datasets, proyectos y exportaciones como herramientas que cualquier cliente compatible con MCP puede invocar, permitiendole gestionar su flujo de trabajo de anotacion mediante lenguaje natural sin cambiar de contexto.

Esto significa que puede pedirle a Claude que "liste todos mis datasets", hacer que Cursor cree una exportacion, o usar VS Code para verificar el estado de un proyecto — todo impulsado por la misma API de Avala que ya utiliza.

## Requisitos previos

* **Node.js** 18 o posterior instalado en su maquina
* Una **clave API de Avala** (genere una en [Mission Control](https://avala.ai/settings?section=security) en **Settings > Security**)

## Configuracion

### Claude Desktop

Abra su archivo de configuracion de Claude Desktop:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Agregue el MCP server de Avala:

<Warning>
  Nunca haga commit de archivos de configuracion que contengan claves API reales en el control de versiones. Defina `AVALA_API_KEY` como una variable de entorno del sistema, o reemplace `"your-api-key"` con su clave real localmente y asegurese de que el archivo de configuracion este en su `.gitignore`.
</Warning>

```json theme={null}
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Reinicie Claude Desktop. Deberia ver las herramientas de Avala disponibles en el selector de herramientas.

### Cursor

Cree o edite `.cursor/mcp.json` en la raiz de su proyecto (o en el directorio de configuracion global):

<Warning>
  `.cursor/mcp.json` se encuentra en la raiz de su proyecto y puede ser incluido en git. Agreguelo a su `.gitignore` o defina `AVALA_API_KEY` como una variable de entorno del sistema en lugar de colocarla directamente en el archivo de configuracion.
</Warning>

```json theme={null}
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Reinicie Cursor o recargue la ventana. Las herramientas de Avala apareceran en el modo agente de Cursor.

### VS Code

Cree o edite `.vscode/mcp.json` en su espacio de trabajo:

<Warning>
  `.vscode/mcp.json` se encuentra en su espacio de trabajo y puede ser incluido en git. Agreguelo a su `.gitignore` o defina `AVALA_API_KEY` como una variable de entorno del sistema en lugar de colocarla directamente en el archivo de configuracion.
</Warning>

```json theme={null}
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Asegurese de tener la extension [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) instalada con el soporte MCP habilitado. Reinicie VS Code para que reconozca el nuevo servidor.

### Claude Code

Agregue el MCP server de Avala a Claude Code con un solo comando:

```bash theme={null}
claude mcp add avala -- npx -y @avala-ai/mcp-server
```

Defina su clave API como variable de entorno:

```bash theme={null}
export AVALA_API_KEY="your-api-key"
```

Reinicie Claude Code. Las herramientas de Avala estaran disponibles en su sesion.

### ChatGPT

<Info>
  El soporte MCP de ChatGPT esta en evolucion. Consulte la
  [documentacion de OpenAI](https://platform.openai.com/docs) para las ultimas
  instrucciones de configuracion y disponibilidad en su plan y region.
</Info>

## Modo de seguridad MCP

Por seguridad, el MCP server es de solo lectura por defecto. Las herramientas de mutacion no se registran a menos que las habilite explicitamente con:

```bash theme={null}
AVALA_MCP_ENABLE_MUTATIONS=true
```

Esta variable de entorno puede definirse en el entorno de proceso de su MCP server antes de iniciarlo.

Por defecto, las siguientes operaciones de escritura/eliminacion estan bloqueadas:

* `create_dataset`
* `create_agent`, `delete_agent`
* `create_annotation_issue`, `update_annotation_issue`, `delete_annotation_issue`
* `create_storage_config`, `test_storage_config`, `delete_storage_config`
* `create_webhook`, `delete_webhook`
* `create_export`
* `evaluate_quality`
* `compute_consensus`
* `fleet_register_device`, `fleet_acknowledge_alert`

## Herramientas MCP disponibles

Una vez conectado, las siguientes herramientas estan disponibles para el asistente de IA:

| Herramienta                          | Descripcion                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `list_datasets`                      | Listar todos los datasets en su espacio de trabajo.                                                          |
| `get_dataset`                        | Obtener detalles de un dataset especifico.                                                                   |
| `create_dataset`                     | Crear un nuevo dataset para anotacion. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `list_projects`                      | Listar todos los proyectos de anotacion.                                                                     |
| `get_project`                        | Obtener los detalles completos de un proyecto.                                                               |
| `create_export`                      | Iniciar una nueva exportacion para un dataset o proyecto. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*     |
| `get_export_status`                  | Verificar el estado de una exportacion.                                                                      |
| `list_exports`                       | Listar todas las exportaciones.                                                                              |
| `get_workspace_stats`                | Obtener un resumen de uso del espacio de trabajo.                                                            |
| `list_tasks`                         | Listar tareas con filtrado opcional.                                                                         |
| `get_task`                           | Obtener detalles de una tarea.                                                                               |
| `list_agents`                        | Listar agentes de automatizacion.                                                                            |
| `get_agent`                          | Obtener detalles de un agente.                                                                               |
| `create_agent`                       | Crear un nuevo agente de automatizacion. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                      |
| `delete_agent`                       | Eliminar un agente. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                           |
| `list_webhooks`                      | Listar suscripciones de webhook.                                                                             |
| `create_webhook`                     | Crear una suscripcion de webhook. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                             |
| `delete_webhook`                     | Eliminar un webhook. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                          |
| `list_storage_configs`               | Listar configuraciones de almacenamiento.                                                                    |
| `create_storage_config`              | Crear una configuracion de almacenamiento. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                    |
| `test_storage_config`                | Probar la conectividad de almacenamiento. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                     |
| `delete_storage_config`              | Eliminar una configuracion de almacenamiento. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                 |
| `list_quality_targets`               | Listar objetivos de calidad de un proyecto.                                                                  |
| `evaluate_quality`                   | Evaluar objetivos de calidad. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                 |
| `get_consensus_summary`              | Obtener el resumen de consenso de un proyecto.                                                               |
| `compute_consensus`                  | Iniciar el calculo de consenso. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                               |
| `list_organizations`                 | Listar organizaciones.                                                                                       |
| `get_organization`                   | Obtener detalles de una organizacion.                                                                        |
| `list_slices`                        | Listar slices de un propietario.                                                                             |
| `get_slice`                          | Obtener detalles de un slice.                                                                                |
| `list_annotation_issues_by_sequence` | Listar problemas de anotacion de una secuencia.                                                              |
| `create_annotation_issue`            | Crear un nuevo problema de anotacion. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                         |
| `update_annotation_issue`            | Actualizar un problema de anotacion. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                          |
| `delete_annotation_issue`            | Eliminar un problema de anotacion. *(requiere `AVALA_MCP_ENABLE_MUTATIONS=true`)*                            |
| `list_annotation_issues_by_dataset`  | Listar problemas de anotacion de un dataset.                                                                 |
| `get_annotation_issue_metrics`       | Obtener metricas de problemas de un dataset.                                                                 |
| `list_qc_tools`                      | Listar herramientas QC disponibles.                                                                          |

### Fleet (Vista previa)

<Info>
  Las herramientas Fleet estan en vista previa y pueden cambiar. Proporcionan acceso de lectura y escritura a dispositivos, grabaciones, eventos, alertas y reglas de la flota.
</Info>

| Herramienta               | Descripcion                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `fleet_list_devices`      | Listar dispositivos de la flota con filtros opcionales.                                                        |
| `fleet_get_device`        | Obtener informacion detallada de un dispositivo de la flota.                                                   |
| `fleet_list_recordings`   | Listar grabaciones de la flota con filtros opcionales.                                                         |
| `fleet_get_recording`     | Obtener informacion detallada de una grabacion.                                                                |
| `fleet_list_events`       | Listar eventos de la flota con filtros opcionales.                                                             |
| `fleet_list_alerts`       | Listar alertas de la flota con filtros opcionales.                                                             |
| `fleet_list_rules`        | Listar reglas de la flota con filtros opcionales.                                                              |
| `fleet_register_device`   | Registrar un nuevo dispositivo de flota. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `fleet_acknowledge_alert` | Confirmar una alerta de flota. <span className="text-orange-500 text-xs font-medium">mutation</span>           |

## Definiciones de herramientas

Esquemas detallados para cada herramienta MCP. Todas las herramientas devuelven JSON como contenido de texto.

### list\_datasets

Lista todos los datasets en el espacio de trabajo.

**Parameters:**

* `dataType` (string, optional) — Filtrar por tipo de datos (`image`, `video`, `lidar`, `mcap`, `splat`)
* `name` (string, optional) — Filtrar por nombre de dataset (coincidencia parcial)
* `status` (string, optional) — Filtrar por estado del dataset
* `visibility` (string, optional) — Filtrar por visibilidad (`private` o `public`)
* `limit` (number, optional) — Numero maximo de datasets a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

**Ejemplo de respuesta:**

```json theme={null}
{
  "datasets": [
    {
      "uid": "d8f2e1a4-3b7c-4e9f-a1d6-5c8b9e0f2a3d",
      "name": "Urban Driving Q1",
      "slug": "urban-driving-q1",
      "dataType": "lidar",
      "itemCount": 12450,
      "visibility": "private",
      "status": "active",
      "createdAt": "2026-01-15T08:30:00Z"
    },
    {
      "uid": "a1b2c3d4-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
      "name": "Warehouse Cameras",
      "slug": "warehouse-cameras",
      "dataType": "image",
      "itemCount": 34200,
      "visibility": "private",
      "status": "active",
      "createdAt": "2026-02-20T14:15:00Z"
    }
  ],
  "cursor": "eyJpZCI6MTAwfQ=="
}
```

### get\_dataset

Obtiene los detalles de un dataset especifico.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) del dataset

**Ejemplo de respuesta:**

```json theme={null}
{
  "uid": "d8f2e1a4-3b7c-4e9f-a1d6-5c8b9e0f2a3d",
  "name": "Urban Driving Q1",
  "slug": "urban-driving-q1",
  "dataType": "lidar",
  "itemCount": 12450,
  "sequenceCount": 85,
  "visibility": "private",
  "status": "active",
  "owner": "acme-robotics",
  "createdAt": "2026-01-15T08:30:00Z",
  "updatedAt": "2026-03-10T11:45:00Z"
}
```

**Respuesta de error (UID invalido):**

```json theme={null}
{
  "error": "not_found",
  "message": "Dataset with UID 'invalid-uid-here' was not found.",
  "status": 404
}
```

### list\_projects

Lista todos los proyectos de anotacion.

**Parameters:**

* `limit` (number, optional) — Numero maximo de proyectos a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### get\_project

Obtiene los detalles de un proyecto especifico.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) del proyecto

### create\_dataset

Crea un nuevo dataset para anotacion.

**Parameters:**

* `name` (string, required) — Nombre para mostrar del dataset
* `slug` (string, required) — Identificador compatible con URL para el dataset
* `dataType` (string, required) — Tipo de datos: `image`, `video`, `lidar` o `mcap`
* `visibility` (string, optional) — Visibilidad del dataset: `private` o `public` (por defecto: `private`)
* `createMetadata` (boolean, optional) — Si se deben crear los metadatos del dataset (por defecto: true)
* `providerConfig` (object, optional) — Configuracion del proveedor de almacenamiento en la nube
* `ownerName` (string, optional) — Nombre de usuario o correo electronico del propietario del dataset

### create\_export

Inicia una nueva exportacion para un dataset o proyecto.

**Parameters:**

* `project` (string, optional) — UID del proyecto a exportar
* `dataset` (string, optional) — UID del dataset a exportar

**Ejemplo de respuesta:**

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "pending",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "createdAt": "2026-03-19T10:00:00Z"
}
```

### get\_export\_status

Verifica el estado de una exportacion.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) de la exportacion

**Ejemplo de respuesta:**

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "completed",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "downloadUrl": "https://api.avala.ai/exports/e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9/download",
  "fileSize": 52428800,
  "createdAt": "2026-03-19T10:00:00Z",
  "completedAt": "2026-03-19T10:02:34Z"
}
```

### list\_exports

Lista todas las exportaciones en el espacio de trabajo.

**Parameters:**

* `limit` (number, optional) — Numero maximo de exportaciones a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### get\_workspace\_stats

Obtiene un resumen rapido del contenido del espacio de trabajo (datasets, proyectos, exportaciones).

**Parameters:** Ninguno

**Ejemplo de respuesta:**

```json theme={null}
{
  "datasets": 14,
  "projects": 7,
  "exports": 23,
  "tasks": {
    "total": 8420,
    "pending": 312,
    "completed": 7856,
    "inProgress": 252
  },
  "members": 18
}
```

### list\_tasks

Lista tareas con filtrado opcional por proyecto o estado.

**Parameters:**

* `project` (string, optional) — Filtrar por UID de proyecto
* `status` (string, optional) — Filtrar por estado de tarea
* `limit` (number, optional) — Numero maximo de tareas a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

**Ejemplo de respuesta:**

```json theme={null}
{
  "tasks": [
    {
      "uid": "t1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6",
      "status": "completed",
      "project": "770a9600-a40d-63f6-c938-668877660000",
      "assignee": "jane.doe@acme.com",
      "completedAt": "2026-03-18T16:30:00Z"
    },
    {
      "uid": "t7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2",
      "status": "pending",
      "project": "770a9600-a40d-63f6-c938-668877660000",
      "assignee": null,
      "completedAt": null
    }
  ],
  "cursor": "eyJ0YXNrSWQiOjUwfQ=="
}
```

### get\_task

Obtiene informacion detallada sobre una tarea especifica.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) de la tarea

### list\_agents

Lista todos los agentes de automatizacion configurados en su espacio de trabajo.

**Parameters:**

* `limit` (number, optional) — Numero maximo de agentes a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### get\_agent

Obtiene informacion detallada sobre un agente de automatizacion especifico.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) del agente

### create\_agent

Crea un nuevo agente de automatizacion con suscripciones a eventos y una URL de devolucion de llamada.

**Parameters:**

* `name` (string, required) — Nombre del agente
* `events` (string\[], required) — Lista de tipos de eventos a los que el agente se suscribe
* `callbackUrl` (string, optional) — URL para recibir devoluciones de llamada de eventos
* `description` (string, optional) — Descripcion del agente
* `project` (string, optional) — UID del proyecto para limitar el alcance del agente
* `taskTypes` (string\[], optional) — Tipos de tareas que maneja el agente

### delete\_agent

Elimina un agente de automatizacion por su UID.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) del agente a eliminar

### list\_webhooks

Lista todas las suscripciones de webhook en su espacio de trabajo.

**Parameters:**

* `limit` (number, optional) — Numero maximo de webhooks a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### create\_webhook

Crea una nueva suscripcion de webhook para eventos especificos.

**Parameters:**

* `targetUrl` (string, required) — URL para recibir entregas de webhook
* `events` (string\[], required) — Lista de tipos de eventos a los que suscribirse

### delete\_webhook

Elimina una suscripcion de webhook por su UID.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) del webhook a eliminar

### list\_storage\_configs

Lista todas las configuraciones de almacenamiento en su espacio de trabajo.

**Parameters:**

* `limit` (number, optional) — Numero maximo de configuraciones de almacenamiento a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### create\_storage\_config

Crea una nueva configuracion de almacenamiento (S3 o Google Cloud Storage).

**Parameters:**

* `name` (string, required) — Nombre para la configuracion de almacenamiento
* `provider` (string, required) — Tipo de proveedor de almacenamiento (`s3` o `gcs`)
* `s3BucketName` (string, optional) — Nombre del bucket S3
* `s3BucketRegion` (string, optional) — Region del bucket S3
* `s3BucketPrefix` (string, optional) — Prefijo de clave S3
* `s3AccessKeyId` (string, optional) — ID de clave de acceso S3 (almacenado de forma segura en el servidor)
* `s3SecretAccessKey` (string, optional) — Clave de acceso secreta S3 (almacenada de forma segura en el servidor)
* `s3IsAccelerated` (boolean, optional) — Habilitar S3 Transfer Acceleration
* `gcStorageBucketName` (string, optional) — Nombre del bucket de Google Cloud Storage
* `gcStoragePrefix` (string, optional) — Prefijo de Google Cloud Storage
* `gcStorageAuthJsonContent` (string, optional) — Credenciales JSON de la cuenta de servicio GCS (almacenadas de forma segura en el servidor)

### test\_storage\_config

Prueba la conectividad de una configuracion de almacenamiento.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) de la configuracion de almacenamiento a probar

### delete\_storage\_config

Elimina una configuracion de almacenamiento por su UID.

**Parameters:**

* `uid` (string, required) — El identificador unico (UUID) de la configuracion de almacenamiento a eliminar

### list\_quality\_targets

Lista los objetivos de calidad configurados para un proyecto especifico.

**Parameters:**

* `projectUid` (string, required) — El identificador unico (UUID) del proyecto
* `limit` (number, optional) — Numero maximo de objetivos de calidad a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### evaluate\_quality

Evalua todos los objetivos de calidad de un proyecto y devuelve su estado actual.

**Parameters:**

* `projectUid` (string, required) — El identificador unico (UUID) del proyecto a evaluar

### get\_consensus\_summary

Obtiene un resumen de consenso para un proyecto que incluye puntuaciones medias/medianas y distribucion.

**Parameters:**

* `projectUid` (string, required) — El identificador unico (UUID) del proyecto

### compute\_consensus

Inicia el calculo de consenso para un proyecto.

**Parameters:**

* `projectUid` (string, required) — El identificador unico (UUID) del proyecto

### list\_organizations

Lista todas las organizaciones de las que es miembro.

**Parameters:**

* `limit` (number, optional) — Numero maximo de organizaciones a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### get\_organization

Obtiene informacion detallada sobre una organizacion especifica.

**Parameters:**

* `slug` (string, required) — El identificador slug de la organizacion

### list\_slices

Lista los slices de un propietario (usuario u organizacion).

**Parameters:**

* `owner` (string, required) — Nombre del propietario (slug de usuario u organizacion)
* `limit` (number, optional) — Numero maximo de slices a devolver
* `cursor` (string, optional) — Cursor de paginacion de una solicitud anterior

### get\_slice

Obtiene informacion detallada sobre un slice especifico.

**Parameters:**

* `owner` (string, required) — Nombre del propietario (slug de usuario u organizacion)
* `slug` (string, required) — El slug del slice

### list\_annotation\_issues\_by\_sequence

Lista todos los problemas de anotacion de una secuencia especifica.

**Parameters:**

* `sequenceUid` (string, required) — El UUID de la secuencia
* `datasetItemUid` (string, optional) — Filtrar por UUID del elemento de dataset
* `projectUid` (string, optional) — Filtrar por UUID del proyecto

### create\_annotation\_issue

Crea un nuevo problema de anotacion en una secuencia.

**Parameters:**

* `sequenceUid` (string, required) — El UUID de la secuencia
* `toolUid` (string, required) — UUID de la herramienta de anotacion
* `problemUid` (string, required) — UUID del tipo de problema
* `datasetItemUid` (string, optional) — UUID del elemento de dataset
* `projectUid` (string, optional) — UUID del proyecto
* `priority` (string, optional) — Nivel de prioridad: `lowest`, `low`, `medium`, `high`, `highest`
* `severity` (string, optional) — Nivel de severidad: `critical`, `moderate`
* `description` (string, optional) — Descripcion del problema
* `wrongClass` (string, optional) — Etiqueta de clase incorrecta
* `correctClass` (string, optional) — Etiqueta de clase correcta
* `objectUid` (string, optional) — UUID del objeto de anotacion
* `shouldReAnnotate` (boolean, optional) — Si se debe re-anotar
* `shouldDelete` (boolean, optional) — Si se debe eliminar la anotacion
* `framesAffected` (string, optional) — Fotogramas afectados por el problema

### update\_annotation\_issue

Actualiza un problema de anotacion existente (estado, prioridad, etc.).

**Parameters:**

* `sequenceUid` (string, required) — El UUID de la secuencia
* `issueUid` (string, required) — El UUID del problema de anotacion
* `status` (string, optional) — Estado: `open`, `relabeling`, `in_review`, `completed`, `cant_reproduce`, `awaiting_feedback`, `no_action_taken`
* `priority` (string, optional) — Nivel de prioridad: `lowest`, `low`, `medium`, `high`, `highest`
* `severity` (string, optional) — Nivel de severidad: `critical`, `moderate`
* `description` (string, optional) — Descripcion actualizada
* `toolUid` (string, optional) — UUID de la herramienta de anotacion
* `problemUid` (string, optional) — UUID del tipo de problema
* `wrongClass` (string, optional) — Etiqueta de clase incorrecta
* `framesAffected` (string, optional) — Fotogramas afectados por el problema

### delete\_annotation\_issue

Elimina un problema de anotacion.

**Parameters:**

* `sequenceUid` (string, required) — El UUID de la secuencia
* `issueUid` (string, required) — El UUID del problema de anotacion a eliminar

### list\_annotation\_issues\_by\_dataset

Lista todos los problemas de anotacion de un dataset.

**Parameters:**

* `owner` (string, required) — Nombre de usuario del propietario del dataset
* `datasetSlug` (string, required) — Slug del dataset
* `sequenceUid` (string, optional) — Filtrar por UUID de secuencia

### get\_annotation\_issue\_metrics

Obtiene metricas agregadas de problemas de anotacion de un dataset (conteos por estado/prioridad/severidad, tiempos de cierre).

**Parameters:**

* `owner` (string, required) — Nombre de usuario del propietario del dataset
* `datasetSlug` (string, required) — Slug del dataset
* `sequenceUid` (string, optional) — Filtrar por UUID de secuencia

### list\_qc\_tools

Lista las herramientas QC de anotacion disponibles para un tipo de dataset dado.

**Parameters:**

* `datasetType` (string, required) — El tipo de dataset (ej. `lidar`, `image`, `video`)

### fleet\_list\_devices

Lista los dispositivos de la flota con filtros opcionales.

**Parameters:**

* `status` (string, optional) — Filtrar por estado del dispositivo (`online`, `offline`, `maintenance`)
* `type` (string, optional) — Filtrar por tipo de dispositivo
* `limit` (number, optional) — Numero maximo de dispositivos a devolver
* `cursor` (string, optional) — Cursor de paginacion

**Ejemplo de respuesta:**

```json theme={null}
{
  "devices": [
    {
      "uid": "dev-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Forklift Sensor Unit 12",
      "type": "lidar-sensor",
      "status": "online",
      "firmwareVersion": "2.4.1",
      "lastSeenAt": "2026-03-19T09:55:00Z",
      "tags": ["warehouse-a", "forklift"]
    },
    {
      "uid": "dev-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Dock Camera 3",
      "type": "camera",
      "status": "offline",
      "firmwareVersion": "1.8.0",
      "lastSeenAt": "2026-03-18T23:10:00Z",
      "tags": ["dock", "exterior"]
    }
  ],
  "cursor": "eyJkZXZpY2VJZCI6MjB9"
}
```

### fleet\_get\_device

Obtiene informacion detallada sobre un dispositivo de flota especifico.

**Parameters:**

* `uid` (string, required) — El identificador unico del dispositivo

### fleet\_list\_recordings

Lista las grabaciones de la flota con filtros opcionales.

**Parameters:**

* `device` (string, optional) — Filtrar por UID de dispositivo
* `status` (string, optional) — Filtrar por estado de grabacion
* `limit` (number, optional) — Numero maximo de grabaciones a devolver
* `cursor` (string, optional) — Cursor de paginacion

### fleet\_get\_recording

Obtiene informacion detallada sobre una grabacion especifica.

**Parameters:**

* `uid` (string, required) — El identificador unico de la grabacion

### fleet\_list\_events

Lista los eventos de la flota con filtros opcionales.

**Parameters:**

* `recording` (string, optional) — Filtrar por UID de grabacion
* `device` (string, optional) — Filtrar por UID de dispositivo
* `type` (string, optional) — Filtrar por tipo de evento
* `severity` (string, optional) — Filtrar por severidad
* `limit` (number, optional) — Numero maximo de eventos a devolver
* `cursor` (string, optional) — Cursor de paginacion

### fleet\_list\_alerts

Lista las alertas de la flota con filtros opcionales.

**Parameters:**

* `status` (string, optional) — Filtrar por estado de alerta (`open`, `acknowledged`, `resolved`)
* `severity` (string, optional) — Filtrar por severidad (`info`, `warning`, `error`, `critical`)
* `device` (string, optional) — Filtrar por UID de dispositivo
* `rule` (string, optional) — Filtrar por UID de regla
* `limit` (number, optional) — Numero maximo de alertas a devolver
* `cursor` (string, optional) — Cursor de paginacion

**Ejemplo de respuesta:**

```json theme={null}
{
  "alerts": [
    {
      "uid": "alert-c3d4e5f6-a7b8-9012-cdef-123456789012",
      "status": "open",
      "severity": "warning",
      "device": "dev-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rule": "rule-d4e5f6a7-b8c9-0123-defa-234567890123",
      "message": "Device temperature exceeded threshold (72C)",
      "createdAt": "2026-03-19T08:45:00Z"
    },
    {
      "uid": "alert-e5f6a7b8-c9d0-1234-efab-345678901234",
      "status": "acknowledged",
      "severity": "critical",
      "device": "dev-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "rule": "rule-f6a7b8c9-d0e1-2345-fabc-456789012345",
      "message": "Device offline for more than 24 hours",
      "createdAt": "2026-03-18T09:00:00Z",
      "acknowledgedAt": "2026-03-18T10:30:00Z"
    }
  ],
  "cursor": "eyJhbGVydElkIjoxMH0="
}
```

### fleet\_list\_rules

Lista las reglas de la flota con filtros opcionales.

**Parameters:**

* `enabled` (boolean, optional) — Filtrar por estado de habilitacion
* `limit` (number, optional) — Numero maximo de reglas a devolver
* `cursor` (string, optional) — Cursor de paginacion

### fleet\_register\_device

Registra un nuevo dispositivo de flota.

**Parameters:**

* `name` (string, required) — Nombre del dispositivo
* `type` (string, required) — Tipo del dispositivo
* `firmwareVersion` (string, optional) — Version del firmware
* `tags` (string\[], optional) — Etiquetas para el dispositivo

### fleet\_acknowledge\_alert

Confirma una alerta de flota.

**Parameters:**

* `uid` (string, required) — El identificador unico de la alerta a confirmar

## Recetas

Flujos de trabajo de varios pasos que puede ejecutar mediante lenguaje natural. Cada receta muestra las llamadas a herramientas que el asistente realiza en segundo plano.

### Receta 1: Revision de salud de datasets

Pregunte a su asistente: *"Dame una revision de salud de mi espacio de trabajo — cuantos datasets tengo y cuales tienen mas elementos?"*

**Paso 1** — El asistente llama a `get_workspace_stats` para obtener la vision general.

```json theme={null}
{
  "datasets": 14,
  "projects": 7,
  "exports": 23,
  "tasks": { "total": 8420, "pending": 312, "completed": 7856, "inProgress": 252 },
  "members": 18
}
```

**Paso 2** — El asistente llama a `list_datasets` con `limit: 50` para obtener todos los datasets.

**Paso 3** — El asistente ordena los resultados por `itemCount` y presenta un resumen clasificado:

> Tiene 14 datasets. Los tres mas grandes son:
>
> 1. **Warehouse Cameras** — 34.200 elementos (image)
> 2. **Urban Driving Q1** — 12.450 elementos (lidar)
> 3. **Parking Lot Footage** — 8.900 elementos (video)

### Receta 2: Exportar y descargar

Pregunte a su asistente: *"Exporte el proyecto Urban Driving Q1 y aviseme cuando este listo."*

**Paso 1** — El asistente llama a `list_projects` para encontrar el UID del proyecto que coincida con "Urban Driving Q1".

**Paso 2** — El asistente llama a `create_export` con el UID del proyecto.

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "pending",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "createdAt": "2026-03-19T10:00:00Z"
}
```

**Paso 3** — El asistente consulta `get_export_status` hasta que el estado cambie a `completed`.

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "completed",
  "downloadUrl": "https://api.avala.ai/exports/e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9/download",
  "fileSize": 52428800,
  "completedAt": "2026-03-19T10:02:34Z"
}
```

**Paso 4** — El asistente proporciona el enlace de descarga y el tamano del archivo.

> Su exportacion esta lista (50 MB). Descarguelo aqui: `https://api.avala.ai/exports/.../download`

### Receta 3: Auditoria de calidad en todos los proyectos

Pregunte a su asistente: *"Evalue los objetivos de calidad de todos mis proyectos y senale los que estan fallando."*

**Paso 1** — El asistente llama a `list_projects` para obtener todos los proyectos.

**Paso 2** — Para cada proyecto, el asistente llama a `evaluate_quality` con el UID del proyecto.

**Paso 3** — El asistente agrega los resultados y destaca los fallos:

> 5 de 7 proyectos cumplen todos los objetivos de calidad. Dos requieren atencion:
>
> * **Sidewalk Segmentation** — Objetivo "Label accuracy" en 88% (umbral: 95%)
> * **Fleet Camera Review** — Objetivo "Consensus score" en 0,72 (umbral: 0,85)

### Receta 4: Monitoreo de dispositivos de la flota

Pregunte a su asistente: *"Muestreme todas las alertas de flota que no han sido confirmadas, agrupadas por severidad."*

**Paso 1** — El asistente llama a `fleet_list_alerts` con `status: "open"`.

**Paso 2** — El asistente agrupa y formatea la respuesta:

> **Critico (1)**
>
> * Dock Camera 3 — "Dispositivo fuera de linea por mas de 24 horas" (desde el 18 de marzo)
>
> **Advertencia (2)**
>
> * Forklift Sensor Unit 12 — "Temperatura del dispositivo supero el umbral (72C)" (desde el 19 de marzo)
> * Rooftop LiDAR 1 — "Espacio en disco bajo (\< 5%)" (desde el 19 de marzo)

**Paso 3** — Puede continuar: *"Confirme todas las alertas de nivel de advertencia."* El asistente llama a `fleet_acknowledge_alert` para cada UID de alerta de tipo advertencia.

### Receta 5: Triaje de problemas de anotacion

Pregunte a su asistente: *"Obtenga las metricas de problemas de anotacion del dataset urban-driving-q1 y muestreme el desglose."*

**Paso 1** — El asistente llama a `get_annotation_issue_metrics` con el propietario y el slug del dataset.

**Paso 2** — El asistente presenta un resumen formateado:

> **Urban Driving Q1 — Metricas de problemas**
>
> Por estado: 12 abiertos, 5 en revision, 3 en re-etiquetado, 45 completados
> Por severidad: 8 criticos, 57 moderados
> Por prioridad: 2 mas altos, 6 altos, 18 medios, 25 bajos, 14 mas bajos
> Tiempo promedio de cierre: 4,2 horas

**Paso 3** — Usted continua: *"Liste los problemas criticos abiertos."* El asistente llama a `list_annotation_issues_by_dataset` con filtros y muestra los resultados.

## Ejemplos de prompts

Aqui hay algunos prompts en lenguaje natural que puede usar con cualquier cliente compatible con MCP:

```
Listar todos mis datasets
```

```
Muestrame los detalles del dataset "autonomous-driving-v3"
```

```
Cual es el estado del proyecto "Lidar QA"?
```

```
Crear una exportacion para el proyecto 770a9600-a40d-63f6-c938-668877660000
```

```
Cuantas exportaciones tengo?
```

```
Mostrar las estadisticas de mi espacio de trabajo
```

```
Listar todos mis agentes de automatizacion
```

```
Crear un webhook para eventos task.completed apuntando a https://my-server.com/hooks
```

```
Muestrame los objetivos de calidad del proyecto proj_abc123
```

```
Cual es el resumen del puntaje de consenso de mi proyecto de anotacion?
```

```
Listar todas las organizaciones a las que pertenezco
```

```
Mostrar la lista de configuraciones de almacenamiento del espacio de trabajo
```

```
Listar todos los dispositivos de flota en linea
```

```
Muestrame las alertas criticas abiertas de la flota
```

```
Registrar un nuevo dispositivo lidar-sensor llamado "Rooftop Unit 5"
```

El asistente de IA llamara a la herramienta MCP de Avala apropiada, procesara la respuesta y presentara los resultados en un formato legible. Puede encadenar solicitudes en una misma conversacion — por ejemplo, listar datasets, elegir uno y luego verificar el estado de una exportacion.

## Solucion de problemas

### `AVALA_API_KEY` no definida

El MCP server se detiene inmediatamente con el codigo de error 1 si la variable de entorno `AVALA_API_KEY` no esta presente. Asegurese de que la clave este definida en el bloque `env` de su configuracion MCP o exportada en su shell antes de iniciar el servidor.

```
Error: AVALA_API_KEY environment variable is required
```

### Las herramientas de mutacion no aparecen

Si herramientas como `create_export`, `create_agent` o `fleet_register_device` no aparecen en la lista de herramientas, necesita definir `AVALA_MCP_ENABLE_MUTATIONS=true` en el entorno del servidor. Agreguelo al bloque `env` de su archivo de configuracion MCP:

```json theme={null}
{
  "env": {
    "AVALA_API_KEY": "your-api-key",
    "AVALA_MCP_ENABLE_MUTATIONS": "true"
  }
}
```

### `npx` no encontrado o version incorrecta de Node.js

El MCP server requiere Node.js 18 o posterior. Si ve `npx: command not found` o errores de sintaxis de modulos, verifique su version de Node.js:

```bash theme={null}
node --version  # Must be v18.0.0 or later
```

### MCP server en cache desactualizado

Si actualizo recientemente el paquete `@avala-ai/mcp-server` pero todavia ve el comportamiento anterior o herramientas faltantes, npx puede estar sirviendo una version en cache. Fuerce una nueva instalacion:

```bash theme={null}
npx --yes @avala-ai/mcp-server@latest
```

Luego reinicie su cliente MCP.

### Clave API invalida o expirada

Si las llamadas a herramientas devuelven `401 Unauthorized`, su clave API puede ser invalida, estar expirada o revocada. Genere una nueva clave en [Mission Control](https://avala.ai/settings?section=security) en **Settings > Security** y actualice su configuracion MCP.

<Info>
  El MCP server de Avala es de codigo abierto. Visite el [repositorio en GitHub](https://github.com/avala-ai/avala-sdk-ts) para ver el codigo fuente o contribuir.
</Info>