MCP Server - Avala Documentation

Model Context Protocol (MCP)은 AI 어시스턴트가 외부 도구 및 데이터 소스와 상호작용할 수 있게 해주는 개방형 표준입니다. Avala의 MCP server는 datasets, projects 및 exports를 MCP 호환 client가 호출할 수 있는 도구로 노출하므로, 컨텍스트를 전환하지 않고 자연어를 통해 annotation 워크플로우를 관리할 수 있습니다. 즉, Claude에게 “내 모든 datasets 목록을 보여줘”라고 요청하거나, Cursor로 export를 생성하거나, VS Code로 project 상태를 확인할 수 있습니다. 이 모든 것은 이미 사용하고 계신 동일한 Avala API로 구동됩니다.

사전 요구사항

Node.js 18 이상이 설치되어 있어야 합니다
Avala API key (Mission Control의 Settings > Security에서 생성)

설정

Claude Desktop

Claude Desktop 설정 파일을 여세요:

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

Avala MCP server를 추가하세요:

실제 API keys가 포함된 config 파일을 버전 관리에 커밋하지 마세요. AVALA_API_KEY를 시스템 environment variable로 설정하거나, "your-api-key"를 로컬에서 실제 key로 교체하고 config 파일이 .gitignore에 포함되어 있는지 확인하세요.

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

Claude Desktop을 다시 시작하세요. 도구 선택기에서 Avala 도구를 사용할 수 있습니다.

Cursor

프로젝트 루트(또는 글로벌 config 디렉터리)에서 .cursor/mcp.json을 생성하거나 편집하세요:

.cursor/mcp.json은 프로젝트 루트에 있으며 git에 커밋될 수 있습니다. .gitignore에 추가하거나, config 파일에 직접 넣는 대신 AVALA_API_KEY를 시스템 environment variable로 설정하세요.

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

Cursor를 다시 시작하거나 창을 다시 로드하세요. Cursor의 agent mode에서 Avala 도구가 나타납니다.

VS Code

워크스페이스에서 .vscode/mcp.json을 생성하거나 편집하세요:

.vscode/mcp.json은 워크스페이스에 있으며 git에 커밋될 수 있습니다. .gitignore에 추가하거나, config 파일에 직접 넣는 대신 AVALA_API_KEY를 시스템 environment variable로 설정하세요.

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

MCP 지원이 활성화된 GitHub Copilot 확장이 설치되어 있는지 확인하세요. 새 server를 인식하려면 VS Code를 다시 시작하세요.

Claude Code

단일 명령어로 Claude Code에 Avala MCP server를 추가하세요:

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

API key를 environment variable로 설정하세요:

export AVALA_API_KEY="your-api-key"

Claude Code를 다시 시작하세요. 세션에서 Avala 도구를 사용할 수 있습니다.

ChatGPT

ChatGPT의 MCP 지원은 발전 중입니다. 최신 설정 안내 및 플랜과 지역에서의 사용 가능 여부는 OpenAI 문서를 참조하세요.

MCP 보안 모드

안전을 위해 MCP server는 기본적으로 읽기 전용입니다. 변경 도구는 명시적으로 활성화하지 않으면 등록되지 않습니다:

AVALA_MCP_ENABLE_MUTATIONS=true

이 environment variable은 server를 시작하기 전에 MCP server 프로세스 환경에서 설정할 수 있습니다. 기본적으로 다음 쓰기/삭제 작업이 차단됩니다:

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

사용 가능한 MCP 도구

연결되면 AI 어시스턴트에서 다음 도구를 사용할 수 있습니다:

도구	설명
`list_datasets`	워크스페이스의 모든 datasets를 나열합니다.
`get_dataset`	특정 dataset의 상세 정보를 가져옵니다.
`create_dataset`	annotation을 위한 새 dataset을 생성합니다. mutation
`list_projects`	모든 annotation projects를 나열합니다.
`get_project`	전체 project 상세 정보를 가져옵니다.
`create_export`	dataset 또는 project에 대한 새 export를 트리거합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`get_export_status`	export 상태를 확인합니다.
`list_exports`	모든 exports를 나열합니다.
`get_workspace_stats`	워크스페이스 사용 요약을 가져옵니다.
`list_tasks`	선택적 필터링으로 tasks를 나열합니다.
`get_task`	task 상세 정보를 가져옵니다.
`list_agents`	automation agents를 나열합니다.
`get_agent`	agent 상세 정보를 가져옵니다.
`create_agent`	새 automation agent를 생성합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`delete_agent`	agent를 삭제합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`list_webhooks`	webhook subscriptions를 나열합니다.
`create_webhook`	webhook subscription을 생성합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`delete_webhook`	webhook을 삭제합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`list_storage_configs`	storage configurations를 나열합니다.
`create_storage_config`	storage configuration을 생성합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`test_storage_config`	storage 연결을 테스트합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`delete_storage_config`	storage configuration을 삭제합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`list_quality_targets`	project의 quality targets를 나열합니다.
`evaluate_quality`	quality targets를 평가합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`get_consensus_summary`	project의 consensus 요약을 가져옵니다.
`compute_consensus`	consensus 계산을 트리거합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`list_organizations`	organizations를 나열합니다.
`get_organization`	organization 상세 정보를 가져옵니다.
`list_slices`	owner의 slices를 나열합니다.
`get_slice`	slice 상세 정보를 가져옵니다.
`list_annotation_issues_by_sequence`	sequence의 annotation issues를 나열합니다.
`create_annotation_issue`	새 annotation issue를 생성합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`update_annotation_issue`	annotation issue를 업데이트합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`delete_annotation_issue`	annotation issue를 삭제합니다. (`AVALA_MCP_ENABLE_MUTATIONS=true` 필요)
`list_annotation_issues_by_dataset`	dataset의 annotation issues를 나열합니다.
`get_annotation_issue_metrics`	dataset의 issue metrics를 가져옵니다.
`list_qc_tools`	사용 가능한 QC 도구를 나열합니다.

Fleet (미리보기)

Fleet 도구는 미리보기 상태이며 변경될 수 있습니다. fleet devices, recordings, events, alerts 및 rules에 대한 읽기 및 쓰기 액세스를 제공합니다.

도구	설명
`fleet_list_devices`	선택적 필터로 fleet devices를 나열합니다.
`fleet_get_device`	특정 fleet device의 상세 정보를 가져옵니다.
`fleet_list_recordings`	선택적 필터로 fleet recordings를 나열합니다.
`fleet_get_recording`	특정 recording의 상세 정보를 가져옵니다.
`fleet_list_events`	선택적 필터로 fleet events를 나열합니다.
`fleet_list_alerts`	선택적 필터로 fleet alerts를 나열합니다.
`fleet_list_rules`	선택적 필터로 fleet rules를 나열합니다.
`fleet_register_device`	새 fleet device를 등록합니다. mutation
`fleet_acknowledge_alert`	fleet alert를 확인합니다. mutation

도구 정의

각 MCP 도구의 상세 스키마입니다. 모든 도구는 JSON을 text content로 반환합니다.

list_datasets

워크스페이스의 모든 datasets를 나열합니다. Parameters:

dataType (string, optional) — 데이터 유형별 필터 (image, video, lidar, mcap, splat)
name (string, optional) — dataset 이름별 필터 (부분 일치)
status (string, optional) — dataset 상태별 필터
visibility (string, optional) — 가시성별 필터 (private 또는 public)
limit (number, optional) — 반환할 최대 datasets 수
cursor (string, optional) — 이전 요청의 pagination cursor

응답 예시:

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

특정 dataset의 상세 정보를 가져옵니다. Parameters:

uid (string, required) — dataset의 고유 식별자 (UUID)

응답 예시:

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

오류 응답 (잘못된 UID):

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

list_projects

모든 annotation projects를 나열합니다. Parameters:

limit (number, optional) — 반환할 최대 projects 수
cursor (string, optional) — 이전 요청의 pagination cursor

get_project

특정 project의 상세 정보를 가져옵니다. Parameters:

uid (string, required) — project의 고유 식별자 (UUID)

create_dataset

annotation을 위한 새 dataset을 생성합니다. Parameters:

name (string, required) — dataset의 표시 이름
slug (string, required) — dataset의 URL 친화적 식별자
dataType (string, required) — 데이터 유형: image, video, lidar 또는 mcap
visibility (string, optional) — dataset 가시성: private 또는 public (기본값: private)
createMetadata (boolean, optional) — dataset metadata를 생성할지 여부 (기본값: true)
providerConfig (object, optional) — 클라우드 스토리지 provider 설정
ownerName (string, optional) — dataset owner 사용자 이름 또는 이메일

create_export

dataset 또는 project에 대한 새 export를 트리거합니다. Parameters:

project (string, optional) — export할 project UID
dataset (string, optional) — export할 dataset UID

응답 예시:

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

get_export_status

export의 상태를 확인합니다. Parameters:

uid (string, required) — export의 고유 식별자 (UUID)

응답 예시:

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

list_exports

워크스페이스의 모든 exports를 나열합니다. Parameters:

limit (number, optional) — 반환할 최대 exports 수
cursor (string, optional) — 이전 요청의 pagination cursor

get_workspace_stats

워크스페이스 내용(datasets, projects, exports)의 빠른 확인을 가져옵니다. Parameters: 없음 응답 예시:

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

list_tasks

project 또는 상태별 선택적 필터링으로 tasks를 나열합니다. Parameters:

project (string, optional) — project UID별 필터
status (string, optional) — task 상태별 필터
limit (number, optional) — 반환할 최대 tasks 수
cursor (string, optional) — 이전 요청의 pagination cursor

응답 예시:

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

특정 task의 상세 정보를 가져옵니다. Parameters:

uid (string, required) — task의 고유 식별자 (UUID)

list_agents

워크스페이스에 설정된 모든 automation agents를 나열합니다. Parameters:

limit (number, optional) — 반환할 최대 agents 수
cursor (string, optional) — 이전 요청의 pagination cursor

get_agent

특정 automation agent의 상세 정보를 가져옵니다. Parameters:

uid (string, required) — agent의 고유 식별자 (UUID)

create_agent

event subscriptions 및 callback URL을 가진 새 automation agent를 생성합니다. Parameters:

name (string, required) — agent의 이름
events (string[], required) — agent가 구독하는 event 유형 목록
callbackUrl (string, optional) — event callbacks를 수신할 URL
description (string, optional) — agent 설명
project (string, optional) — agent 범위를 지정할 project UID
taskTypes (string[], optional) — agent가 처리하는 task 유형

delete_agent

UID로 automation agent를 삭제합니다. Parameters:

uid (string, required) — 삭제할 agent의 고유 식별자 (UUID)

list_webhooks

워크스페이스의 모든 webhook subscriptions를 나열합니다. Parameters:

limit (number, optional) — 반환할 최대 webhooks 수
cursor (string, optional) — 이전 요청의 pagination cursor

create_webhook

특정 events에 대한 새 webhook subscription을 생성합니다. Parameters:

targetUrl (string, required) — webhook deliveries를 수신할 URL
events (string[], required) — 구독할 event 유형 목록

delete_webhook

UID로 webhook subscription을 삭제합니다. Parameters:

uid (string, required) — 삭제할 webhook의 고유 식별자 (UUID)

list_storage_configs

워크스페이스의 모든 storage configurations를 나열합니다. Parameters:

limit (number, optional) — 반환할 최대 storage configs 수
cursor (string, optional) — 이전 요청의 pagination cursor

create_storage_config

새 storage configuration을 생성합니다 (S3 또는 Google Cloud Storage). Parameters:

name (string, required) — storage configuration의 이름
provider (string, required) — storage provider 유형 (s3 또는 gcs)
s3BucketName (string, optional) — S3 bucket 이름
s3BucketRegion (string, optional) — S3 bucket region
s3BucketPrefix (string, optional) — S3 key prefix
s3AccessKeyId (string, optional) — S3 access key ID (서버 측에서 안전하게 저장됨)
s3SecretAccessKey (string, optional) — S3 secret access key (서버 측에서 안전하게 저장됨)
s3IsAccelerated (boolean, optional) — S3 Transfer Acceleration 활성화
gcStorageBucketName (string, optional) — Google Cloud Storage bucket 이름
gcStoragePrefix (string, optional) — Google Cloud Storage prefix
gcStorageAuthJsonContent (string, optional) — GCS service account JSON credentials (서버 측에서 안전하게 저장됨)

