MCP Server - Avala Documentation

Model Context Protocol (MCP) 是一个开放标准，允许 AI 助手与外部工具和数据源进行交互。Avala 的 MCP Server 将您的数据集、项目和导出公开为工具，任何 MCP 兼容的客户端都可以调用，让您无需切换上下文即可通过自然语言管理标注工作流。这意味着您可以让 Claude「列出我所有的数据集」，在 Cursor 中创建导出，或使用 VS Code 查看项目状态——所有这些都由您已在使用的 Avala API 提供支持。

前提条件

您的机器上已安装 Node.js 18 或更高版本
一个 Avala API 密钥（在 Mission Control 的 Settings > Security 中生成）

设置

Claude Desktop

打开您的 Claude Desktop 配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

添加 Avala MCP Server：

切勿将包含真实 API 密钥的配置文件提交到版本控制系统。请将 AVALA_API_KEY 设置为系统环境变量，或在本地将 "your-api-key" 替换为您的实际密钥，并确保配置文件已添加到 .gitignore 中。

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

重启 Claude Desktop。您应该能在工具选择器中看到 Avala 的工具。

Cursor

在项目根目录（或全局配置目录）中创建或编辑 .cursor/mcp.json：

.cursor/mcp.json 位于项目根目录中，可能会被提交到 git。请将其添加到 .gitignore，或将 AVALA_API_KEY 设置为系统环境变量，而不是直接写在配置文件中。

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

重启 Cursor 或重新加载窗口。Avala 工具将出现在 Cursor 的代理模式中。

VS Code

在您的工作区中创建或编辑 .vscode/mcp.json：

.vscode/mcp.json 位于您的工作区中，可能会被提交到 git。请将其添加到 .gitignore，或将 AVALA_API_KEY 设置为系统环境变量，而不是直接写在配置文件中。

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

确保您已安装启用了 MCP 支持的 GitHub Copilot 扩展。重启 VS Code 以加载新的服务器。

Claude Code

使用一条命令将 Avala MCP Server 添加到 Claude Code：

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

将 API 密钥设置为环境变量：

export AVALA_API_KEY="your-api-key"

重启 Claude Code。Avala 工具将在您的会话中可用。

ChatGPT

ChatGPT 的 MCP 支持仍在发展中。有关最新的设置说明以及在您所在的套餐和地区的可用性，请参阅 OpenAI 文档。

MCP 安全模式

为了安全起见，MCP Server 默认为只读模式。变更类工具不会被注册，除非您明确启用它们：

AVALA_MCP_ENABLE_MUTATIONS=true

此环境变量可以在启动服务器之前在 MCP Server 的进程环境中设置。默认情况下，以下写入/删除操作会被阻止：

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

可用的 MCP 工具

连接后，AI 助手可以使用以下工具：

工具	描述
`list_datasets`	列出工作区中的所有数据集。
`get_dataset`	获取特定数据集的详细信息。
`create_dataset`	创建新的标注数据集。 mutation
`list_projects`	列出所有标注项目。
`get_project`	获取项目的完整详情。
`create_export`	为数据集或项目触发新的导出。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`get_export_status`	检查导出状态。
`list_exports`	列出所有导出。
`get_workspace_stats`	获取工作区使用情况摘要。
`list_tasks`	列出任务，支持可选筛选。
`get_task`	获取任务详情。
`list_agents`	列出自动化代理。
`get_agent`	获取代理详情。
`create_agent`	创建新的自动化代理。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`delete_agent`	删除代理。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`list_webhooks`	列出 Webhook 订阅。
`create_webhook`	创建 Webhook 订阅。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`delete_webhook`	删除 Webhook。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`list_storage_configs`	列出存储配置。
`create_storage_config`	创建存储配置。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`test_storage_config`	测试存储连接。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`delete_storage_config`	删除存储配置。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`list_quality_targets`	列出项目的质量目标。
`evaluate_quality`	评估质量目标。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`get_consensus_summary`	获取项目的共识摘要。
`compute_consensus`	触发共识计算。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`list_organizations`	列出组织。
`get_organization`	获取组织详情。
`list_slices`	列出所有者的切片。
`get_slice`	获取切片详情。
`list_annotation_issues_by_sequence`	列出序列的标注问题。
`create_annotation_issue`	创建新的标注问题。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`update_annotation_issue`	更新标注问题。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`delete_annotation_issue`	删除标注问题。（需要 `AVALA_MCP_ENABLE_MUTATIONS=true`）
`list_annotation_issues_by_dataset`	列出数据集的标注问题。
`get_annotation_issue_metrics`	获取数据集的问题指标。
`list_qc_tools`	列出可用的 QC 工具。

