MCP Server - Avala Documentation

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data sources. Avala’s MCP server exposes your datasets, projects, and exports as tools that any MCP-compatible client can call, so you can manage your annotation workflow through natural language without switching context. This means you can ask Claude to “list all my datasets,” have Cursor create an export, or use VS Code to check project status — all powered by the same Avala API you already use.

Prerequisites

Node.js 18 or later installed on your machine
An Avala API key (generate one in Mission Control under Settings > Security)

Setup

Claude Desktop

Open your Claude Desktop configuration file:

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

Add the Avala MCP server:

Never commit config files containing real API keys to version control. Set AVALA_API_KEY as a system environment variable, or replace "your-api-key" with your actual key locally and ensure the config file is in your .gitignore.

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

Restart Claude Desktop. You should see the Avala tools available in the tool picker.

Cursor

Create or edit .cursor/mcp.json in your project root (or global config directory):

.cursor/mcp.json lives in your project root and may be committed to git. Add it to your .gitignore or set AVALA_API_KEY as a system environment variable instead of placing it directly in the config file.

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

Restart Cursor or reload the window. The Avala tools will appear in Cursor’s agent mode.

VS Code

Create or edit .vscode/mcp.json in your workspace:

.vscode/mcp.json lives in your workspace and may be committed to git. Add it to your .gitignore or set AVALA_API_KEY as a system environment variable instead of placing it directly in the config file.

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

Make sure you have the GitHub Copilot extension installed with MCP support enabled. Restart VS Code to pick up the new server.

Claude Code

Add the Avala MCP server to Claude Code with a single command:

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

Set your API key as an environment variable:

export AVALA_API_KEY="your-api-key"

Restart Claude Code. The Avala tools will be available in your session.

ChatGPT

ChatGPT’s MCP support is evolving. Refer to OpenAI’s documentation for the latest setup instructions and availability in your plan and region.

MCP Security Mode

For safety, the MCP server is read-only by default. Mutating tools are not registered unless you explicitly enable them with:

AVALA_MCP_ENABLE_MUTATIONS=true

This environment variable can be set in your MCP server process environment before launching the server. By default, the following write/delete operations are blocked:

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

Available MCP Tools

Once connected, the following tools are available to the AI assistant:

Tool	Description
`list_datasets`	List all datasets in your workspace.
`get_dataset`	Get details for a specific dataset.
`list_sequences`	List sequences for a dataset (paginated).
`get_sequence`	Get a sequence including its embedded frames array.
`get_frame`	Get a single frame’s LiDAR JSON metadata (camera model, intrinsics, device pose).
`get_calibration`	Get the canonicalized per-camera rig for a sequence (derived from frame[0]).
`get_dataset_health`	Read-only ingest/health snapshot: frame totals, per-sequence counts, S3 prefix, detected issues.
`create_dataset`	Create a new dataset for annotation. mutation
`list_projects`	List all annotation projects.
`get_project`	Get full project details.
`create_export`	Trigger a new export for a dataset or project. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`get_export_status`	Check export status.
`list_exports`	List all exports.
`get_workspace_stats`	Get workspace usage summary.
`list_tasks`	List tasks with optional filtering.
`get_task`	Get task details.
`list_agents`	List automation agents.
`get_agent`	Get agent details.
`create_agent`	Create a new automation agent. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`delete_agent`	Delete an agent. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`list_webhooks`	List webhook subscriptions.
`create_webhook`	Create a webhook subscription. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`delete_webhook`	Delete a webhook. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`list_storage_configs`	List storage configurations.
`create_storage_config`	Create a storage configuration. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`test_storage_config`	Test storage connectivity.
`delete_storage_config`	Delete a storage configuration. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`list_quality_targets`	List quality targets for a project.
`evaluate_quality`	Evaluate quality targets. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`get_consensus_summary`	Get consensus summary for a project.
`compute_consensus`	Trigger consensus computation. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`list_organizations`	List organizations.
`get_organization`	Get organization details.
`list_slices`	List slices for an owner.
`get_slice`	Get slice details.
`list_annotation_issues_by_sequence`	List annotation issues for a sequence.
`create_annotation_issue`	Create a new annotation issue. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`update_annotation_issue`	Update an annotation issue. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`delete_annotation_issue`	Delete an annotation issue. (requires `AVALA_MCP_ENABLE_MUTATIONS=true`)
`list_annotation_issues_by_dataset`	List annotation issues for a dataset.
`get_annotation_issue_metrics`	Get issue metrics for a dataset.
`list_qc_tools`	List available QC tools.

