> ## 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
> Utilisez Avala avec Claude, Claude Code, Cursor, VS Code et ChatGPT via le Model Context Protocol
Le [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) est un standard ouvert qui permet aux assistants IA d'interagir avec des outils et des sources de donnees externes. Le MCP server d'Avala expose vos datasets, projets et exports sous forme d'outils que tout client compatible MCP peut appeler, vous permettant ainsi de gerer votre flux d'annotation en langage naturel sans changer de contexte.
Cela signifie que vous pouvez demander a Claude de « lister tous mes datasets », faire creer un export par Cursor, ou utiliser VS Code pour verifier l'etat d'un projet — le tout reposant sur la meme API Avala que vous utilisez deja.
## Prerequis
* **Node.js** 18 ou version ulterieure installe sur votre machine
* Une **cle API Avala** (generez-en une dans [Mission Control](https://avala.ai/settings?section=security) sous **Settings > Security**)
## Installation
### Claude Desktop
Ouvrez votre fichier de configuration Claude Desktop :
* **macOS :** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows :** `%APPDATA%\Claude\claude_desktop_config.json`
Ajoutez le MCP server Avala :
Ne committez jamais de fichiers de configuration contenant de vraies cles API dans le controle de version. Definissez `AVALA_API_KEY` comme variable d'environnement systeme, ou remplacez `"your-api-key"` par votre cle reelle localement et assurez-vous que le fichier de configuration est dans votre `.gitignore`.
```json theme={null}
{
"mcpServers": {
"avala": {
"command": "npx",
"args": ["-y", "@avala-ai/mcp-server"],
"env": {
"AVALA_API_KEY": "your-api-key"
}
}
}
}
```
Redemarrez Claude Desktop. Vous devriez voir les outils Avala disponibles dans le selecteur d'outils.
### Cursor
Creez ou modifiez `.cursor/mcp.json` a la racine de votre projet (ou dans le repertoire de configuration globale) :
`.cursor/mcp.json` se trouve a la racine de votre projet et peut etre committe dans git. Ajoutez-le a votre `.gitignore` ou definissez `AVALA_API_KEY` comme variable d'environnement systeme au lieu de la placer directement dans le fichier de configuration.
```json theme={null}
{
"mcpServers": {
"avala": {
"command": "npx",
"args": ["-y", "@avala-ai/mcp-server"],
"env": {
"AVALA_API_KEY": "your-api-key"
}
}
}
}
```
Redemarrez Cursor ou rechargez la fenetre. Les outils Avala apparaitront dans le mode agent de Cursor.
### VS Code
Creez ou modifiez `.vscode/mcp.json` dans votre espace de travail :
`.vscode/mcp.json` se trouve dans votre espace de travail et peut etre committe dans git. Ajoutez-le a votre `.gitignore` ou definissez `AVALA_API_KEY` comme variable d'environnement systeme au lieu de la placer directement dans le fichier de configuration.
```json theme={null}
{
"mcpServers": {
"avala": {
"command": "npx",
"args": ["-y", "@avala-ai/mcp-server"],
"env": {
"AVALA_API_KEY": "your-api-key"
}
}
}
}
```
Assurez-vous que l'extension [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) est installee avec le support MCP active. Redemarrez VS Code pour prendre en compte le nouveau serveur.
### Claude Code
Ajoutez le MCP server Avala a Claude Code avec une seule commande :
```bash theme={null}
claude mcp add avala -- npx -y @avala-ai/mcp-server
```
Definissez votre cle API comme variable d'environnement :
```bash theme={null}
export AVALA_API_KEY="your-api-key"
```
Redemarrez Claude Code. Les outils Avala seront disponibles dans votre session.
### ChatGPT
Le support MCP de ChatGPT est en evolution. Consultez la
[documentation d'OpenAI](https://platform.openai.com/docs) pour les dernieres
instructions d'installation et la disponibilite dans votre plan et votre region.
## Mode de securite MCP
Pour des raisons de securite, le MCP server est en lecture seule par defaut. Les outils de mutation ne sont pas enregistres sauf si vous les activez explicitement avec :
```bash theme={null}
AVALA_MCP_ENABLE_MUTATIONS=true
```
Cette variable d'environnement peut etre definie dans l'environnement de processus de votre MCP server avant de le lancer.
Par defaut, les operations d'ecriture/suppression suivantes sont bloquees :
* `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`
## Outils MCP disponibles
Une fois connecte, les outils suivants sont disponibles pour l'assistant IA :
| Outil | Description |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `list_datasets` | Lister tous les datasets de votre espace de travail. |
| `get_dataset` | Obtenir les details d'un dataset specifique. |
| `create_dataset` | Creer un nouveau dataset pour l'annotation. mutation |
| `list_projects` | Lister tous les projets d'annotation. |
| `get_project` | Obtenir les details complets d'un projet. |
| `create_export` | Declencher un nouvel export pour un dataset ou un projet. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `get_export_status` | Verifier le statut d'un export. |
| `list_exports` | Lister tous les exports. |
| `get_workspace_stats` | Obtenir un resume de l'utilisation de l'espace de travail. |
| `list_tasks` | Lister les taches avec filtrage optionnel. |
| `get_task` | Obtenir les details d'une tache. |
| `list_agents` | Lister les agents d'automatisation. |
| `get_agent` | Obtenir les details d'un agent. |
| `create_agent` | Creer un nouvel agent d'automatisation. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `delete_agent` | Supprimer un agent. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `list_webhooks` | Lister les abonnements webhook. |
| `create_webhook` | Creer un abonnement webhook. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `delete_webhook` | Supprimer un webhook. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `list_storage_configs` | Lister les configurations de stockage. |
| `create_storage_config` | Creer une configuration de stockage. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `test_storage_config` | Tester la connectivite d'un stockage. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `delete_storage_config` | Supprimer une configuration de stockage. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `list_quality_targets` | Lister les objectifs de qualite d'un projet. |
| `evaluate_quality` | Evaluer les objectifs de qualite. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `get_consensus_summary` | Obtenir le resume de consensus d'un projet. |
| `compute_consensus` | Declencher le calcul de consensus. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `list_organizations` | Lister les organisations. |
| `get_organization` | Obtenir les details d'une organisation. |
| `list_slices` | Lister les slices d'un proprietaire. |
| `get_slice` | Obtenir les details d'un slice. |
| `list_annotation_issues_by_sequence` | Lister les problemes d'annotation d'une sequence. |
| `create_annotation_issue` | Creer un nouveau probleme d'annotation. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `update_annotation_issue` | Mettre a jour un probleme d'annotation. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `delete_annotation_issue` | Supprimer un probleme d'annotation. *(necessite `AVALA_MCP_ENABLE_MUTATIONS=true`)* |
| `list_annotation_issues_by_dataset` | Lister les problemes d'annotation d'un dataset. |
| `get_annotation_issue_metrics` | Obtenir les metriques de problemes d'un dataset. |
| `list_qc_tools` | Lister les outils QC disponibles. |
### Fleet (Apercu)
Les outils Fleet sont en apercu et peuvent evoluer. Ils fournissent un acces en lecture et en ecriture aux appareils, enregistrements, evenements, alertes et regles de la flotte.
| Outil | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `fleet_list_devices` | Lister les appareils de la flotte avec des filtres optionnels. |
| `fleet_get_device` | Obtenir les informations detaillees d'un appareil de la flotte. |
| `fleet_list_recordings` | Lister les enregistrements de la flotte avec des filtres optionnels. |
| `fleet_get_recording` | Obtenir les informations detaillees d'un enregistrement. |
| `fleet_list_events` | Lister les evenements de la flotte avec des filtres optionnels. |
| `fleet_list_alerts` | Lister les alertes de la flotte avec des filtres optionnels. |
| `fleet_list_rules` | Lister les regles de la flotte avec des filtres optionnels. |
| `fleet_register_device` | Enregistrer un nouvel appareil de flotte. mutation |
| `fleet_acknowledge_alert` | Acquitter une alerte de flotte. mutation |
## Definitions des outils
Schemas detailles pour chaque outil MCP. Tous les outils retournent du JSON sous forme de contenu texte.
### list\_datasets
Liste tous les datasets de l'espace de travail.
**Parameters:**
* `dataType` (string, optional) — Filtrer par type de donnees (`image`, `video`, `lidar`, `mcap`, `splat`)
* `name` (string, optional) — Filtrer par nom de dataset (correspondance partielle)
* `status` (string, optional) — Filtrer par statut du dataset
* `visibility` (string, optional) — Filtrer par visibilite (`private` ou `public`)
* `limit` (number, optional) — Nombre maximum de datasets a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
**Exemple de reponse :**
```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
Obtient les details d'un dataset specifique.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) du dataset
**Exemple de reponse :**
```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"
}
```
**Reponse d'erreur (UID invalide) :**
```json theme={null}
{
"error": "not_found",
"message": "Dataset with UID 'invalid-uid-here' was not found.",
"status": 404
}
```
### list\_projects
Liste tous les projets d'annotation.
**Parameters:**
* `limit` (number, optional) — Nombre maximum de projets a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### get\_project
Obtient les details d'un projet specifique.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) du projet
### create\_dataset
Cree un nouveau dataset pour l'annotation.
**Parameters:**
* `name` (string, required) — Nom d'affichage du dataset
* `slug` (string, required) — Identifiant compatible URL pour le dataset
* `dataType` (string, required) — Type de donnees : `image`, `video`, `lidar` ou `mcap`
* `visibility` (string, optional) — Visibilite du dataset : `private` ou `public` (par defaut : `private`)
* `createMetadata` (boolean, optional) — Si les metadonnees du dataset doivent etre creees (par defaut : true)
* `providerConfig` (object, optional) — Configuration du fournisseur de stockage cloud
* `ownerName` (string, optional) — Nom d'utilisateur ou email du proprietaire du dataset
### create\_export
Declenche un nouvel export pour un dataset ou un projet.
**Parameters:**
* `project` (string, optional) — UID du projet a exporter
* `dataset` (string, optional) — UID du dataset a exporter
**Exemple de reponse :**
```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
Verifie le statut d'un export.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) de l'export
**Exemple de reponse :**
```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
Liste tous les exports de l'espace de travail.
**Parameters:**
* `limit` (number, optional) — Nombre maximum d'exports a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### get\_workspace\_stats
Obtient un apercu rapide du contenu de l'espace de travail (datasets, projets, exports).
**Parameters:** Aucun
**Exemple de reponse :**
```json theme={null}
{
"datasets": 14,
"projects": 7,
"exports": 23,
"tasks": {
"total": 8420,
"pending": 312,
"completed": 7856,
"inProgress": 252
},
"members": 18
}
```
### list\_tasks
Liste les taches avec filtrage optionnel par projet ou statut.
**Parameters:**
* `project` (string, optional) — Filtrer par UID de projet
* `status` (string, optional) — Filtrer par statut de tache
* `limit` (number, optional) — Nombre maximum de taches a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
**Exemple de reponse :**
```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
Obtient les informations detaillees d'une tache specifique.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) de la tache
### list\_agents
Liste tous les agents d'automatisation configures dans votre espace de travail.
**Parameters:**
* `limit` (number, optional) — Nombre maximum d'agents a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### get\_agent
Obtient les informations detaillees d'un agent d'automatisation specifique.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) de l'agent
### create\_agent
Cree un nouvel agent d'automatisation avec des abonnements aux evenements et une URL de rappel.
**Parameters:**
* `name` (string, required) — Nom de l'agent
* `events` (string\[], required) — Liste des types d'evenements auxquels l'agent s'abonne
* `callbackUrl` (string, optional) — URL pour recevoir les rappels d'evenements
* `description` (string, optional) — Description de l'agent
* `project` (string, optional) — UID du projet pour limiter la portee de l'agent
* `taskTypes` (string\[], optional) — Types de taches geres par l'agent
### delete\_agent
Supprime un agent d'automatisation par son UID.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) de l'agent a supprimer
### list\_webhooks
Liste tous les abonnements webhook de votre espace de travail.
**Parameters:**
* `limit` (number, optional) — Nombre maximum de webhooks a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### create\_webhook
Cree un nouvel abonnement webhook pour des evenements specifiques.
**Parameters:**
* `targetUrl` (string, required) — URL pour recevoir les livraisons de webhook
* `events` (string\[], required) — Liste des types d'evenements auxquels s'abonner
### delete\_webhook
Supprime un abonnement webhook par son UID.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) du webhook a supprimer
### list\_storage\_configs
Liste toutes les configurations de stockage de votre espace de travail.
**Parameters:**
* `limit` (number, optional) — Nombre maximum de configurations de stockage a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### create\_storage\_config
Cree une nouvelle configuration de stockage (S3 ou Google Cloud Storage).
**Parameters:**
* `name` (string, required) — Nom de la configuration de stockage
* `provider` (string, required) — Type de fournisseur de stockage (`s3` ou `gcs`)
* `s3BucketName` (string, optional) — Nom du bucket S3
* `s3BucketRegion` (string, optional) — Region du bucket S3
* `s3BucketPrefix` (string, optional) — Prefixe de cle S3
* `s3AccessKeyId` (string, optional) — ID de cle d'acces S3 (stocke de maniere securisee cote serveur)
* `s3SecretAccessKey` (string, optional) — Cle d'acces secrete S3 (stockee de maniere securisee cote serveur)
* `s3IsAccelerated` (boolean, optional) — Activer S3 Transfer Acceleration
* `gcStorageBucketName` (string, optional) — Nom du bucket Google Cloud Storage
* `gcStoragePrefix` (string, optional) — Prefixe Google Cloud Storage
* `gcStorageAuthJsonContent` (string, optional) — Identifiants JSON du compte de service GCS (stockes de maniere securisee cote serveur)
### test\_storage\_config
Teste la connectivite d'une configuration de stockage.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) de la configuration de stockage a tester
### delete\_storage\_config
Supprime une configuration de stockage par son UID.
**Parameters:**
* `uid` (string, required) — L'identifiant unique (UUID) de la configuration de stockage a supprimer
### list\_quality\_targets
Liste les objectifs de qualite configures pour un projet specifique.
**Parameters:**
* `projectUid` (string, required) — L'identifiant unique (UUID) du projet
* `limit` (number, optional) — Nombre maximum d'objectifs de qualite a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### evaluate\_quality
Evalue tous les objectifs de qualite d'un projet et retourne leur statut actuel.
**Parameters:**
* `projectUid` (string, required) — L'identifiant unique (UUID) du projet a evaluer
### get\_consensus\_summary
Obtient un resume de consensus pour un projet incluant les scores moyens/medians et la distribution.
**Parameters:**
* `projectUid` (string, required) — L'identifiant unique (UUID) du projet
### compute\_consensus
Declenche le calcul de consensus pour un projet.
**Parameters:**
* `projectUid` (string, required) — L'identifiant unique (UUID) du projet
### list\_organizations
Liste toutes les organisations dont vous etes membre.
**Parameters:**
* `limit` (number, optional) — Nombre maximum d'organisations a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### get\_organization
Obtient les informations detaillees d'une organisation specifique.
**Parameters:**
* `slug` (string, required) — L'identifiant slug de l'organisation
### list\_slices
Liste les slices d'un proprietaire (utilisateur ou organisation).
**Parameters:**
* `owner` (string, required) — Nom du proprietaire (slug d'utilisateur ou d'organisation)
* `limit` (number, optional) — Nombre maximum de slices a retourner
* `cursor` (string, optional) — Curseur de pagination d'une requete precedente
### get\_slice
Obtient les informations detaillees d'un slice specifique.
**Parameters:**
* `owner` (string, required) — Nom du proprietaire (slug d'utilisateur ou d'organisation)
* `slug` (string, required) — Le slug du slice
### list\_annotation\_issues\_by\_sequence
Liste tous les problemes d'annotation d'une sequence specifique.
**Parameters:**
* `sequenceUid` (string, required) — L'UUID de la sequence
* `datasetItemUid` (string, optional) — Filtrer par UUID de l'element de dataset
* `projectUid` (string, optional) — Filtrer par UUID du projet
### create\_annotation\_issue
Cree un nouveau probleme d'annotation sur une sequence.
**Parameters:**
* `sequenceUid` (string, required) — L'UUID de la sequence
* `toolUid` (string, required) — UUID de l'outil d'annotation
* `problemUid` (string, required) — UUID du type de probleme
* `datasetItemUid` (string, optional) — UUID de l'element de dataset
* `projectUid` (string, optional) — UUID du projet
* `priority` (string, optional) — Niveau de priorite : `lowest`, `low`, `medium`, `high`, `highest`
* `severity` (string, optional) — Niveau de severite : `critical`, `moderate`
* `description` (string, optional) — Description du probleme
* `wrongClass` (string, optional) — Etiquette de classe incorrecte
* `correctClass` (string, optional) — Etiquette de classe correcte
* `objectUid` (string, optional) — UUID de l'objet d'annotation
* `shouldReAnnotate` (boolean, optional) — Si une re-annotation est necessaire
* `shouldDelete` (boolean, optional) — Si l'annotation doit etre supprimee
* `framesAffected` (string, optional) — Images affectees par le probleme
### update\_annotation\_issue
Met a jour un probleme d'annotation existant (statut, priorite, etc.).
**Parameters:**
* `sequenceUid` (string, required) — L'UUID de la sequence
* `issueUid` (string, required) — L'UUID du probleme d'annotation
* `status` (string, optional) — Statut : `open`, `relabeling`, `in_review`, `completed`, `cant_reproduce`, `awaiting_feedback`, `no_action_taken`
* `priority` (string, optional) — Niveau de priorite : `lowest`, `low`, `medium`, `high`, `highest`
* `severity` (string, optional) — Niveau de severite : `critical`, `moderate`
* `description` (string, optional) — Description mise a jour
* `toolUid` (string, optional) — UUID de l'outil d'annotation
* `problemUid` (string, optional) — UUID du type de probleme
* `wrongClass` (string, optional) — Etiquette de classe incorrecte
* `framesAffected` (string, optional) — Images affectees par le probleme
### delete\_annotation\_issue
Supprime un probleme d'annotation.
**Parameters:**
* `sequenceUid` (string, required) — L'UUID de la sequence
* `issueUid` (string, required) — L'UUID du probleme d'annotation a supprimer
### list\_annotation\_issues\_by\_dataset
Liste tous les problemes d'annotation d'un dataset.
**Parameters:**
* `owner` (string, required) — Nom d'utilisateur du proprietaire du dataset
* `datasetSlug` (string, required) — Slug du dataset
* `sequenceUid` (string, optional) — Filtrer par UUID de sequence
### get\_annotation\_issue\_metrics
Obtient les metriques agregees des problemes d'annotation d'un dataset (nombre par statut/priorite/severite, temps de cloture).
**Parameters:**
* `owner` (string, required) — Nom d'utilisateur du proprietaire du dataset
* `datasetSlug` (string, required) — Slug du dataset
* `sequenceUid` (string, optional) — Filtrer par UUID de sequence
### list\_qc\_tools
Liste les outils QC d'annotation disponibles pour un type de dataset donne.
**Parameters:**
* `datasetType` (string, required) — Le type de dataset (ex. `lidar`, `image`, `video`)
### fleet\_list\_devices
Liste les appareils de la flotte avec des filtres optionnels.
**Parameters:**
* `status` (string, optional) — Filtrer par statut de l'appareil (`online`, `offline`, `maintenance`)
* `type` (string, optional) — Filtrer par type d'appareil
* `limit` (number, optional) — Nombre maximum d'appareils a retourner
* `cursor` (string, optional) — Curseur de pagination
**Exemple de reponse :**
```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
Obtient les informations detaillees d'un appareil de flotte specifique.
**Parameters:**
* `uid` (string, required) — L'identifiant unique de l'appareil
### fleet\_list\_recordings
Liste les enregistrements de la flotte avec des filtres optionnels.
**Parameters:**
* `device` (string, optional) — Filtrer par UID d'appareil
* `status` (string, optional) — Filtrer par statut d'enregistrement
* `limit` (number, optional) — Nombre maximum d'enregistrements a retourner
* `cursor` (string, optional) — Curseur de pagination
### fleet\_get\_recording
Obtient les informations detaillees d'un enregistrement specifique.
**Parameters:**
* `uid` (string, required) — L'identifiant unique de l'enregistrement
### fleet\_list\_events
Liste les evenements de la flotte avec des filtres optionnels.
**Parameters:**
* `recording` (string, optional) — Filtrer par UID d'enregistrement
* `device` (string, optional) — Filtrer par UID d'appareil
* `type` (string, optional) — Filtrer par type d'evenement
* `severity` (string, optional) — Filtrer par severite
* `limit` (number, optional) — Nombre maximum d'evenements a retourner
* `cursor` (string, optional) — Curseur de pagination
### fleet\_list\_alerts
Liste les alertes de la flotte avec des filtres optionnels.
**Parameters:**
* `status` (string, optional) — Filtrer par statut d'alerte (`open`, `acknowledged`, `resolved`)
* `severity` (string, optional) — Filtrer par severite (`info`, `warning`, `error`, `critical`)
* `device` (string, optional) — Filtrer par UID d'appareil
* `rule` (string, optional) — Filtrer par UID de regle
* `limit` (number, optional) — Nombre maximum d'alertes a retourner
* `cursor` (string, optional) — Curseur de pagination
**Exemple de reponse :**
```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
Liste les regles de la flotte avec des filtres optionnels.
**Parameters:**
* `enabled` (boolean, optional) — Filtrer par statut d'activation
* `limit` (number, optional) — Nombre maximum de regles a retourner
* `cursor` (string, optional) — Curseur de pagination
### fleet\_register\_device
Enregistre un nouvel appareil de flotte.
**Parameters:**
* `name` (string, required) — Nom de l'appareil
* `type` (string, required) — Type de l'appareil
* `firmwareVersion` (string, optional) — Version du firmware
* `tags` (string\[], optional) — Etiquettes pour l'appareil
### fleet\_acknowledge\_alert
Acquitte une alerte de flotte.
**Parameters:**
* `uid` (string, required) — L'identifiant unique de l'alerte a acquitter
## Recettes
Flux de travail en plusieurs etapes que vous pouvez executer en langage naturel. Chaque recette montre les appels d'outils que l'assistant effectue en arriere-plan.
### Recette 1 : Bilan de sante des datasets
Demandez a votre assistant : *« Faites-moi un bilan de sante de mon espace de travail — combien de datasets ai-je, et lesquels ont le plus d'elements ? »*
**Etape 1** — L'assistant appelle `get_workspace_stats` pour obtenir la vue d'ensemble.
```json theme={null}
{
"datasets": 14,
"projects": 7,
"exports": 23,
"tasks": { "total": 8420, "pending": 312, "completed": 7856, "inProgress": 252 },
"members": 18
}
```
**Etape 2** — L'assistant appelle `list_datasets` avec `limit: 50` pour recuperer tous les datasets.
**Etape 3** — L'assistant trie les resultats par `itemCount` et presente un resume classe :
> Vous avez 14 datasets. Les trois plus volumineux sont :
>
> 1. **Warehouse Cameras** — 34 200 elements (image)
> 2. **Urban Driving Q1** — 12 450 elements (lidar)
> 3. **Parking Lot Footage** — 8 900 elements (video)
### Recette 2 : Export et telechargement
Demandez a votre assistant : *« Exportez le projet Urban Driving Q1 et prevenez-moi quand c'est pret. »*
**Etape 1** — L'assistant appelle `list_projects` pour trouver l'UID du projet correspondant a « Urban Driving Q1 ».
**Etape 2** — L'assistant appelle `create_export` avec l'UID du projet.
```json theme={null}
{
"uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
"status": "pending",
"project": "770a9600-a40d-63f6-c938-668877660000",
"createdAt": "2026-03-19T10:00:00Z"
}
```
**Etape 3** — L'assistant interroge `get_export_status` jusqu'a ce que le statut passe a `completed`.
```json theme={null}
{
"uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
"status": "completed",
"downloadUrl": "https://api.avala.ai/exports/e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9/download",
"fileSize": 52428800,
"completedAt": "2026-03-19T10:02:34Z"
}
```
**Etape 4** — L'assistant fournit le lien de telechargement et la taille du fichier.
> Votre export est pret (50 Mo). Telechargez-le ici : `https://api.avala.ai/exports/.../download`
### Recette 3 : Audit qualite de tous les projets
Demandez a votre assistant : *« Evaluez les objectifs de qualite de tous mes projets et signalez ceux qui echouent. »*
**Etape 1** — L'assistant appelle `list_projects` pour recuperer tous les projets.
**Etape 2** — Pour chaque projet, l'assistant appelle `evaluate_quality` avec l'UID du projet.
**Etape 3** — L'assistant agrege les resultats et met en evidence les echecs :
> 5 projets sur 7 atteignent tous les objectifs de qualite. Deux necessitent votre attention :
>
> * **Sidewalk Segmentation** — Objectif « Label accuracy » a 88 % (seuil : 95 %)
> * **Fleet Camera Review** — Objectif « Consensus score » a 0,72 (seuil : 0,85)
### Recette 4 : Surveillance des appareils de la flotte
Demandez a votre assistant : *« Montrez-moi toutes les alertes de flotte non acquittees, regroupees par severite. »*
**Etape 1** — L'assistant appelle `fleet_list_alerts` avec `status: "open"`.
**Etape 2** — L'assistant regroupe et formate la reponse :
> **Critique (1)**
>
> * Dock Camera 3 — « Appareil hors ligne depuis plus de 24 heures » (depuis le 18 mars)
>
> **Avertissement (2)**
>
> * Forklift Sensor Unit 12 — « Temperature de l'appareil depassant le seuil (72C) » (depuis le 19 mars)
> * Rooftop LiDAR 1 — « Espace disque faible (\< 5 %) » (depuis le 19 mars)
**Etape 3** — Vous pouvez poursuivre : *« Acquittez toutes les alertes de niveau avertissement. »* L'assistant appelle `fleet_acknowledge_alert` pour chaque UID d'alerte de type avertissement.
### Recette 5 : Triage des problemes d'annotation
Demandez a votre assistant : *« Obtenez les metriques des problemes d'annotation du dataset urban-driving-q1 et montrez-moi la repartition. »*
**Etape 1** — L'assistant appelle `get_annotation_issue_metrics` avec le proprietaire et le slug du dataset.
**Etape 2** — L'assistant presente un resume formate :
> **Urban Driving Q1 — Metriques des problemes**
>
> Par statut : 12 ouverts, 5 en revue, 3 en re-etiquetage, 45 termines
> Par severite : 8 critiques, 57 moderes
> Par priorite : 2 les plus hauts, 6 hauts, 18 moyens, 25 bas, 14 les plus bas
> Temps moyen de cloture : 4,2 heures
**Etape 3** — Vous poursuivez : *« Listez les problemes critiques ouverts. »* L'assistant appelle `list_annotation_issues_by_dataset` avec des filtres et affiche les resultats.
## Exemples de prompts
Voici quelques prompts en langage naturel que vous pouvez utiliser avec tout client compatible MCP :
```
Lister tous mes datasets
```
```
Montre-moi les details du dataset "autonomous-driving-v3"
```
```
Quel est le statut du projet "Lidar QA" ?
```
```
Creer un export pour le projet 770a9600-a40d-63f6-c938-668877660000
```
```
Combien d'exports ai-je ?
```
```
Afficher les statistiques de mon espace de travail
```
```
Lister tous mes agents d'automatisation
```
```
Creer un webhook pour les evenements task.completed pointant vers https://my-server.com/hooks
```
```
Montre-moi les objectifs de qualite du projet proj_abc123
```
```
Quel est le resume du score de consensus de mon projet d'annotation ?
```
```
Lister toutes les organisations auxquelles j'appartiens
```
```
Afficher la liste des configurations de stockage de l'espace de travail
```
```
Lister tous les appareils de flotte en ligne
```
```
Montre-moi les alertes critiques ouvertes de la flotte
```
```
Enregistrer un nouvel appareil lidar-sensor appele "Rooftop Unit 5"
```
L'assistant IA appellera l'outil MCP Avala approprie, traitera la reponse et presentera les resultats dans un format lisible. Vous pouvez enchainer les requetes dans une meme conversation — par exemple, lister les datasets, en choisir un, puis consulter le statut d'un export.
## Depannage
### `AVALA_API_KEY` non definie
Le MCP server s'arrete immediatement avec le code d'erreur 1 si la variable d'environnement `AVALA_API_KEY` est manquante. Assurez-vous que la cle est definie dans le bloc `env` de votre configuration MCP ou exportee dans votre shell avant de lancer le serveur.
```
Error: AVALA_API_KEY environment variable is required
```
### Les outils de mutation n'apparaissent pas
Si des outils comme `create_export`, `create_agent` ou `fleet_register_device` sont absents de la liste des outils, vous devez definir `AVALA_MCP_ENABLE_MUTATIONS=true` dans l'environnement du serveur. Ajoutez-le au bloc `env` de votre fichier de configuration MCP :
```json theme={null}
{
"env": {
"AVALA_API_KEY": "your-api-key",
"AVALA_MCP_ENABLE_MUTATIONS": "true"
}
}
```
### `npx` introuvable ou mauvaise version de Node.js
Le MCP server necessite Node.js 18 ou une version ulterieure. Si vous voyez `npx: command not found` ou des erreurs de syntaxe de module, verifiez votre version de Node.js :
```bash theme={null}
node --version # Must be v18.0.0 or later
```
### MCP server en cache obsolete
Si vous avez recemment mis a jour le package `@avala-ai/mcp-server` mais constatez toujours un ancien comportement ou des outils manquants, npx utilise peut-etre une version en cache. Forcez une nouvelle installation :
```bash theme={null}
npx --yes @avala-ai/mcp-server@latest
```
Puis redemarrez votre client MCP.
### Cle API invalide ou expiree
Si les appels d'outils retournent `401 Unauthorized`, votre cle API est peut-etre invalide, expiree ou revoquee. Generez une nouvelle cle dans [Mission Control](https://avala.ai/settings?section=security) sous **Settings > Security** et mettez a jour votre configuration MCP.
Le MCP server Avala est open source. Visitez le [depot GitHub](https://github.com/avala-ai/avala-sdk-ts) pour consulter le code source ou contribuer.