Fleet（预览版）

Fleet 工具处于预览阶段，可能会发生变化。它们提供对车队设备、录制、事件、警报和规则的读写访问。

工具	描述
`fleet_list_devices`	列出车队设备，支持可选筛选。
`fleet_get_device`	获取特定车队设备的详细信息。
`fleet_list_recordings`	列出车队录制，支持可选筛选。
`fleet_get_recording`	获取特定录制的详细信息。
`fleet_list_events`	列出车队事件，支持可选筛选。
`fleet_list_alerts`	列出车队警报，支持可选筛选。
`fleet_list_rules`	列出车队规则，支持可选筛选。
`fleet_register_device`	注册新的车队设备。 mutation
`fleet_acknowledge_alert`	确认车队警报。 mutation

工具定义

每个 MCP 工具的详细架构。所有工具以文本内容形式返回 JSON。

list_datasets

列出工作区中的所有数据集。 参数：

dataType (string, optional) — 按数据类型筛选（image、video、lidar、mcap、splat）
name (string, optional) — 按数据集名称筛选（部分匹配）
status (string, optional) — 按数据集状态筛选
visibility (string, optional) — 按可见性筛选（private 或 public）
limit (number, optional) — 返回的最大数据集数量
cursor (string, optional) — 来自上一次请求的分页游标

示例响应：

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

获取特定数据集的详细信息。 参数：

uid (string, required) — 数据集的唯一标识符（UUID）

示例响应：

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

错误响应（无效 UID）：

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

list_projects

列出所有标注项目。 参数：

limit (number, optional) — 返回的最大项目数量
cursor (string, optional) — 来自上一次请求的分页游标

get_project

获取特定项目的详细信息。 参数：

uid (string, required) — 项目的唯一标识符（UUID）

create_dataset

创建新的标注数据集。 参数：

name (string, required) — 数据集的显示名称
slug (string, required) — 数据集的 URL 友好标识符
dataType (string, required) — 数据类型：image、video、lidar 或 mcap
visibility (string, optional) — 数据集可见性：private 或 public（默认值：private）
createMetadata (boolean, optional) — 是否创建数据集元数据（默认值：true）
providerConfig (object, optional) — 云存储提供商配置
ownerName (string, optional) — 数据集所有者的用户名或邮箱

create_export

为数据集或项目触发新的导出。 参数：

project (string, optional) — 要导出的项目 UID
dataset (string, optional) — 要导出的数据集 UID

示例响应：

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

get_export_status

检查导出的状态。 参数：

uid (string, required) — 导出的唯一标识符（UUID）

示例响应：

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

列出工作区中的所有导出。 参数：

limit (number, optional) — 返回的最大导出数量
cursor (string, optional) — 来自上一次请求的分页游标

get_workspace_stats

快速查看工作区内容（数据集、项目、导出）。 参数： 无 示例响应：

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

list_tasks

列出任务，支持按项目或状态进行可选筛选。 参数：

project (string, optional) — 按项目 UID 筛选
status (string, optional) — 按任务状态筛选
limit (number, optional) — 返回的最大任务数量
cursor (string, optional) — 来自上一次请求的分页游标

示例响应：

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

获取特定任务的详细信息。 参数：

uid (string, required) — 任务的唯一标识符（UUID）

list_agents

列出工作区中配置的所有自动化代理。 参数：