Fleet (Preview)

Fleet tools are in preview and may change. They provide read and write access to fleet devices, recordings, events, alerts, and rules.

Tool	Description
`fleet_list_devices`	List fleet devices with optional filters.
`fleet_get_device`	Get detailed information about a specific fleet device.
`fleet_list_recordings`	List fleet recordings with optional filters.
`fleet_get_recording`	Get detailed information about a specific recording.
`fleet_list_events`	List fleet events with optional filters.
`fleet_list_alerts`	List fleet alerts with optional filters.
`fleet_list_rules`	List fleet rules with optional filters.
`fleet_register_device`	Register a new fleet device. mutation
`fleet_acknowledge_alert`	Acknowledge a fleet alert. mutation

Tool Definitions

Detailed schemas for each MCP tool. All tools return JSON as text content.

list_datasets

Lists all datasets in the workspace. Parameters:

dataType (string, optional) — Filter by data type (image, video, lidar, mcap, splat)
name (string, optional) — Filter by dataset name (partial match)
status (string, optional) — Filter by dataset status
visibility (string, optional) — Filter by visibility (private or public)
limit (number, optional) — Maximum number of datasets to return
cursor (string, optional) — Pagination cursor from a previous request

Example response:

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

Gets details for a specific dataset. Parameters:

uid (string, required) — The unique identifier (UUID) of the dataset

Example response:

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

Error response (invalid UID):

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

list_sequences

Lists sequences for a dataset. Parameters:

owner (string, required) — Dataset owner username, handle, or organization slug
slug (string, required) — Dataset slug
limit (number, optional) — Maximum number of sequences to return
cursor (string, optional) — Pagination cursor from a previous request

get_sequence

Gets a sequence including its embedded frames array (full LiDAR JSON metadata for every frame). Parameters:

owner (string, required) — Dataset owner username, handle, or organization slug
slug (string, required) — Dataset slug
sequenceUid (string, required) — Sequence UUID

get_frame

Gets a single frame’s LiDAR JSON metadata — the same blob Mission Control loads. Useful for post-ingest validation: confirm camera model, intrinsics, extrinsics, and device pose without opening the UI. Parameters:

owner (string, required) — Dataset owner username, handle, or organization slug
slug (string, required) — Dataset slug
sequenceUid (string, required) — Sequence UUID
frameIdx (number, required) — Zero-based frame index within the sequence

Example response (truncated):

{
  "frameIndex": 0,
  "key": "frame-0.json",
  "model": "pinhole",
  "xi": null,
  "alpha": null,
  "devicePosition": { "x": 1.0, "y": 2.0, "z": 3.0 },
  "deviceHeading": { "x": 0, "y": 0, "z": 0, "w": 1 },
  "images": [
    { "fx": 824.74, "fy": 834.49, "cx": 960.0, "cy": 540.0, "model": "pinhole" }
  ]
}

get_calibration

Gets the canonicalized per-camera rig for a sequence, derived from frame[0]. Parameters:

owner (string, required) — Dataset owner username, handle, or organization slug
slug (string, required) — Dataset slug
sequenceUid (string, required) — Sequence UUID

get_dataset_health

Read-only ingest/health snapshot for a dataset. Intended for programmatic validation after upload. Parameters:

owner (string, required) — Dataset owner username, handle, or organization slug
slug (string, required) — Dataset slug

Example response:

{
  "datasetUid": "d8f2e1a4-3b7c-4e9f-a1d6-5c8b9e0f2a3d",
  "datasetSlug": "urban-driving-q1",
  "datasetStatus": "created",
  "itemCount": 569,
  "sequenceCount": 1,
  "totalFrames": 569,
  "s3Prefix": "datasets/urban-driving-q1/full-scene-569",
  "gcStoragePrefix": null,
  "lastUpdatedAt": "2026-04-21T15:33:02Z",
  "ingestOk": true,
  "issues": [],
  "sequences": [
    {
      "uid": "55555555-5555-5555-5555-555555555555",
      "key": "full-scene-569",
      "status": "completed",
      "frameCount": 569,
      "hasLidarCalibration": true,
      "hasCameraCalibration": true
    }
  ]
}