test_storage_config

storage configuration의 연결을 테스트합니다. Parameters:

uid (string, required) — 테스트할 storage config의 고유 식별자 (UUID)

delete_storage_config

UID로 storage configuration을 삭제합니다. Parameters:

uid (string, required) — 삭제할 storage config의 고유 식별자 (UUID)

list_quality_targets

특정 project에 설정된 quality targets를 나열합니다. Parameters:

projectUid (string, required) — project의 고유 식별자 (UUID)
limit (number, optional) — 반환할 최대 quality targets 수
cursor (string, optional) — 이전 요청의 pagination cursor

evaluate_quality

project의 모든 quality targets를 평가하고 현재 상태를 반환합니다. Parameters:

projectUid (string, required) — 평가할 project의 고유 식별자 (UUID)

get_consensus_summary

평균/중앙값 점수 및 분포를 포함한 project의 consensus 요약을 가져옵니다. Parameters:

projectUid (string, required) — project의 고유 식별자 (UUID)

compute_consensus

project의 consensus 계산을 트리거합니다. Parameters:

projectUid (string, required) — project의 고유 식별자 (UUID)

list_organizations

회원으로 속해 있는 모든 organizations를 나열합니다. Parameters:

limit (number, optional) — 반환할 최대 organizations 수
cursor (string, optional) — 이전 요청의 pagination cursor

get_organization

특정 organization의 상세 정보를 가져옵니다. Parameters:

slug (string, required) — organization의 slug 식별자

list_slices

owner(사용자 또는 organization)의 slices를 나열합니다. Parameters:

owner (string, required) — owner 이름 (사용자 또는 organization slug)
limit (number, optional) — 반환할 최대 slices 수
cursor (string, optional) — 이전 요청의 pagination cursor

get_slice

특정 slice의 상세 정보를 가져옵니다. Parameters:

owner (string, required) — owner 이름 (사용자 또는 organization slug)
slug (string, required) — slice의 slug

list_annotation_issues_by_sequence

특정 sequence의 모든 annotation issues를 나열합니다. Parameters:

sequenceUid (string, required) — sequence의 UUID
datasetItemUid (string, optional) — dataset item UUID별 필터
projectUid (string, optional) — project UUID별 필터

create_annotation_issue

sequence에 새 annotation issue를 생성합니다. Parameters:

sequenceUid (string, required) — sequence의 UUID
toolUid (string, required) — annotation tool의 UUID
problemUid (string, required) — problem type의 UUID
datasetItemUid (string, optional) — dataset item UUID
projectUid (string, optional) — project UUID
priority (string, optional) — 우선순위: lowest, low, medium, high, highest
severity (string, optional) — 심각도: critical, moderate
description (string, optional) — issue 설명
wrongClass (string, optional) — 잘못된 class label
correctClass (string, optional) — 올바른 class label
objectUid (string, optional) — annotation object의 UUID
shouldReAnnotate (boolean, optional) — 재 annotation 여부
shouldDelete (boolean, optional) — annotation 삭제 여부
framesAffected (string, optional) — issue의 영향을 받는 frames

update_annotation_issue

기존 annotation issue를 업데이트합니다 (상태, 우선순위 등). Parameters:

sequenceUid (string, required) — sequence의 UUID
issueUid (string, required) — annotation issue의 UUID
status (string, optional) — 상태: open, relabeling, in_review, completed, cant_reproduce, awaiting_feedback, no_action_taken
priority (string, optional) — 우선순위: lowest, low, medium, high, highest
severity (string, optional) — 심각도: critical, moderate
description (string, optional) — 업데이트된 설명
toolUid (string, optional) — annotation tool의 UUID
problemUid (string, optional) — problem type의 UUID
wrongClass (string, optional) — 잘못된 class label
framesAffected (string, optional) — issue의 영향을 받는 frames

delete_annotation_issue

annotation issue를 삭제합니다. Parameters:

sequenceUid (string, required) — sequence의 UUID
issueUid (string, required) — 삭제할 annotation issue의 UUID

list_annotation_issues_by_dataset

dataset의 모든 annotation issues를 나열합니다. Parameters:

owner (string, required) — dataset owner 사용자 이름
datasetSlug (string, required) — dataset slug
sequenceUid (string, optional) — sequence UUID별 필터

get_annotation_issue_metrics

dataset의 annotation issues에 대한 집계 metrics를 가져옵니다 (상태/우선순위/심각도 수, 종료 시간). Parameters:

owner (string, required) — dataset owner 사용자 이름
datasetSlug (string, required) — dataset slug
sequenceUid (string, optional) — sequence UUID별 필터

list_qc_tools

지정된 dataset 유형에 사용 가능한 QC annotation 도구를 나열합니다. Parameters:

datasetType (string, required) — dataset 유형 (예: lidar, image, video)

fleet_list_devices

선택적 필터로 fleet devices를 나열합니다. Parameters:

status (string, optional) — device 상태별 필터 (online, offline, maintenance)
type (string, optional) — device 유형별 필터
limit (number, optional) — 반환할 최대 devices 수
cursor (string, optional) — pagination cursor

응답 예시:

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

특정 fleet device의 상세 정보를 가져옵니다. Parameters:

uid (string, required) — device의 고유 식별자

fleet_list_recordings

선택적 필터로 fleet recordings를 나열합니다. Parameters:

device (string, optional) — device UID별 필터
status (string, optional) — recording 상태별 필터
limit (number, optional) — 반환할 최대 recordings 수
cursor (string, optional) — pagination cursor

fleet_get_recording

특정 recording의 상세 정보를 가져옵니다. Parameters:

uid (string, required) — recording의 고유 식별자

fleet_list_events

선택적 필터로 fleet events를 나열합니다. Parameters:

recording (string, optional) — recording UID별 필터
device (string, optional) — device UID별 필터
type (string, optional) — event 유형별 필터
severity (string, optional) — 심각도별 필터
limit (number, optional) — 반환할 최대 events 수
cursor (string, optional) — pagination cursor

fleet_list_alerts

선택적 필터로 fleet alerts를 나열합니다. Parameters:

status (string, optional) — alert 상태별 필터 (open, acknowledged, resolved)
severity (string, optional) — 심각도별 필터 (info, warning, error, critical)
device (string, optional) — device UID별 필터
rule (string, optional) — rule UID별 필터
limit (number, optional) — 반환할 최대 alerts 수
cursor (string, optional) — pagination cursor

응답 예시:

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

선택적 필터로 fleet rules를 나열합니다. Parameters:

enabled (boolean, optional) — 활성화 상태별 필터
limit (number, optional) — 반환할 최대 rules 수
cursor (string, optional) — pagination cursor

fleet_register_device

새 fleet device를 등록합니다. Parameters:

name (string, required) — device의 이름
type (string, required) — device의 유형
firmwareVersion (string, optional) — firmware 버전
tags (string[], optional) — device의 tags

fleet_acknowledge_alert

fleet alert를 확인합니다. Parameters:

uid (string, required) — 확인할 alert의 고유 식별자

레시피

자연어를 통해 실행할 수 있는 다단계 워크플로우입니다. 각 레시피는 어시스턴트가 백그라운드에서 수행하는 tool calls를 보여줍니다.

레시피 1: Dataset 상태 점검

어시스턴트에게 요청하세요: “내 워크스페이스의 상태를 점검해줘 — datasets가 몇 개 있고, 어떤 것이 가장 많은 items을 가지고 있어?” 단계 1 — 어시스턴트가 get_workspace_stats를 호출하여 개요를 가져옵니다.

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

단계 2 — 어시스턴트가 limit: 50으로 list_datasets를 호출하여 모든 datasets를 가져옵니다. 단계 3 — 어시스턴트가 결과를 itemCount 기준으로 정렬하고 순위 요약을 제공합니다:

14개의 datasets가 있습니다. 가장 큰 세 개는:

Warehouse Cameras — 34,200 items (image)

Urban Driving Q1 — 12,450 items (lidar)

Parking Lot Footage — 8,900 items (video)

레시피 2: Export 및 다운로드

어시스턴트에게 요청하세요: “Urban Driving Q1 project를 export하고 준비되면 알려줘.” 단계 1 — 어시스턴트가 “Urban Driving Q1”과 일치하는 project UID를 찾기 위해 list_projects를 호출합니다. 단계 2 — 어시스턴트가 project UID로 create_export를 호출합니다.

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