limit (number, optional) — 返回的最大代理数量
cursor (string, optional) — 来自上一次请求的分页游标

get_agent

获取特定自动化代理的详细信息。 参数：

uid (string, required) — 代理的唯一标识符（UUID）

create_agent

创建一个带有事件订阅和回调 URL 的新自动化代理。 参数：

name (string, required) — 代理名称
events (string[], required) — 代理订阅的事件类型列表
callbackUrl (string, optional) — 接收事件回调的 URL
description (string, optional) — 代理描述
project (string, optional) — 代理作用范围的项目 UID
taskTypes (string[], optional) — 代理处理的任务类型

delete_agent

按 UID 删除自动化代理。 参数：

uid (string, required) — 要删除的代理的唯一标识符（UUID）

list_webhooks

列出工作区中的所有 Webhook 订阅。 参数：

limit (number, optional) — 返回的最大 Webhook 数量
cursor (string, optional) — 来自上一次请求的分页游标

create_webhook

为特定事件创建新的 Webhook 订阅。 参数：

targetUrl (string, required) — 接收 Webhook 投递的 URL
events (string[], required) — 要订阅的事件类型列表

delete_webhook

按 UID 删除 Webhook 订阅。 参数：

uid (string, required) — 要删除的 Webhook 的唯一标识符（UUID）

list_storage_configs

列出工作区中的所有存储配置。 参数：

limit (number, optional) — 返回的最大存储配置数量
cursor (string, optional) — 来自上一次请求的分页游标

create_storage_config

创建新的存储配置（S3 或 Google Cloud Storage）。 参数：

name (string, required) — 存储配置的名称
provider (string, required) — 存储提供商类型（s3 或 gcs）
s3BucketName (string, optional) — S3 存储桶名称
s3BucketRegion (string, optional) — S3 存储桶区域
s3BucketPrefix (string, optional) — S3 键前缀
s3AccessKeyId (string, optional) — S3 访问密钥 ID（在服务器端安全存储）
s3SecretAccessKey (string, optional) — S3 秘密访问密钥（在服务器端安全存储）
s3IsAccelerated (boolean, optional) — 启用 S3 Transfer Acceleration
gcStorageBucketName (string, optional) — Google Cloud Storage 存储桶名称
gcStoragePrefix (string, optional) — Google Cloud Storage 前缀
gcStorageAuthJsonContent (string, optional) — GCS 服务账户 JSON 凭据（在服务器端安全存储）

test_storage_config

测试存储配置的连接。 参数：

uid (string, required) — 要测试的存储配置的唯一标识符（UUID）

delete_storage_config

按 UID 删除存储配置。 参数：

uid (string, required) — 要删除的存储配置的唯一标识符（UUID）

list_quality_targets

列出特定项目配置的质量目标。 参数：

projectUid (string, required) — 项目的唯一标识符（UUID）
limit (number, optional) — 返回的最大质量目标数量
cursor (string, optional) — 来自上一次请求的分页游标

evaluate_quality

评估项目的所有质量目标并返回其当前状态。 参数：

projectUid (string, required) — 要评估的项目的唯一标识符（UUID）

get_consensus_summary

获取项目的共识摘要，包括平均值/中位数分数和分布。 参数：

projectUid (string, required) — 项目的唯一标识符（UUID）

compute_consensus

触发项目的共识计算。 参数：

projectUid (string, required) — 项目的唯一标识符（UUID）

list_organizations

列出您所属的所有组织。 参数：

limit (number, optional) — 返回的最大组织数量
cursor (string, optional) — 来自上一次请求的分页游标

get_organization

获取特定组织的详细信息。 参数：

slug (string, required) — 组织的 slug 标识符

list_slices

列出所有者（用户或组织）的切片。 参数：

owner (string, required) — 所有者名称（用户或组织的 slug）
limit (number, optional) — 返回的最大切片数量
cursor (string, optional) — 来自上一次请求的分页游标

get_slice

获取特定切片的详细信息。 参数：