list_projects

Lists all annotation projects. Parameters:

limit (number, optional) — Maximum number of projects to return
cursor (string, optional) — Pagination cursor from a previous request

get_project

Gets details for a specific project. Parameters:

uid (string, required) — The unique identifier (UUID) of the project

create_dataset

Creates a new dataset for annotation. Parameters:

name (string, required) — Display name for the dataset
slug (string, required) — URL-friendly identifier for the dataset
dataType (string, required) — Type of data: image, video, lidar, or mcap
isSequence (boolean, optional) — Whether the dataset contains sequences (default: false)
visibility (string, optional) — Dataset visibility: private or public (default: private)
createMetadata (boolean, optional) — Whether to create dataset metadata (default: true)
providerConfig (object, optional) — Cloud storage provider configuration
ownerName (string, optional) — Dataset owner username or email

create_export

Triggers a new export for a dataset or project. Parameters:

project (string, optional) — Project UID to export
dataset (string, optional) — Dataset UID to export

Example response:

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

get_export_status

Checks the status of an export. Parameters:

uid (string, required) — The unique identifier (UUID) of the export

Example response:

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

Lists all exports in the workspace. Parameters:

limit (number, optional) — Maximum number of exports to return
cursor (string, optional) — Pagination cursor from a previous request

get_workspace_stats

Gets a quick check of workspace contents (datasets, projects, exports). Parameters: None Example response:

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

list_tasks

Lists tasks with optional filtering by project or status. Parameters:

project (string, optional) — Filter by project UID
status (string, optional) — Filter by task status
limit (number, optional) — Maximum number of tasks to return
cursor (string, optional) — Pagination cursor from a previous request

Example response:

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

Gets detailed information about a specific task. Parameters:

uid (string, required) — The unique identifier (UUID) of the task

list_agents

Lists all automation agents configured in your workspace. Parameters:

limit (number, optional) — Maximum number of agents to return
cursor (string, optional) — Pagination cursor from a previous request

get_agent

Gets detailed information about a specific automation agent. Parameters:

uid (string, required) — The unique identifier (UUID) of the agent

create_agent

Creates a new automation agent with event subscriptions and a callback URL. Parameters:

name (string, required) — Name of the agent
events (string[], required) — List of event types the agent subscribes to
callbackUrl (string, optional) — URL to receive event callbacks
description (string, optional) — Description of the agent
project (string, optional) — Project UID to scope the agent to
taskTypes (string[], optional) — Task types the agent handles

delete_agent

Deletes an automation agent by its UID. Parameters:

uid (string, required) — The unique identifier (UUID) of the agent to delete

list_webhooks

Lists all webhook subscriptions in your workspace. Parameters:

limit (number, optional) — Maximum number of webhooks to return
cursor (string, optional) — Pagination cursor from a previous request

create_webhook

Creates a new webhook subscription for specific events. Parameters:

targetUrl (string, required) — URL to receive webhook deliveries
events (string[], required) — List of event types to subscribe to

delete_webhook

Deletes a webhook subscription by its UID. Parameters:

uid (string, required) — The unique identifier (UUID) of the webhook to delete

list_storage_configs

Lists all storage configurations in your workspace. Parameters:

limit (number, optional) — Maximum number of storage configs to return
cursor (string, optional) — Pagination cursor from a previous request

create_storage_config

Creates a new storage configuration (S3 or Google Cloud Storage). Parameters:

name (string, required) — Name for the storage configuration
provider (string, required) — Storage provider type (s3 or gcs)
s3BucketName (string, optional) — S3 bucket name
s3BucketRegion (string, optional) — S3 bucket region
s3BucketPrefix (string, optional) — S3 key prefix
s3AccessKeyId (string, optional) — S3 access key ID (stored securely server-side)
s3SecretAccessKey (string, optional) — S3 secret access key (stored securely server-side)
s3IsAccelerated (boolean, optional) — Enable S3 Transfer Acceleration
gcStorageBucketName (string, optional) — Google Cloud Storage bucket name
gcStoragePrefix (string, optional) — Google Cloud Storage prefix
gcStorageAuthJsonContent (string, optional) — GCS service account JSON credentials (stored securely server-side)