단계 3 — 어시스턴트가 상태가 completed로 변경될 때까지 get_export_status를 폴링합니다.

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

단계 4 — 어시스턴트가 다운로드 링크와 파일 크기를 제공합니다.

export가 준비되었습니다 (50 MB). 여기에서 다운로드하세요: https://api.avala.ai/exports/.../download

레시피 3: Projects 전반의 품질 감사

어시스턴트에게 요청하세요: “모든 projects의 quality targets를 평가하고 실패한 것을 표시해줘.” 단계 1 — 어시스턴트가 모든 projects를 가져오기 위해 list_projects를 호출합니다. 단계 2 — 각 project에 대해 어시스턴트가 project UID로 evaluate_quality를 호출합니다. 단계 3 — 어시스턴트가 결과를 집계하고 실패 항목을 강조합니다:

7개 projects 중 5개가 모든 quality targets를 통과합니다. 두 개는 주의가 필요합니다:

Sidewalk Segmentation — “Label accuracy” 목표 88% (기준: 95%)

Fleet Camera Review — “Consensus score” 목표 0.72 (기준: 0.85)

레시피 4: Fleet device 모니터링

어시스턴트에게 요청하세요: “아직 확인되지 않은 모든 fleet alerts를 심각도별로 그룹화해서 보여줘.” 단계 1 — 어시스턴트가 status: "open"으로 fleet_list_alerts를 호출합니다. 단계 2 — 어시스턴트가 응답을 그룹화하고 포맷합니다:

Critical (1)

Dock Camera 3 — “Device offline for more than 24 hours” (3월 18일부터)

Warning (2)

Forklift Sensor Unit 12 — “Device temperature exceeded threshold (72C)” (3월 19일부터)

Rooftop LiDAR 1 — “Low disk space (< 5%)” (3월 19일부터)

단계 3 — 후속 요청: “모든 warning 레벨 alerts를 확인해줘.” 어시스턴트가 각 warning alert UID에 대해 fleet_acknowledge_alert를 호출합니다.

레시피 5: Annotation issue 분류

어시스턴트에게 요청하세요: “urban-driving-q1 dataset의 annotation issue metrics를 가져와서 분석을 보여줘.” 단계 1 — 어시스턴트가 owner 및 dataset slug로 get_annotation_issue_metrics를 호출합니다. 단계 2 — 어시스턴트가 포맷된 요약을 제공합니다:

Urban Driving Q1 — Issue Metrics 상태별: 12 open, 5 in review, 3 relabeling, 45 completed 심각도별: 8 critical, 57 moderate 우선순위별: 2 highest, 6 high, 18 medium, 25 low, 14 lowest 평균 종료 시간: 4.2시간

단계 3 — 후속 요청: “open critical issues를 나열해줘.” 어시스턴트가 필터와 함께 list_annotation_issues_by_dataset를 호출하고 결과를 보여줍니다.

예시 프롬프트

MCP 호환 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"

AI 어시스턴트가 적절한 Avala MCP 도구를 호출하고, 응답을 처리하며, 결과를 읽기 쉬운 형식으로 제시합니다. 단일 대화에서 요청을 연결할 수 있습니다 — 예를 들어, datasets를 나열하고, 하나를 선택한 다음 export 상태를 확인할 수 있습니다.

문제 해결

`AVALA_API_KEY`가 설정되지 않음

AVALA_API_KEY environment variable이 없으면 MCP server가 error code 1과 함께 즉시 종료됩니다. MCP config의 env 블록에 key가 설정되어 있거나 server를 시작하기 전에 shell에서 export되어 있는지 확인하세요.

Error: AVALA_API_KEY environment variable is required

Mutation 도구가 표시되지 않음

create_export, create_agent 또는 fleet_register_device와 같은 도구가 도구 목록에 없는 경우, server 환경에서 AVALA_MCP_ENABLE_MUTATIONS=true를 설정해야 합니다. MCP configuration 파일의 env 블록에 추가하세요:

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

`npx`를 찾을 수 없거나 잘못된 Node.js 버전

MCP server는 Node.js 18 이상이 필요합니다. npx: command not found 또는 module syntax errors가 표시되면 Node.js 버전을 확인하세요:

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

