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

# MCP Server

> Use Avala with Claude, Claude Code, Cursor, VS Code, and ChatGPT through the Model Context Protocol

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://avala.ai/settings?section=security) 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:

<Warning>
  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`.
</Warning>

```json theme={null}
{
  "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):

<Warning>
  `.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.
</Warning>

```json theme={null}
{
  "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:

<Warning>
  `.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.
</Warning>

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

Make sure you have the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=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:

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

Set your API key as an environment variable:

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

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

### ChatGPT

<Tip>
  ChatGPT's MCP support is evolving. Refer to
  [OpenAI's documentation](https://platform.openai.com/docs) for the latest
  setup instructions and availability in your plan and region.
</Tip>

## MCP Security Mode

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

```bash theme={null}
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`, `test_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. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `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. *(requires `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                  |
| `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)

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

| 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. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `fleet_acknowledge_alert` | Acknowledge a fleet alert. <span className="text-orange-500 text-xs font-medium">mutation</span>   |

## 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:**

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

### get\_dataset

Gets details for a specific dataset.

**Parameters:**

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

**Example response:**

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

**Error response (invalid UID):**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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`
* `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:**

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

### get\_export\_status

Checks the status of an export.

**Parameters:**

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

**Example response:**

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

### list\_exports

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:**

```json theme={null}
{
  "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:**

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

### get\_task

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:**

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

### fleet\_get\_device

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:**

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

### fleet\_list\_rules

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.

```json theme={null}
{
  "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:
>
> 1. **Warehouse Cameras** — 34,200 items (image)
> 2. **Urban Driving Q1** — 12,450 items (lidar)
> 3. **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.

```json theme={null}
{
  "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`.

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

**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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](https://avala.ai/settings?section=security) under **Settings > Security** and update your MCP configuration.

<Tip>
  The Avala MCP server is open source. Visit the [GitHub repository](https://github.com/avala-ai/avala-sdk-ts) to view the source code or contribute.
</Tip>