test_storage_config

Tests connectivity for a storage configuration. Parameters:

uid (string, required) — The unique identifier (UUID) of the storage config to test

delete_storage_config

Deletes a storage configuration by its UID. Parameters:

uid (string, required) — The unique identifier (UUID) of the storage config to delete

list_quality_targets

Lists quality targets configured for a specific project. Parameters:

projectUid (string, required) — The unique identifier (UUID) of the project
limit (number, optional) — Maximum number of quality targets to return
cursor (string, optional) — Pagination cursor from a previous request

evaluate_quality

Evaluates all quality targets for a project and returns their current status. Parameters:

projectUid (string, required) — The unique identifier (UUID) of the project to evaluate

get_consensus_summary

Gets a consensus summary for a project including mean/median scores and distribution. Parameters:

projectUid (string, required) — The unique identifier (UUID) of the project

compute_consensus

Triggers consensus computation for a project. Parameters:

projectUid (string, required) — The unique identifier (UUID) of the project

list_organizations

Lists all organizations you are a member of. Parameters:

limit (number, optional) — Maximum number of organizations to return
cursor (string, optional) — Pagination cursor from a previous request

get_organization

Gets detailed information about a specific organization. Parameters:

slug (string, required) — The slug identifier of the organization

list_slices

Lists slices for an owner (user or organization). Parameters:

owner (string, required) — Owner name (user or organization slug)
limit (number, optional) — Maximum number of slices to return
cursor (string, optional) — Pagination cursor from a previous request

get_slice

Gets detailed information about a specific slice. Parameters:

owner (string, required) — Owner name (user or organization slug)
slug (string, required) — The slug of the slice

list_annotation_issues_by_sequence

Lists all annotation issues for a specific sequence. Parameters:

sequenceUid (string, required) — The UUID of the sequence
datasetItemUid (string, optional) — Filter by dataset item UUID
projectUid (string, optional) — Filter by project UUID

create_annotation_issue

Creates a new annotation issue on a sequence. Parameters:

sequenceUid (string, required) — The UUID of the sequence
toolUid (string, required) — UUID of the annotation tool
problemUid (string, required) — UUID of the problem type
datasetItemUid (string, optional) — Dataset item UUID
projectUid (string, optional) — Project UUID
priority (string, optional) — Priority level: lowest, low, medium, high, highest
severity (string, optional) — Severity level: critical, moderate
description (string, optional) — Issue description
wrongClass (string, optional) — Incorrect class label
correctClass (string, optional) — Correct class label
objectUid (string, optional) — UUID of the annotation object
shouldReAnnotate (boolean, optional) — Whether to re-annotate
shouldDelete (boolean, optional) — Whether to delete the annotation
framesAffected (string, optional) — Frames affected by the issue

update_annotation_issue

Updates an existing annotation issue (status, priority, etc.). Parameters:

sequenceUid (string, required) — The UUID of the sequence
issueUid (string, required) — The UUID of the annotation issue
status (string, optional) — Status: open, relabeling, in_review, completed, cant_reproduce, awaiting_feedback, no_action_taken
priority (string, optional) — Priority level: lowest, low, medium, high, highest
severity (string, optional) — Severity level: critical, moderate
description (string, optional) — Updated description
toolUid (string, optional) — UUID of the annotation tool
problemUid (string, optional) — UUID of the problem type
wrongClass (string, optional) — Incorrect class label
framesAffected (string, optional) — Frames affected by the issue

delete_annotation_issue

Deletes an annotation issue. Parameters:

sequenceUid (string, required) — The UUID of the sequence
issueUid (string, required) — The UUID of the annotation issue to delete

list_annotation_issues_by_dataset

Lists all annotation issues for a dataset. Parameters:

owner (string, required) — Dataset owner username
datasetSlug (string, required) — Dataset slug
sequenceUid (string, optional) — Filter by sequence UUID

get_annotation_issue_metrics

Gets aggregated metrics for annotation issues in a dataset (status/priority/severity counts, close times). Parameters:

owner (string, required) — Dataset owner username
datasetSlug (string, required) — Dataset slug
sequenceUid (string, optional) — Filter by sequence UUID

list_qc_tools

Lists available QC annotation tools for a given dataset type. Parameters:

datasetType (string, required) — The dataset type (e.g., lidar, image, video)

fleet_list_devices

Lists fleet devices with optional filters. Parameters:

status (string, optional) — Filter by device status (online, offline, maintenance)
type (string, optional) — Filter by device type
limit (number, optional) — Maximum number of devices to return
cursor (string, optional) — Pagination cursor

Example response:

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

Gets detailed information about a specific fleet device. Parameters:

uid (string, required) — The unique identifier of the device

fleet_list_recordings

Lists fleet recordings with optional filters. Parameters:

device (string, optional) — Filter by device UID
status (string, optional) — Filter by recording status
limit (number, optional) — Maximum number of recordings to return
cursor (string, optional) — Pagination cursor

fleet_get_recording

Gets detailed information about a specific recording. Parameters:

uid (string, required) — The unique identifier of the recording

fleet_list_events

Lists fleet events with optional filters. Parameters:

recording (string, optional) — Filter by recording UID
device (string, optional) — Filter by device UID
type (string, optional) — Filter by event type
severity (string, optional) — Filter by severity
limit (number, optional) — Maximum number of events to return
cursor (string, optional) — Pagination cursor

fleet_list_alerts

Lists fleet alerts with optional filters. Parameters:

status (string, optional) — Filter by alert status (open, acknowledged, resolved)
severity (string, optional) — Filter by severity (info, warning, error, critical)
device (string, optional) — Filter by device UID
rule (string, optional) — Filter by rule UID
limit (number, optional) — Maximum number of alerts to return
cursor (string, optional) — Pagination cursor

Example response:

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

Lists fleet rules with optional filters. Parameters:

enabled (boolean, optional) — Filter by enabled status
limit (number, optional) — Maximum number of rules to return
cursor (string, optional) — Pagination cursor

fleet_register_device

Registers a new fleet device. Parameters:

name (string, required) — Name of the device
type (string, required) — Type of the device
firmwareVersion (string, optional) — Firmware version
tags (string[], optional) — Tags for the device

fleet_acknowledge_alert

Acknowledges a fleet alert. Parameters:

uid (string, required) — The unique identifier of the alert to acknowledge

Recipes

Multi-step workflows you can run through natural language. Each recipe shows the tool calls the assistant makes behind the scenes.

Recipe 1: Dataset health check

Ask your assistant: “Give me a health check on my workspace — how many datasets do I have, and which ones have the most items?” Step 1 — The assistant calls get_workspace_stats to get the overview.

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

Step 2 — The assistant calls list_datasets with limit: 50 to fetch all datasets. Step 3 — The assistant sorts the results by itemCount and presents a ranked summary:

You have 14 datasets. The three largest are:

Warehouse Cameras — 34,200 items (image)

Urban Driving Q1 — 12,450 items (lidar)

Parking Lot Footage — 8,900 items (video)

Recipe 2: Export and download

Ask your assistant: “Export the Urban Driving Q1 project and let me know when it’s ready.” Step 1 — The assistant calls list_projects to find the project UID matching “Urban Driving Q1.” Step 2 — The assistant calls create_export with the project UID.

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

Step 3 — The assistant polls get_export_status until the status changes to 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"
}

Step 4 — The assistant provides the download link and file size.

Your export is ready (50 MB). Download it here: https://api.avala.ai/exports/.../download

Recipe 3: Quality audit across projects

Ask your assistant: “Evaluate quality targets for all my projects and flag any that are failing.” Step 1 — The assistant calls list_projects to retrieve all projects. Step 2 — For each project, the assistant calls evaluate_quality with the project UID. Step 3 — The assistant aggregates the results and highlights failures:

5 of 7 projects are passing all quality targets. Two need attention:

Sidewalk Segmentation — “Label accuracy” target at 88% (threshold: 95%)

Fleet Camera Review — “Consensus score” target at 0.72 (threshold: 0.85)

Recipe 4: Fleet device monitoring