owner (string, required) — 所有者名称（用户或组织的 slug）
slug (string, required) — 切片的 slug

list_annotation_issues_by_sequence

列出特定序列的所有标注问题。 参数：

sequenceUid (string, required) — 序列的 UUID
datasetItemUid (string, optional) — 按数据集项 UUID 筛选
projectUid (string, optional) — 按项目 UUID 筛选

create_annotation_issue

在序列上创建新的标注问题。 参数：

sequenceUid (string, required) — 序列的 UUID
toolUid (string, required) — 标注工具的 UUID
problemUid (string, required) — 问题类型的 UUID
datasetItemUid (string, optional) — 数据集项的 UUID
projectUid (string, optional) — 项目的 UUID
priority (string, optional) — 优先级：lowest、low、medium、high、highest
severity (string, optional) — 严重程度：critical、moderate
description (string, optional) — 问题描述
wrongClass (string, optional) — 错误的类别标签
correctClass (string, optional) — 正确的类别标签
objectUid (string, optional) — 标注对象的 UUID
shouldReAnnotate (boolean, optional) — 是否需要重新标注
shouldDelete (boolean, optional) — 是否删除标注
framesAffected (string, optional) — 受影响的帧

update_annotation_issue

更新现有的标注问题（状态、优先级等）。 参数：

sequenceUid (string, required) — 序列的 UUID
issueUid (string, required) — 标注问题的 UUID
status (string, optional) — 状态：open、relabeling、in_review、completed、cant_reproduce、awaiting_feedback、no_action_taken
priority (string, optional) — 优先级：lowest、low、medium、high、highest
severity (string, optional) — 严重程度：critical、moderate
description (string, optional) — 更新后的描述
toolUid (string, optional) — 标注工具的 UUID
problemUid (string, optional) — 问题类型的 UUID
wrongClass (string, optional) — 错误的类别标签
framesAffected (string, optional) — 受影响的帧

delete_annotation_issue

删除标注问题。 参数：

sequenceUid (string, required) — 序列的 UUID
issueUid (string, required) — 要删除的标注问题的 UUID

list_annotation_issues_by_dataset

列出数据集的所有标注问题。 参数：

owner (string, required) — 数据集所有者的用户名
datasetSlug (string, required) — 数据集的 slug
sequenceUid (string, optional) — 按序列 UUID 筛选

get_annotation_issue_metrics

获取数据集中标注问题的聚合指标（状态/优先级/严重程度计数、关闭时间）。 参数：

owner (string, required) — 数据集所有者的用户名
datasetSlug (string, required) — 数据集的 slug
sequenceUid (string, optional) — 按序列 UUID 筛选

list_qc_tools

列出指定数据集类型可用的 QC 标注工具。 参数：

datasetType (string, required) — 数据集类型（例如 lidar、image、video）

fleet_list_devices

列出车队设备，支持可选筛选。 参数：

status (string, optional) — 按设备状态筛选（online、offline、maintenance）
type (string, optional) — 按设备类型筛选
limit (number, optional) — 返回的最大设备数量
cursor (string, optional) — 分页游标

示例响应：

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

获取特定车队设备的详细信息。 参数：

uid (string, required) — 设备的唯一标识符

fleet_list_recordings

列出车队录制，支持可选筛选。 参数：

device (string, optional) — 按设备 UID 筛选
status (string, optional) — 按录制状态筛选
limit (number, optional) — 返回的最大录制数量
cursor (string, optional) — 分页游标

fleet_get_recording

获取特定录制的详细信息。 参数：

uid (string, required) — 录制的唯一标识符

fleet_list_events

列出车队事件，支持可选筛选。 参数：

recording (string, optional) — 按录制 UID 筛选
device (string, optional) — 按设备 UID 筛选
type (string, optional) — 按事件类型筛选
severity (string, optional) — 按严重程度筛选
limit (number, optional) — 返回的最大事件数量
cursor (string, optional) — 分页游标

fleet_list_alerts

列出车队警报，支持可选筛选。 参数：

