Serveur MCP Audact — guide de configuration des clients

De quoi s’agit-il ? Le serveur MCP (Model Context Protocol) d’Audact expose un ensemble choisi d’opérations Audact sous forme d’outils pour les assistants IA — Claude, Cursor, Claude Desktop ou tout client compatible MCP — via une simple interface HTTP. Connectez-vous avec la clé API de votre tenant, puis examinez des appels, gérez des agents et des webhooks, construisez des automatisations de conformité et pilotez des opérations vocales.

Outils documentés : 161 pour l’ensemble des rôles. Chaque outil est confirmé séparément ; l’état mesuré du point de terminaison figure sur la page du serveur MCP.

Points de terminaison :

• Production : https://api.audact.ai/mcp/

1. Ce que c’est

Le serveur MCP est un point de terminaison HTTP sans état qui traduit des appels d’outils en opérations de l’API REST d’Audact. Il fonctionne en Streamable HTTP (le standard MCP pour le JSON-RPC du serveur vers le client et du client vers le serveur), n’exige que votre clé API pour l’authentification (jeton Bearer) et applique exactement les mêmes permissions et le même cloisonnement que l’API REST elle-même.

Pourquoi MCP ?

• Configuration en une ligne : aucune intégration écrite à la main, aucune passerelle sur mesure.
• Contexte en temps réel : votre assistant IA accède en direct aux agents, webhooks, numéros, appels et preuves.
• Respect des permissions : chaque appel d’outil est transmis avec votre clé — un assistant ne peut faire que ce que le rôle de votre clé autorise.
• Aucun secret conservé : le serveur MCP ne stocke aucun identifiant qui lui soit propre ; il transmet votre clé octet pour octet à l’API sous-jacente, de sorte qu’un appel d’outil ne peut pas faire plus que la même clé utilisée directement.

Transport et protocole

• Protocole : Model Context Protocol (MCP), version 2025-06-18 (rétrocompatible avec 2025-03-26).
• Transport : POST Streamable HTTP vers /mcp/ sur l’URL de base de votre environnement.
• Contenu : requêtes et réponses JSON-RPC 2.0.
• Authentification : Authorization: Bearer aud_live_… (la clé API de votre tenant, la même que pour REST).
• Sans état : ni session ni cookie. Chaque requête est indépendante ; n’importe quelle réplique peut la traiter.

Ce que signifie OAuth ici

OAuth n’est pas pris en charge. Les clients MCP qui exigent OAuth avec des serveurs distants ne peuvent pas se connecter. Les clients pris en charge (Claude Code, Cursor, Claude Desktop via mcp-remote, SDK MCP) transmettent tous les en-têtes directement :

• ✅ Claude Code, Cursor, Claude Desktop avec mcp-remote : fonctionne
• ✅ Clients SDK MCP avec --header ou une variable d’environnement : fonctionne
• ✅ Implémentations MCP personnalisées qui prennent en charge les jetons Bearer : fonctionne
• ❌ Clients qui ne prennent en charge que OAuth pour les serveurs distants : non pris en charge en v1

2. Connecter votre assistant IA

Claude Code

claude mcp add --transport http audact https://api.audact.ai/mcp/ \
  --header "Authorization: Bearer aud_live_…"

Remplacez aud_live_… par votre véritable clé API (voir Obtenir votre clé ci-dessous).

Pour vérifier : après l’ajout, redémarrez Claude Code et demandez-lui : « Listez mes agents. » S’il appelle list_agents sans erreur, la connexion est établie.

Claude Desktop

Utilisez mcp-remote pour exécuter le serveur MCP derrière la passerelle locale :

# In Claude Desktop's config file (~/.config/Claude/claude_desktop_config.json on Linux/Mac,
# or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "audact": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.audact.ai/mcp/"],
      "env": {
        "MCP_REMOTE_HEADER_Authorization": "Bearer aud_live_…"
      }
    }
  }
}

Redémarrez Claude Desktop. Les outils Audact devraient maintenant apparaître dans votre liste d’outils.

Cursor

Comme pour Claude Desktop : ajoutez ceci au fichier mcp_server_config.json de Cursor :

{
  "audact": {
    "command": "npx",
    "args": ["mcp-remote", "https://api.audact.ai/mcp/"],
    "env": {
      "MCP_REMOTE_HEADER_Authorization": "Bearer aud_live_…"
    }
  }
}

3. Obtenir votre clé

1. Connectez-vous au tableau de bord Audact à l’URL de votre environnement.
2. Allez dans API Keys (ou Settings → API Keys).
3. Copiez une clé dotée du rôle dont vous avez besoin (Viewer, Developer ou Owner ; voir Correspondance des rôles ci-dessous).
4. Utilisez-la dans la configuration ci-dessus.

