MCP Server - Avala Documentation

El Model Context Protocol (MCP) 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 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:

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.

{
  "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):

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

{
  "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:

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

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

Asegurese de tener la extension 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:

claude mcp add avala -- npx -y @avala-ai/mcp-server

Defina su clave API como variable de entorno:

export AVALA_API_KEY="your-api-key"

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

ChatGPT

El soporte MCP de ChatGPT esta en evolucion. Consulte la documentacion de OpenAI para las ultimas instrucciones de configuracion y disponibilidad en su plan y region.

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:

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. mutation
`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)

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.

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. mutation
`fleet_acknowledge_alert`	Confirmar una alerta de flota. mutation

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:

{
  "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:

{
  "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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.

{
  "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:

Warehouse Cameras — 34.200 elementos (image)

Urban Driving Q1 — 12.450 elementos (lidar)

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.

{
  "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.

{
  "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:

{
  "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:

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:

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 en Settings > Security y actualice su configuracion MCP.

El MCP server de Avala es de codigo abierto. Visite el repositorio en GitHub para ver el codigo fuente o contribuir.

​Requisitos previos

​Configuracion

​Claude Desktop

​Cursor

​VS Code

​Claude Code

​ChatGPT

​Modo de seguridad MCP

​Herramientas MCP disponibles

​Fleet (Vista previa)

​Definiciones de herramientas

​list_datasets

​get_dataset

​list_projects

​get_project

​create_dataset

​create_export

​get_export_status

​list_exports

​get_workspace_stats

​list_tasks

​get_task

​list_agents

​get_agent

​create_agent

​delete_agent

​list_webhooks

​create_webhook

​delete_webhook

​list_storage_configs

​create_storage_config

​test_storage_config

​delete_storage_config

​list_quality_targets

​evaluate_quality

​get_consensus_summary

​compute_consensus

​list_organizations

​get_organization

​list_slices

​get_slice

​list_annotation_issues_by_sequence

​create_annotation_issue

​update_annotation_issue

​delete_annotation_issue

​list_annotation_issues_by_dataset

​get_annotation_issue_metrics

​list_qc_tools

​fleet_list_devices

​fleet_get_device

​fleet_list_recordings

​fleet_get_recording

​fleet_list_events

​fleet_list_alerts

​fleet_list_rules

​fleet_register_device

​fleet_acknowledge_alert

​Recetas

​Receta 1: Revision de salud de datasets

​Receta 2: Exportar y descargar

​Receta 3: Auditoria de calidad en todos los proyectos

​Receta 4: Monitoreo de dispositivos de la flota

​Receta 5: Triaje de problemas de anotacion

​Ejemplos de prompts

​Solucion de problemas

​AVALA_API_KEY no definida

​Las herramientas de mutacion no aparecen

​npx no encontrado o version incorrecta de Node.js

​MCP server en cache desactualizado

​Clave API invalida o expirada

Requisitos previos

Configuracion

Claude Desktop

Cursor

VS Code

Claude Code

ChatGPT

Modo de seguridad MCP

Herramientas MCP disponibles

Fleet (Vista previa)

Definiciones de herramientas

list_datasets

get_dataset

list_projects

get_project

create_dataset

create_export

get_export_status

list_exports

get_workspace_stats

list_tasks

get_task

list_agents

get_agent

create_agent

delete_agent

list_webhooks

create_webhook

delete_webhook

list_storage_configs

create_storage_config

test_storage_config

delete_storage_config

list_quality_targets

evaluate_quality

get_consensus_summary

compute_consensus

list_organizations

get_organization

list_slices

get_slice

list_annotation_issues_by_sequence

create_annotation_issue

update_annotation_issue

delete_annotation_issue

list_annotation_issues_by_dataset

get_annotation_issue_metrics

list_qc_tools

fleet_list_devices

fleet_get_device

fleet_list_recordings

fleet_get_recording

fleet_list_events

fleet_list_alerts

fleet_list_rules

fleet_register_device

fleet_acknowledge_alert

Recetas

Receta 1: Revision de salud de datasets

Receta 2: Exportar y descargar

Receta 3: Auditoria de calidad en todos los proyectos

Receta 4: Monitoreo de dispositivos de la flota

Receta 5: Triaje de problemas de anotacion

Ejemplos de prompts

Solucion de problemas

`AVALA_API_KEY` no definida

Las herramientas de mutacion no aparecen

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

MCP server en cache desactualizado

Clave API invalida o expirada