status (string, optional) — 按警报状态筛选（open、acknowledged、resolved）
severity (string, optional) — 按严重程度筛选（info、warning、error、critical）
device (string, optional) — 按设备 UID 筛选
rule (string, optional) — 按规则 UID 筛选
limit (number, optional) — 返回的最大警报数量
cursor (string, optional) — 分页游标

示例响应：

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

列出车队规则，支持可选筛选。 参数：

enabled (boolean, optional) — 按启用状态筛选
limit (number, optional) — 返回的最大规则数量
cursor (string, optional) — 分页游标

fleet_register_device

注册新的车队设备。 参数：

name (string, required) — 设备名称
type (string, required) — 设备类型
firmwareVersion (string, optional) — 固件版本
tags (string[], optional) — 设备标签

fleet_acknowledge_alert

确认车队警报。 参数：

uid (string, required) — 要确认的警报的唯一标识符

使用示例

可以通过自然语言运行的多步骤工作流。每个示例展示了助手在后台进行的工具调用。

示例 1：数据集健康检查

向助手提问：「检查一下我的工作区——我有多少个数据集，哪些数据集的项目数最多？」 步骤 1 — 助手调用 get_workspace_stats 获取概览。

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

步骤 2 — 助手调用 list_datasets，设置 limit: 50 获取所有数据集。 步骤 3 — 助手按 itemCount 排序结果并呈现排名摘要：

您有 14 个数据集。最大的三个是：

Warehouse Cameras — 34,200 个项目（image）

Urban Driving Q1 — 12,450 个项目（lidar）

Parking Lot Footage — 8,900 个项目（video）

示例 2：导出和下载

向助手提问：「导出 Urban Driving Q1 项目，准备好了告诉我。」 步骤 1 — 助手调用 list_projects 查找与「Urban Driving Q1」匹配的项目 UID。 步骤 2 — 助手使用项目 UID 调用 create_export。

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

步骤 3 — 助手轮询 get_export_status，直到状态变为 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"
}

步骤 4 — 助手提供下载链接和文件大小。

您的导出已准备就绪（50 MB）。在此处下载：https://api.avala.ai/exports/.../download

示例 3：跨项目质量审计

向助手提问：「评估我所有项目的质量目标，标记未通过的项目。」 步骤 1 — 助手调用 list_projects 获取所有项目。 步骤 2 — 对于每个项目，助手使用项目 UID 调用 evaluate_quality。 步骤 3 — 助手汇总结果并突出显示未通过的项目：

7 个项目中有 5 个通过了所有质量目标。两个需要关注：

Sidewalk Segmentation — 「标签准确率」目标为 88%（阈值：95%）

Fleet Camera Review — 「共识分数」目标为 0.72（阈值：0.85）

示例 4：车队设备监控

向助手提问：「显示所有尚未确认的车队警报，按严重程度分组。」 步骤 1 — 助手调用 fleet_list_alerts，设置 status: "open"。 步骤 2 — 助手对响应进行分组和格式化：

Critical（1 条）

Dock Camera 3 — 「设备离线超过 24 小时」（自 3 月 18 日起）

Warning（2 条）

Forklift Sensor Unit 12 — 「设备温度超过阈值（72C）」（自 3 月 19 日起）

Rooftop LiDAR 1 — 「磁盘空间不足（< 5%）」（自 3 月 19 日起）

步骤 3 — 您可以继续提问：「确认所有 warning 级别的警报。」 助手将为每个 warning 警报的 UID 调用 fleet_acknowledge_alert。

示例 5：标注问题分类

向助手提问：「获取 urban-driving-q1 数据集的标注问题指标，显示详细分类。」 步骤 1 — 助手使用所有者和数据集 slug 调用 get_annotation_issue_metrics。 步骤 2 — 助手展示格式化的摘要：

Urban Driving Q1 — 问题指标 按状态：12 个 open，5 个 in review，3 个 relabeling，45 个 completed 按严重程度：8 个 critical，57 个 moderate 按优先级：2 个 highest，6 个 high，18 个 medium，25 个 low，14 个 lowest 平均关闭时间：4.2 小时