Ask your assistant: “Show me all fleet alerts that haven’t been acknowledged yet, grouped by severity.” Step 1 — The assistant calls fleet_list_alerts with status: "open". Step 2 — The assistant groups and formats the response:

Critical (1)

Dock Camera 3 — “Device offline for more than 24 hours” (since Mar 18)

Warning (2)

Forklift Sensor Unit 12 — “Device temperature exceeded threshold (72C)” (since Mar 19)

Rooftop LiDAR 1 — “Low disk space (< 5%)” (since Mar 19)

Step 3 — You can follow up: “Acknowledge all the warning-level alerts.” The assistant calls fleet_acknowledge_alert for each warning alert UID.

Recipe 5: Annotation issue triage

Ask your assistant: “Get the annotation issue metrics for the urban-driving-q1 dataset and show me the breakdown.” Step 1 — The assistant calls get_annotation_issue_metrics with owner and dataset slug. Step 2 — The assistant presents a formatted summary:

Urban Driving Q1 — Issue Metrics By status: 12 open, 5 in review, 3 relabeling, 45 completed By severity: 8 critical, 57 moderate By priority: 2 highest, 6 high, 18 medium, 25 low, 14 lowest Average close time: 4.2 hours

Step 3 — You follow up: “List the open critical issues.” The assistant calls list_annotation_issues_by_dataset with filters and shows the results.

Example Prompts

Here are some natural-language prompts you can use with any MCP-compatible client:

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"

The AI assistant will call the appropriate Avala MCP tool, process the response, and present the results in a readable format. You can chain requests in a single conversation — for example, list datasets, pick one, then view export status.

Troubleshooting

`AVALA_API_KEY` not set

The MCP server exits immediately with error code 1 if the AVALA_API_KEY environment variable is missing. Make sure the key is set in the env block of your MCP config or exported in your shell before launching the server.

Error: AVALA_API_KEY environment variable is required

Mutation tools not appearing

If tools like create_export, create_agent, or fleet_register_device are missing from the tool list, you need to set AVALA_MCP_ENABLE_MUTATIONS=true in the server environment. Add it to the env block in your MCP configuration file:

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

`npx` not found or wrong Node.js version

The MCP server requires Node.js 18 or later. If you see npx: command not found or module syntax errors, verify your Node.js version:

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

Stale cached MCP server

If you recently updated the @avala-ai/mcp-server package but still see old behavior or missing tools, npx may be serving a cached version. Force a fresh install:

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

Then restart your MCP client.

API key invalid or expired

If tool calls return 401 Unauthorized, your API key may be invalid, expired, or revoked. Generate a new key in Mission Control under Settings > Security and update your MCP configuration.

The Avala MCP server is open source. Visit the GitHub repository to view the source code or contribute.

Integrations

Documentation Index

​Prerequisites

​Setup

​Claude Desktop

​Cursor

​VS Code

​Claude Code

​ChatGPT

​MCP Security Mode

​Available MCP Tools

​Fleet (Preview)

​Tool Definitions

​list_datasets

​get_dataset

​list_sequences

​get_sequence

​get_frame

​get_calibration

​get_dataset_health

​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

​Recipes

​Recipe 1: Dataset health check

​Recipe 2: Export and download

​Recipe 3: Quality audit across projects

​Recipe 4: Fleet device monitoring

​Recipe 5: Annotation issue triage

​Example Prompts

​Troubleshooting

​AVALA_API_KEY not set

​Mutation tools not appearing

​npx not found or wrong Node.js version

​Stale cached MCP server

​API key invalid or expired

Prerequisites

Setup

Claude Desktop

Cursor

VS Code

Claude Code

ChatGPT

MCP Security Mode

Available MCP Tools

Fleet (Preview)

Tool Definitions

list_datasets

get_dataset

list_sequences

get_sequence

get_frame

get_calibration

get_dataset_health

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

Recipes

Recipe 1: Dataset health check

Recipe 2: Export and download

Recipe 3: Quality audit across projects

Recipe 4: Fleet device monitoring

Recipe 5: Annotation issue triage

Example Prompts

Troubleshooting

`AVALA_API_KEY` not set

Mutation tools not appearing

`npx` not found or wrong Node.js version

Stale cached MCP server

API key invalid or expired