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, captures, quality results, and exports as tools that any MCP-compatible client can call, so you can manage your data operations through natural language without switching context.

Two ways to connect

	Hosted server (recommended)	Local server
Address	`https://mcp.avala.ai/mcp`	`npx -y @avala-ai/mcp-server` on your machine
Sign-in	Your Avala account (OAuth) — or an API key for automation	Avala API key
Install	None	Node.js 20+
Tools	Read tools permitted for your credential	Read-only by default; legacy write tools with `AVALA_MCP_ENABLE_MUTATIONS=true`
Best for	Claude, ChatGPT, Codex, Cursor, Grok, VS Code, and any remote-MCP client	Scripts, CI, air-gapped machines, and legacy write operations

Both run the same tool catalog against the same Avala API, scoped to what your account can already see.

Hosted server

Enter https://mcp.avala.ai/mcp wherever your assistant asks for an MCP server or custom connector, then sign in with your Avala account. Step-by-step instructions for every client are on Use Avala with AI.

Using an API key with the hosted server

Automation, CI pipelines, and clients that cannot open a browser can authenticate with an Avala API key instead of signing in. Send it on every request as either header:

X-Avala-Api-Key: <your key>

Authorization: Bearer <your key>

Most clients accept a fixed header on a remote server entry; for example in Cursor or VS Code add "headers": {"X-Avala-Api-Key": "<your key>"} next to the url. The key’s scopes decide which tools are listed and callable.

Never commit config files containing real API keys to version control. Prefer a system environment variable and reference it from the config file where your client supports that.

Local server

The local server runs on your machine with Node.js and talks to the Avala API with your API key. Use it when you need the legacy write catalog (create datasets, trigger exports, manage webhooks) or when your environment cannot reach mcp.avala.ai.

Prerequisites

Node.js 20 or later
An Avala API key (generate one in Mission Control under Settings > Security)

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 and VS Code

Use the same command / args / env block as above in .cursor/mcp.json (Cursor) or .vscode/mcp.json (VS Code, under "servers"). Both files may be committed to git — add them to .gitignore or reference AVALA_API_KEY from your environment instead of writing the key into the file.

Claude Code

claude mcp add avala -- npx -y @avala-ai/mcp-server
export AVALA_API_KEY="your-api-key"

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

MCP Security Mode