步骤 3 — 您继续提问：「列出打开的 critical 问题。」 助手使用筛选条件调用 list_annotation_issues_by_dataset 并显示结果。

提示词示例

以下是一些可以在任何 MCP 兼容客户端中使用的自然语言提示词：

List all my datasets

Show me the details of dataset "autonomous-driving-v3"

What's the status of the "Lidar QA" project?

Create an export for project 770a9600-a40d-63f6-c938-668877660000

How many exports do I have?

Show my workspace stats

List all my automation agents

Create a webhook for task.completed events pointing to https://my-server.com/hooks

Show me the quality targets for project proj_abc123

What's the consensus score summary for my annotation project?

List all organizations I belong to

Show workspace storage config list

List all online fleet devices

Show me open critical alerts across the fleet

Register a new lidar-sensor device called "Rooftop Unit 5"

AI 助手将调用相应的 Avala MCP 工具，处理响应，并以易读的格式呈现结果。您可以在一次对话中连续发出请求——例如，列出数据集，选择一个，然后查看导出状态。

故障排除

`AVALA_API_KEY` 未设置

如果 AVALA_API_KEY 环境变量缺失，MCP Server 会立即以错误代码 1 退出。请确保在 MCP 配置的 env 块中设置了密钥，或在启动服务器之前在 shell 中导出了该变量。

Error: AVALA_API_KEY environment variable is required

变更类工具未显示

如果 create_export、create_agent 或 fleet_register_device 等工具未出现在工具列表中，您需要在服务器环境中设置 AVALA_MCP_ENABLE_MUTATIONS=true。将其添加到 MCP 配置文件的 env 块中：

{
  "env": {
    "AVALA_API_KEY": "your-api-key",
    "AVALA_MCP_ENABLE_MUTATIONS": "true"
  }
}

`npx` 未找到或 Node.js 版本不正确

MCP Server 需要 Node.js 18 或更高版本。如果您看到 npx: command not found 或模块语法错误，请验证您的 Node.js 版本：

node --version  # Must be v18.0.0 or later

缓存的旧版 MCP Server

如果您最近更新了 @avala-ai/mcp-server 包，但仍然看到旧的行为或缺少工具，npx 可能在使用缓存的版本。强制重新安装：

npx --yes @avala-ai/mcp-server@latest

然后重启您的 MCP 客户端。

API 密钥无效或已过期

如果工具调用返回 401 Unauthorized，您的 API 密钥可能无效、已过期或已被撤销。在 Mission Control 的 Settings > Security 中生成新密钥，并更新您的 MCP 配置。

Avala MCP Server 是开源的。访问 GitHub 仓库查看源代码或参与贡献。

​前提条件

​设置

​Claude Desktop

​Cursor

​VS Code

​Claude Code

​ChatGPT

​MCP 安全模式

​可用的 MCP 工具

​Fleet（预览版）

​工具定义

​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

​使用示例

​示例 1：数据集健康检查

​示例 2：导出和下载

​示例 3：跨项目质量审计

​示例 4：车队设备监控

​示例 5：标注问题分类

​提示词示例

​故障排除

​AVALA_API_KEY 未设置

​变更类工具未显示

​npx 未找到或 Node.js 版本不正确

​缓存的旧版 MCP Server

​API 密钥无效或已过期

前提条件

设置

Claude Desktop

Cursor

VS Code

Claude Code

ChatGPT

MCP 安全模式

可用的 MCP 工具

Fleet（预览版）

工具定义

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

使用示例

示例 1：数据集健康检查

示例 2：导出和下载

示例 3：跨项目质量审计

示例 4：车队设备监控

示例 5：标注问题分类

提示词示例

故障排除

`AVALA_API_KEY` 未设置

变更类工具未显示

`npx` 未找到或 Node.js 版本不正确

缓存的旧版 MCP Server

API 密钥无效或已过期