오래된 캐시된 MCP server

최근에 @avala-ai/mcp-server package를 업데이트했지만 이전 동작이나 누락된 도구가 계속 표시되는 경우, npx가 캐시된 버전을 제공하고 있을 수 있습니다. 새로 설치를 강제하세요:

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

그런 다음 MCP client를 다시 시작하세요.

API key가 유효하지 않거나 만료됨

tool calls가 401 Unauthorized를 반환하면 API key가 유효하지 않거나, 만료되었거나, 해지되었을 수 있습니다. Mission Control의 Settings > Security에서 새 key를 생성하고 MCP configuration을 업데이트하세요.

Avala MCP server는 오픈 소스입니다. 소스 코드를 확인하거나 기여하려면 GitHub repository를 방문하세요.

​사전 요구사항

​설정

​Claude Desktop

​Cursor

​VS Code

​Claude Code

​ChatGPT

​MCP 보안 모드

​사용 가능한 MCP 도구

​Fleet (미리보기)

​도구 정의

​list_datasets

​get_dataset

​list_projects

​get_project

​create_dataset

​create_export

​get_export_status

​list_exports

​get_workspace_stats

​list_tasks

​get_task

​list_agents

​get_agent

​create_agent

​delete_agent

​list_webhooks

​create_webhook

​delete_webhook

​list_storage_configs

​create_storage_config

​test_storage_config

​delete_storage_config

​list_quality_targets

​evaluate_quality

​get_consensus_summary

​compute_consensus

​list_organizations

​get_organization

​list_slices

​get_slice

​list_annotation_issues_by_sequence

​create_annotation_issue

​update_annotation_issue

​delete_annotation_issue

​list_annotation_issues_by_dataset

​get_annotation_issue_metrics

​list_qc_tools

​fleet_list_devices

​fleet_get_device

​fleet_list_recordings

​fleet_get_recording

​fleet_list_events

​fleet_list_alerts

​fleet_list_rules

​fleet_register_device

​fleet_acknowledge_alert

​레시피

​레시피 1: Dataset 상태 점검

​레시피 2: Export 및 다운로드

​레시피 3: Projects 전반의 품질 감사

​레시피 4: Fleet device 모니터링

​레시피 5: Annotation issue 분류

​예시 프롬프트

​문제 해결

​AVALA_API_KEY가 설정되지 않음

​Mutation 도구가 표시되지 않음

​npx를 찾을 수 없거나 잘못된 Node.js 버전

​오래된 캐시된 MCP server

​API key가 유효하지 않거나 만료됨

사전 요구사항

설정

Claude Desktop

Cursor

VS Code

Claude Code

ChatGPT

MCP 보안 모드

사용 가능한 MCP 도구

Fleet (미리보기)

도구 정의

list_datasets

get_dataset

list_projects

get_project

create_dataset

create_export

get_export_status

list_exports

get_workspace_stats

list_tasks

get_task

list_agents

get_agent

create_agent

delete_agent

list_webhooks

create_webhook

delete_webhook

list_storage_configs

create_storage_config

test_storage_config

delete_storage_config

list_quality_targets

evaluate_quality

get_consensus_summary

compute_consensus

list_organizations

get_organization

list_slices

get_slice

list_annotation_issues_by_sequence

create_annotation_issue

update_annotation_issue

delete_annotation_issue

list_annotation_issues_by_dataset

get_annotation_issue_metrics

list_qc_tools

fleet_list_devices

fleet_get_device

fleet_list_recordings

fleet_get_recording

fleet_list_events

fleet_list_alerts

fleet_list_rules

fleet_register_device

fleet_acknowledge_alert

레시피

레시피 1: Dataset 상태 점검

레시피 2: Export 및 다운로드

레시피 3: Projects 전반의 품질 감사

레시피 4: Fleet device 모니터링

레시피 5: Annotation issue 분류

예시 프롬프트

문제 해결

`AVALA_API_KEY`가 설정되지 않음

Mutation 도구가 표시되지 않음

`npx`를 찾을 수 없거나 잘못된 Node.js 버전

오래된 캐시된 MCP server

API key가 유효하지 않거나 만료됨