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

> Model Context Protocol을 통해 Claude, Claude Code, Cursor, VS Code 및 ChatGPT에서 Avala를 사용하세요

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)은 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](https://avala.ai/settings?section=security)의 **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를 추가하세요:

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

```json theme={null}
{
  "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`을 생성하거나 편집하세요:

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

```json theme={null}
{
  "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`을 생성하거나 편집하세요:

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

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

MCP 지원이 활성화된 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 확장이 설치되어 있는지 확인하세요. 새 server를 인식하려면 VS Code를 다시 시작하세요.

### Claude Code

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

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

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

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

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

### ChatGPT

<Info>
  ChatGPT의 MCP 지원은 발전 중입니다. 최신 설정 안내 및 플랜과 지역에서의 사용 가능 여부는 [OpenAI 문서](https://platform.openai.com/docs)를 참조하세요.
</Info>

## MCP 보안 모드

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

```bash theme={null}
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을 생성합니다. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `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 (미리보기)

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

| 도구                        | 설명                                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `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를 등록합니다. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `fleet_acknowledge_alert` | fleet alert를 확인합니다. <span className="text-orange-500 text-xs font-medium">mutation</span>    |

## 도구 정의

각 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

**응답 예시:**

```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

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

**Parameters:**

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

**응답 예시:**

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

**오류 응답 (잘못된 UID):**

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

**응답 예시:**

```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

export의 상태를 확인합니다.

**Parameters:**

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

**응답 예시:**

```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

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

**Parameters:**

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

### get\_workspace\_stats

워크스페이스 내용(datasets, projects, exports)의 빠른 확인을 가져옵니다.

**Parameters:** 없음

**응답 예시:**

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

**응답 예시:**

```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

특정 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

**응답 예시:**

```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

특정 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

**응답 예시:**

```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

선택적 필터로 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`를 호출하여 개요를 가져옵니다.

```json theme={null}
{
  "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가 있습니다. 가장 큰 세 개는:
>
> 1. **Warehouse Cameras** -- 34,200 items (image)
> 2. **Urban Driving Q1** -- 12,450 items (lidar)
> 3. **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`를 호출합니다.

```json theme={null}
{
  "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`를 폴링합니다.

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

**단계 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` 블록에 추가하세요:

```json theme={null}
{
  "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 버전을 확인하세요:

```bash theme={null}
node --version  # Must be v18.0.0 or later
```

### 오래된 캐시된 MCP server

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

```bash theme={null}
npx --yes @avala-ai/mcp-server@latest
```

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

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

tool calls가 `401 Unauthorized`를 반환하면 API key가 유효하지 않거나, 만료되었거나, 해지되었을 수 있습니다. [Mission Control](https://avala.ai/settings?section=security)의 **Settings > Security**에서 새 key를 생성하고 MCP configuration을 업데이트하세요.

<Info>
  Avala MCP server는 오픈 소스입니다. 소스 코드를 확인하거나 기여하려면 [GitHub repository](https://github.com/avala-ai/avala-sdk-ts)를 방문하세요.
</Info>