Gardez votre clé secrète. Traitez-la comme un mot de passe. Si elle est exposée, révoquez-la immédiatement depuis le tableau de bord.

4. Ce que vous pouvez faire : outils par rôle

Le serveur MCP expose 161 outils au total, regroupés par niveau de permission et par domaine. Un outil n’apparaît parmi les outils disponibles de votre assistant que si votre clé possède le rôle requis. Même si vous listez un outil pour lequel vous n’avez pas la permission, le backend rejettera l’appel avec une erreur explicite.

Niveaux de rôle

• Viewer : accès en lecture seule. Consulter les appels, les preuves, les configurations, les webhooks et les numéros.
• Developer : lecture et écriture. Créer et mettre à jour des agents, des outils, des webhooks et des affectations. Pas de suppression ni de purge.
• Owner : accès complet, y compris la suppression et la modification des paramètres.

Catégories d’outils

Légende : L = lecture seule | D = destructif | C = confirmation requise (demandez d’abord à l’utilisateur, puis réessayez avec confirm: true)

Agents

Outils

Bases de connaissances

Voix

Intégrations

Configurations

Appels et preuves

Webhooks

Numéros de téléphone

Tenant, clés et session

Téléphonie BYO (Bring Your Own)

KYC (Know Your Customer)

Coffre PII

Appels (SIP) — gestion des appels en direct

Transferts et passations

Routage SIP

API d’exécution de la conformité

Proxy LLM

5. Confirmation pour les actions dangereuses

Certains outils exigent une confirmation explicite avant de s’exécuter. Ce sont des opérations qui dépensent de l’argent, qui sont irréversibles ou qui touchent à la sécurité :

Les 33 outils qui exigent une confirmation :

• Dépense d’argent : create_number, create_number_order, initiate_outbound_call
• Suppressions irréversibles : delete_kyc_document, delete_kyc_document_set, delete_call_recording, pii_shred_call, pii_shred_by_hash, pii_delete_exemption, pii_delete_exemption_by_path, revoke_key, release_number, delete_number, delete_byo_connection
• Contrôle des appels : initiate_inbound_call, create_browser_call, hangup_call, initiate_transfer, initiate_handover, bridge_transfer, cancel_transfer, end_transfer
• Configuration : create_dispatch_rule, create_inbound_trunk, create_outbound_trunk, set_admission_url, rotate_kyc_dek, pii_add_exemption, pii_put_settings
• Sécurité : generate_key, exchange_key, create_event, proxy_openai

Comment fonctionne la confirmation

Lorsqu’un outil exige une confirmation :

1. Le premier appel échoue avec CONFIRMATION_REQUIRED :

   json

   {
     "isError": true,
     "content": [
       {
         "type": "text",
         "text": "CONFIRMATION_REQUIRED: {consequence}. Ask the user explicitly, and then retry the same call with \"confirm\": true."
       }
     ]
   }

2. Le modèle interroge l’utilisateur : « Cela va {consequence}. Dois-je continuer ? »

3. Après l’accord de l’utilisateur, le modèle réessaie avec confirm: true :

   json

   {
     "name": "create_number_order",
     "arguments": {
       "body": {"set_id": "11111111-2222-3333-4444-555555555555", "country_code": "NL", "number_type": "local"},
       "confirm": true
     }
   }

Important : confirm est une protection contre l’injection de prompt, pas un système de permissions. Le rôle de votre clé API détermine toujours si vous pouvez appeler l’outil. Un confirm: true sans le rôle requis est tout de même rejeté par le backend avec une erreur 403.

6. Envoi de documents KYC

L’envoi de documents KYC (Know Your Customer) via MCP se fait en convertissant le fichier binaire en base64 dans du JSON.

Paramètres

• file_base64 (obligatoire) : le contenu du fichier encodé en base64 (le base64 standard et le base64 compatible URL sont tous deux acceptés ; encodage invalide → erreur d’outil INVALID_FILE_ENCODING)
• file_name (obligatoire) : nom de fichier d’origine (par ex. "passport.pdf")
• file_content_type (facultatif) : type MIME (par ex. "application/pdf"). À omettre s’il est inconnu.
• doc_type (obligatoire) : code de type de document accepté par le backend KYC (par ex. "passport" ou "proof_of_address")

Limites

• Taille maximale du fichier décodé : 10 MiB. Fichiers plus volumineux → erreur d’outil FILE_TOO_LARGE.
• Taille maximale de la requête : 15 MiB pour l’ensemble de la requête /mcp/, ce qui laisse la place à un fichier de 10 MiB en base64.
• Les outils sans fichier sont plafonnés à 1 MiB d’arguments (ARGUMENTS_TOO_LARGE), sauf validate_audio et reconcile_audio, qui peuvent aller jusqu’à la limite de requête de 15 MiB.