For safety, the local stdio MCP server is read-only by default. Its legacy 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. The hosted server ignores this flag. Tools remain limited to those permitted for your credential. 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
create_annotation_pipeline
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.
`preview_curation_candidates`	Preview a bounded set of Physical AI training candidates under an explicit workflow or QC criterion without creating a Slice or changing state.
`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.
`get_dataset_readiness`	Check reconstruction prerequisites for a selected recipe with named, evidence-backed outcomes.
`list_capture_submissions`	List a dataset’s Physical AI captures with media metadata, review state, machine acceptance summary, and campaign context.
`get_capture_submission`	Get one Physical AI capture submission by result ID.
`list_capture_campaigns`	List every Physical AI capture campaign feeding a dataset with per-description and dataset-level progress.
`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 and request an opaque download-asset handle with `detail: "full"`.
`list_exports`	List all exports. Request `detail: "full"` for opaque download-asset handles.
`resolve_asset_handle`	Exchange an opaque asset handle for a fresh URL through an MCP confirmation prompt.
`get_workspace_stats`	Get bounded resource counts: `countStatus` distinguishes exact totals from lower bounds; unavailable sections are omitted and marked `degraded`.
`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`)
`inspect_customer_qc_context`	Inspect workflow metadata for an enrolled nonstaff customer organization editor’s exact cuboid deliverable. Requires datasets.read AND qc.read; pilot enrollment is default-off, and enrollment, current role, and tenant authorization remain server-enforced. Always returns decisionReady=false and all blockers. Available decisions are workflow transitions, not approval authority. Hashes describe workflow metadata only: no annotation revision fence, annotation bytes, media, proposal, approval receipt, or QC mutation. Unavailable targets fail without a legacy-route fallback.
`list_quality_targets`	List quality targets for a project.
`get_result_acceptance`	Explain one capture’s machine verdict with criterion outcomes and measured evidence.
`get_campaign_acceptance_summary`	Compare machine and reviewer acceptance, agreement, and rejection drivers for a capture campaign.
`get_campaign_acceptance_coverage`	Find under-covered and unfilled values across accepted captures in a campaign.
`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.

Workflows

Higher-level tools that compose several API calls, and cross-cutting overviews.

Tool	Description
`get_workspace_overview`	High-level overview of the workspace — organizations, recent datasets, projects, and exports. Good first call after connecting (‘what do I have?’).
`get_project_quality_summary`	Quality picture for a project — details, quality-target breach status, and consensus scores.
`get_fleet_health`	Fleet health overview — bounded device, alert, and recording probes (up to 100 devices, 100 alerts, and 20 recordings), with `hasMore` flags for incomplete sections.
`create_annotation_pipeline`	Create a dataset and optionally trigger an export for a project in one call. The dataset is created first; if the export fails, the response returns the created dataset plus the export error so nothing is lost. mutation

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 authorized workspace datasets by private, unlisted, or public on supporting servers. A known Unlisted link does not grant workspace access.
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

preview_curation_candidates

Previews a bounded, read-only set of dataset items or sequences that satisfy one explicit workflow or quality criterion. The response separates selected candidates from completed-Slice membership, missing evidence, and rejected evidence, and returns an opaque cursor when more candidates are available. It never creates a Slice, recomputes quality evidence, or changes workflow state. The API key always needs datasets.read. Criteria that inspect project results, quality evidence, or an exclusion Slice also require the corresponding projects.read, tasks.read, qc.read, or slices.read scopes. Consensus criteria currently fail closed as insufficient evidence until scores include immutable run provenance. Parameters:

datasetUid (string, required) — Dataset UUID
unit (string, required) — Candidate unit: dataset_item or sequence
qcDimension (string, required) — Evidence dimension: sequence_workflow, result_status, object_qc_status, consensus, or deliverable
requiredState (string, optional) — Required state for workflow, result, object-QC, or deliverable criteria
minimumConsensus (number, optional) — Minimum score for a consensus criterion
projectUid (string, optional) — Project UUID for result-status or consensus evidence
taskName (string, optional) — Task type for result, object-QC, or consensus evidence
deliverableId (string, optional) — Deliverable identifier from the dataset’s active workflow revision
deliverableStateField (string, optional) — Deliverable field to compare: workflow_state, approval_state, or approval_outcome
excludeSliceUid (string, optional) — Completed Slice whose existing membership should be excluded
limit (number, optional) — Maximum candidate identifiers to return (default 25, max 100)
cursor (string, optional) — Opaque cursor returned by a previous request using the same dataset and criterion

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
    }
  ]
}

get_dataset_readiness

Checks whether a dataset satisfies the prerequisites of a selected photoreal-reconstruction recipe. The response contains named pass, fail, insufficient_evidence, or skipped checks instead of a single readiness score or boolean. You must declare which stored calibration artifacts the recipe requires. The health endpoint cannot distinguish a sensor that is absent from one that is present but uncalibrated, so the tool never guesses. A missing required calibration blocks reconstruction; a calibration the recipe does not require is reported as skipped. Dataset presence is evaluated using the server’s actual media shape. Sequence datasets must contain frames. When requiredCalibrations is empty, a non-sequence dataset can instead satisfy the presence check with one or more media assets. Any recipe that requires stored calibration remains sequence-only because the health endpoint exposes those artifacts per sequence. Parameters:

owner (string, required) — Dataset owner username, handle, or organization slug
slug (string, required) — Dataset slug
requiredCalibrations (array, required) — Use ["camera", "lidar"] for a calibrated multisensor rebuild, ["camera"] for a calibrated camera-only rig, or [] only when the selected recipe estimates calibration from its input and may accept non-sequence media assets

Example response (truncated):

{
  "datasetUid": "d8f2e1a4-3b7c-4e9f-a1d6-5c8b9e0f2a3d",
  "datasetSlug": "urban-driving-q1",
  "purpose": "reconstruction",
  "frameCount": 569,
  "requiredCalibrations": ["camera", "lidar"],
  "summary": "Reconstruction is blocked: Every sequence is missing LiDAR calibration required by the selected reconstruction recipe.",
  "checks": [
    {
      "key": "lidar_calibration",
      "status": "fail",
      "severity": "blocking",
      "reason": "Every sequence is missing LiDAR calibration required by the selected reconstruction recipe.",
      "remediation": "Calibrate LiDAR on each sequence (upload the canonical rig, or call get_calibration after a successful calibration write), then run this check again.",
      "evidence": {
        "required": true,
        "sequencesChecked": 1,
        "missingCount": 1
      }
    }
  ],
  "blockingReasons": ["lidar_calibration"],
  "unmeasured": []
}

list_capture_submissions

Lists a dataset’s Physical AI capture submissions with media metadata, human review state, machine acceptance summary, and campaign task context. Provider-signed playback and thumbnail URLs are intentionally omitted so bearer capabilities never enter model-provider logs or conversation transcripts. Parameters:

datasetUid (string, required) — Dataset UUID
status (string (pending, accepted, rejected, overlooked), optional) — Filter by result status
limit (number, optional) — Maximum number of results to return
cursor (string, optional) — Pagination cursor from a previous request

get_capture_submission

Gets one Physical AI capture submission by result ID, including media metadata, reviewer decision, machine acceptance summary, and campaign task context. With detail: "full", provider-signed media URLs become opaque playback and thumbnail handles. Parameters:

resultUid (string, required) — Capture result UUID

list_capture_campaigns

Lists every Physical AI capture campaign feeding a dataset, oldest first. Each campaign includes its task descriptions and capture config, mutually exclusive slot-progress buckets, and a canManage authorization hint. The top-level progress is the roll-up across every campaign feeding the dataset; datasets without campaigns return an empty list and zero counts. Parameters:

datasetUid (string, required) — Dataset UUID

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, public, or unlisted on supporting servers (default: private). Unlisted allows known-link previews, not broad discovery or extra workspace access. Initial manual uploads remain private-only.
createMetadata (boolean, optional) — Whether to create dataset metadata (default: true)
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",
  "downloadAsset": {
    "handle": "ah_opaque_example"
  },
  "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

resolve_asset_handle

Exchanges an opaque handle for a fresh asset URL. The MCP server first requests confirmation through protocol elicitation and verifies a short-lived challenge bound to that exact handle. It then reads the original resource again with your current credential before returning the URL. Unsupported, declined, forged, or cross-handle replayed confirmation releases no URL; revoked resource access also fails. expiresAt is null when the storage provider does not declare an expiry in the URL. Your MCP client must support elicitation. Handles expire after 15 minutes and contain no URL or API credential. Parameters:

handle (string, required) — An opaque ah_... handle returned by another MCP tool

Example response:

{
  "url": "https://storage-provider.example/temporary-download",
  "expiresAt": "2026-03-19T11:02:34.000Z"
}

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
s3IsAccelerated (boolean, optional) — Enable S3 Transfer Acceleration
gcStorageBucketName (string, optional) — Google Cloud Storage bucket name
gcStoragePrefix (string, optional) — Google Cloud Storage prefix

Credentials are intentionally not accepted by MCP tools. Provision them separately through the Avala web console under Settings → Storage so secrets do not enter model context, transcripts, or client logs.

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

inspect_customer_qc_context

Inspect workflow metadata for an enrolled nonstaff customer organization editor’s exact cuboid deliverable. Requires datasets.read AND qc.read; pilot enrollment is default-off, and enrollment, current role, and tenant authorization remain server-enforced. Always returns decisionReady=false and all blockers. Available decisions are workflow transitions, not approval authority. Hashes describe workflow metadata only: no annotation revision fence, annotation bytes, media, proposal, approval receipt, or QC mutation. Unavailable targets fail without a legacy-route fallback. Parameters:

organizationUid (string, required) — Canonical organization UUID; enrollment remains server-controlled
datasetUid (string, required) — Canonical UUID of the dataset in that organization
sequenceUid (string, required) — Canonical UUID of the sequence in that dataset
deliverableId (string, required) — Pilot deliverable identifier; only ‘cuboids’ is supported

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

get_result_acceptance

Gets the machine acceptance verdict for one capture submission, including each criterion outcome, blocking reasons, unmeasured checks, engine and policy versions, and the measured signals behind the decision. The endpoint is tenant-scoped and returns 404 when the result is unscored or inaccessible. Parameters:

resultUid (string, required) — The unique identifier (UUID) of the capture result

get_campaign_acceptance_summary

Gets machine and reviewer acceptance rates for a capture campaign, plus agreement, device-tier and operator breakdowns, and the most common rejection reasons. Parameters:

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

get_campaign_acceptance_coverage

Gets coverage occupancy across captures that reviewers accepted. Cells are ordered with the thinnest coverage first, and each axis reports captures with no value as unfilled. Parameters:

projectUid (string, required) — The unique identifier (UUID) of the campaign project
axes (string, optional) — Comma-separated coverage axes, for example subject,environment,device_tier

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

get_workspace_overview

Get a high-level overview of the workspace — organizations, recent datasets, recent projects, and recent exports. Use when a user first connects or asks “what do I have?”. Parameters: None

get_project_quality_summary

Get a quality picture for a project — project details, quality-target breach status, and consensus scores. Up to 50 quality targets are returned; the result includes hasMore when additional targets were not included. qualityTargets.returnedCount counts the returned page. qualityTargets.total remains a deprecated alias for one release; neither field is a full-project total when hasMore is true. Parameters:

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

get_fleet_health

Get a fleet health overview — bounded device, alert, and recording probes (up to 100 devices, 100 alerts, and 20 recordings). Each section includes hasMore when its result is incomplete. Parameters:

deviceType (string, optional) — Optional filter by device type

create_annotation_pipeline

Create a dataset and optionally trigger an export for a project. The dataset is always created first; if the export step fails, the response includes the dataset that was created and the export error so nothing is silently lost. (requires AVALA_MCP_ENABLE_MUTATIONS=true) Parameters:

name (string, required) — Display name for the new dataset
slug (string, required) — URL-friendly identifier for the new dataset
dataType (string, required) — Type of data: ‘image’, ‘video’, ‘lidar’, ‘mcap’, or ‘splat’
projectUid (string, optional) — If provided, an export is created for this project after the dataset is created

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",
  "downloadAsset": {
    "handle": "ah_opaque_example"
  },
  "fileSize": 52428800,
  "completedAt": "2026-03-19T10:02:34Z"
}

Step 4 — After you confirm that you want the artifact, the assistant calls resolve_asset_handle with downloadAsset.handle and provides the fresh download link.

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: “For this dataset, find the two oldest currently open critical annotation issues created by my reference timestamp, and compute their ages at that timestamp. Inspect each issue’s reported sequence, project, object and frames, then its current cuboids workflow context. Report blockers; do not change any work.” Supply the exact owner and dataset slug, a UTC age-reference timestamp, and the canonical organization UUID for your enrolled pilot. The credential needs datasets.read and qc.read. Enrollment is default-off and server-controlled; an organization UUID is not inferred from an owner slug or a project UUID. Step 1 — Call list_datasets and follow every nextCursor with unchanged filters until the returned ownerName and slug match the supplied owner/slug. Retain the returned dataset UUID and use ownerName as the issue tool’s owner argument; do not substitute a project UUID or a similarly named dataset. A denied source is an error, not an empty collection. Step 2 — Call list_annotation_issues_by_dataset with owner, datasetSlug, and detail: "full". This tool exposes neither status/severity filters nor pagination. Filter its returned items locally to current status: "open", severity: "critical", closedAt: null, and createdAt on or before your reference timestamp. Sort oldest first and select two. Compute ages from createdAt to the reference timestamp. This uses current issue status, not reconstructed historical status; a report closed after the reference date is still excluded if it is closed now. Step 3 — For each selected issue with a non-null sequenceUid, call list_annotation_issues_by_sequence with that UID and detail: "full"; include projectUid: project.uid only when project is non-null. Match the exact issue UID and retain its dataset-item, object and frame identifiers, including nulls. If the issue disappears or its relevant fields change, report that change instead of treating the earlier result as current evidence. These are issue-report fields, not independent validation of the underlying annotations. Retain item-scoped reports with sequenceUid: null in the triage result, but mark their sequence inspection and workflow context unavailable; do not invent a sequence, substitute the item UUID, or drop the report. Step 4 — For each issue whose exact sequence evidence was confirmed in step 3, call inspect_customer_qc_context with the supplied organizationUid, the dataset UUID from step 1 as datasetUid, the issue’s non-null sequenceUid, and deliverableId: "cuboids". Keep each result tied to that exact target. Do not reuse another sequence’s context. If the tool is unavailable or a call fails, report that target’s context as unavailable; do not replace it with an empty result, reuse an earlier success, or fall back to a write tool. Step 5 — Present the issue identifiers and ages separately from the current workflow states, workflow revision, metadata hash, decisionReady, and every blocker. Each call is a separate observation, not an atomic annotation snapshot. The age-reference timestamp does not date the workflow observation. availableDecisions lists configured transitions; even an approved outcome there grants no approval authority. The inspection contract always returns decisionReady: false. Metadata hashes are not annotation revision fences, approval receipts, or proof that anyone inspected the annotations. This recipe stops at read-only triage. It does not resolve reports, approve/reject annotations, submit proposals, or establish that a customer QC decision is safe to execute.

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 local stdio 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"
  }
}

The hosted server ignores AVALA_MCP_ENABLE_MUTATIONS; reconnect after changing your credential or its scopes.

`npx` not found or wrong Node.js version

The MCP server requires Node.js 20 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.

​Two ways to connect

​Hosted server

​Using an API key with the hosted server

​Local server

​Prerequisites

​Claude Desktop

​Cursor and VS Code

​Claude Code

​MCP Security Mode

​Available MCP Tools

​Workflows

​Fleet (Preview)

​Tool Definitions

​list_datasets

​get_dataset

​list_sequences

​get_sequence

​preview_curation_candidates

​get_frame

​get_calibration

​get_dataset_health

​get_dataset_readiness

​list_capture_submissions

​get_capture_submission

​list_capture_campaigns

​list_projects

​get_project

​create_dataset

​create_export

​get_export_status

​list_exports

​resolve_asset_handle

​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

​inspect_customer_qc_context

​list_quality_targets

​get_result_acceptance

​get_campaign_acceptance_summary

​get_campaign_acceptance_coverage

​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

​get_workspace_overview

​get_project_quality_summary

​get_fleet_health

​create_annotation_pipeline

​Recipes

​Recipe 1: Dataset health check

Two ways to connect

Hosted server

Using an API key with the hosted server

Local server

Prerequisites

Claude Desktop

Cursor and VS Code

Claude Code

MCP Security Mode

Available MCP Tools

Workflows

Fleet (Preview)

Tool Definitions

list_datasets

get_dataset

list_sequences

get_sequence

preview_curation_candidates

get_frame

get_calibration

get_dataset_health

get_dataset_readiness

list_capture_submissions

get_capture_submission

list_capture_campaigns

list_projects

get_project

create_dataset

create_export

get_export_status

list_exports

resolve_asset_handle

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

inspect_customer_qc_context

list_quality_targets

get_result_acceptance

get_campaign_acceptance_summary

get_campaign_acceptance_coverage

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

get_workspace_overview

get_project_quality_summary

get_fleet_health

create_annotation_pipeline

Recipes

Recipe 1: Dataset health check