Exemple

{
  "doc_type": "passport",
  "file_base64": "JVBERi0xLjQKJeLjz9MNCjExIDAgb2JqCjw8L1R5cGUvRm9udERlc2NyaXB0b3IvRm9udE5hbWUvQSsvQmFzZUZvbnQvVGltZXMtQm9sZD4+CmVuZG9iCmZv...",
  "file_name": "my_passport.pdf",
  "file_content_type": "application/pdf"
}

Pour générer le base64 d’un fichier en ligne de commande :

base64 < my_passport.pdf

7. Données personnelles

pii_decrypt_call et pii_list_call_identities renvoient des données personnelles en clair (noms, e-mail, numéros de téléphone, etc.) directement dans la fenêtre de contexte de l’assistant IA.

Audact ne journalise ni les arguments ni les résultats des outils. Nous n’enregistrons donc pas nous-mêmes de données personnelles. En revanche, le fait qu’un assistant IA propre à un tenant puisse recevoir des données personnelles en clair relève de la responsabilité du tenant, au titre de son accord de traitement des données (DPA). Chaque client doit s’assurer que son accord sur les données l’autorise.

Si vous travaillez avec un responsable du traitement qui restreint les PII dans les contextes d’IA, utilisez directement l’API REST, avec des contrôles d’accès appropriés, plutôt que le serveur MCP.

Identifiants dans la conversation. generate_key renvoie le secret d’une nouvelle clé API et exchange_key renvoie un jeton de session. Les deux se retrouvent dans l’historique de conversation de l’assistant (et partout où votre client IA le stocke). Les deux exigent confirm: true ; révoquez avec revoke_key toute clé susceptible d’avoir été exposée.

Remarque sur delete_call_recording : l’API exige le rôle Owner, et MCP exige en plus confirm: true.

8. Limites

Limite de débit

• Point de terminaison /mcp/ : 600 requêtes par minute et par clé. Chaque appel d’outil et chaque tools/list est compté.
• Délai d’expiration : 30 secondes par appel.

Limites de taille des arguments

Remarque : les fichiers audio de plus d’environ 11 MiB nécessitent toujours l’API REST ; pour les très gros fichiers, utilisez directement POST /v1/validate-audio et POST /v1/audio-reconciliation.

Taille des réponses

• Plafond de 256 KiB : si le résultat d’une liste dépasse 256 KiB, des éléments entiers sont retirés à la fin pour que le résultat reste du JSON valide. Un champ _mcp_truncated indique combien d’éléments ont été renvoyés et combien tenaient dans la page. Réessayez avec un limit plus petit ou des filtres plus étroits.
• Réponses à un seul élément : si un seul élément dépasse 256 KiB (rare), vous obtenez à la place une erreur d’outil RESPONSE_TOO_LARGE.

Autres limites

• Encodage des fichiers : seul le base64 (standard ou compatible URL) est accepté pour file_base64. Encodage invalide → INVALID_FILE_ENCODING.
• Décodage base64 : la taille encodée doit tenir dans 10 MiB (décodée) ; au-delà → FILE_TOO_LARGE.

9. Proxy LLM

L’outil proxy_openai transmet une requête au proxy LLM d’Audact, qui gère l’authentification et le routage vers le fournisseur de LLM que vous avez configuré.

Paramètres

• call_id (obligatoire) : UUID du contexte d’appel (en-tête X-Audact-Call-ID)
• config_id (obligatoire) : UUID de la configuration LLM (en-tête X-Audact-Config-ID)
• turn (obligatoire) : numéro du tour dans la conversation (en-tête X-Audact-Turn)
• Autres champs : transmis tels quels comme corps de la requête au fournisseur de LLM (par ex. messages, temperature, etc.)

Remarques importantes

• Le tenant provient toujours de votre clé : vous ne pouvez pas en indiquer un autre ; il est renseigné automatiquement à partir de la clé API authentifiée.
• Confirmation requise : appelez proxy_openai avec "confirm": true, car l’appel LLM est payant.
• Pas de streaming via MCP : le streaming (text/event-stream) est réservé à REST. MCP ne gère que le JSON ; utilisez directement /v1/llm-proxy/openai pour les réponses en streaming.
• Latence : cet appel s’exécute sur le chemin critique (délai strict de 40 ms pour la validation de conformité) ; pour le proxy lui-même, attendez-vous à des réponses en moins d’une seconde.

Exemple

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "config_id": "660e8400-e29b-41d4-a716-446655440001",
  "turn": 1,
  "messages": [{"role": "user", "content": "Hello"}],
  "temperature": 0.7,
  "confirm": true
}

10. Ce qui N’est PAS exposé (et pourquoi)

Le serveur MCP exclut délibérément certaines opérations en v1 :

La liste de référence, avec une raison par entrée, est tenue dans la configuration des exclusions du serveur MCP.

Pour toutes ces opérations, utilisez directement l’API REST avec votre clé, ou le tableau de bord Audact.

11. Erreurs et limites de débit

Erreurs d’outil

Lorsqu’un appel d’outil MCP échoue, vous obtenez une erreur d’outil comportant :

• code : le code d’erreur de l’API Audact (par ex. CALL_NOT_FOUND, INVALID_API_KEY, CONFIRMATION_REQUIRED, ARGUMENTS_TOO_LARGE, FILE_TOO_LARGE, INVALID_FILE_ENCODING)
• hint : une suggestion lisible par un humain
• message : le texte complet de l’erreur

Exemple :

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "404 CALL_NOT_FOUND: Call not found\nHint: Provide a valid UUID for call_id"
    }
  ]
}

Authentification et limites de débit

• 401 de transport (HTTP 401) : clé API invalide ou révoquée. Vérifiez que votre clé est correcte et n’a pas été révoquée.
• Erreur d’outil 403 (du backend) : le rôle de votre clé est insuffisant pour cet outil. Passez à Developer ou Owner si nécessaire.
• HTTP 429 (limite de débit) : /mcp/ est limité à 600 requêtes par minute et par clé, en comptant chaque requête MCP. Lorsque la limite est atteinte, vous obtenez un HTTP 429 avec un en-tête Retry-After ; attendez ce nombre de secondes avant de réessayer.
• Plafond de taille des réponses (256 KiB) : si le résultat d’une liste dépasse 256 KiB, des éléments entiers sont retirés à la fin pour que le résultat reste du JSON valide, et un champ _mcp_truncated indique combien d’éléments ont été affichés. next_cursor est retiré d’une page tronquée. Un seul élément au-delà du plafond renvoie à la place une erreur d’outil RESPONSE_TOO_LARGE.

Délais d’expiration

• Chaque appel d’outil a un délai d’expiration de 30 secondes. Des retards réseau ou des opérations en amont lentes peuvent parfois le déclencher. Dans ce cas, réessayez après un court délai.

12. Transmission et architecture

Vos appels MCP sont transmis à la véritable API REST d’Audact (/v1) avec votre clé, exactement comme si vous l’aviez appelée directement. Cela signifie que :

• Permissions : le rôle de votre clé détermine ce que vous pouvez faire. Une clé Viewer ne voit que les outils de lecture ; une clé Developer ou Owner peut écrire.
• Cloisonnement des tenants : votre clé est liée à un seul tenant. Vous ne pouvez ni lire ni modifier les données d’un autre tenant, même si vous transmettez d’une manière ou d’une autre leurs ID.
• Piste d’audit : chaque appel est journalisé sous votre clé, comme un appel REST.
• Idempotence : gérée par les mêmes services backend que ceux qui traitent REST ; transmettez idempotency_key lorsqu’un outil le propose.

En bref : un appel d’outil MCP ne peut jamais faire plus que ce que la même clé pourrait faire directement sur /v1.

13. Exemples

Lister les agents

Outil : list_agents
Arguments : (aucun)
→ Renvoie la liste des agents de votre tenant

Créer un webhook

Outil : create_webhook
Arguments :
  - body:
      url: "https://example.com/hook"
      events: ["call_ended", "call_summary"]
      scope: "account"
→ Renvoie l’ID et la configuration du nouveau webhook

Confirmer la remise

Outil : confirm_delivery
Arguments :
  - body:
      call_id: "aaaabbbb-cccc-dddd-eeee-ffff00001111"
      delivered_text: "Your balance is low"
      mechanism: "voice"
→ Renvoie 200 OK ; événement de preuve enregistré

Envoyer un document KYC

Outil : upload_kyc_document
Arguments :
  - doc_type: "passport"
  - file_base64: "JVBERi0xLjQK..." (PDF encodé en base64)
  - file_name: "my_passport.pdf"
  - file_content_type: "application/pdf"
→ Renvoie l’ID du document et l’horodatage de l’envoi

14. Assistance et retours

• Référence de l’API REST : Référence de l’API Audact
• Spécification du protocole MCP : Model Context Protocol
• Dépannage :
  • Vérifiez que votre clé API est correcte et n’a pas été révoquée.
  • Vérifiez que vous utilisez https://api.audact.ai/mcp/ comme URL de point de terminaison.
  • Si tools/list renvoie une liste vide : le rôle de votre clé est peut-être insuffisant. Essayez une clé Developer.
  • Pour des erreurs d’outil précises : le code d’erreur et l’indication (hint) renvoient à la documentation de l’API REST.
• Signaler un problème : Assistance Audact

Référence rapide