Audact MCP-server — Installatiehandleiding voor clients

Wat is het? De Audact-MCP-server (Model Context Protocol) stelt een zorgvuldig samengestelde reeks Audact-operaties beschikbaar als tools voor AI-assistenten — Claude, Cursor, Claude Desktop of elke MCP-compatibele client — via een eenvoudige HTTP-interface. Maak verbinding met uw tenant-API-sleutel en bekijk gesprekken, beheer agenten en webhooks, bouw compliance-automatiseringen en beheer spraakoperaties.

Beschikbare tools: 161 verspreid over alle rollen

Eindpunten:

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

1. Wat het is

De MCP-server is een staatloze HTTP-eindpunt die tool-aanroepen vertaalt naar Audact REST API-operaties. Hij draait via Streamable HTTP (de MCP-standaard voor server-naar-client- en client-naar-server-JSON-RPC), vereist alleen uw API-sleutel voor authenticatie (Bearer-token) en handhaaft exact dezelfde machtigingen en isolatie als de REST API zelf.

Waarom MCP?

• Instellen in één regel: Geen handgeschreven integraties of aangepaste bruggen.
• Realtime context: Uw AI-assistent heeft live toegang tot agenten, webhooks, nummers, gesprekken en bewijzen.
• Veilige machtigingen: Elke tool-aanroep wordt doorgestuurd met uw sleutel — een assistent kan alleen doen wat uw sleutelrol toestaat.
• Geen opgeslagen geheimen: De MCP-server bewaart geen aanmeldgegevens en creëert geen nieuw aanvalsoppervlak; hij stuurt uw sleutel byte voor byte door naar de onderliggende API.

Transport en protocol

• Protocol: Model Context Protocol (MCP), versie 2025-06-18 (achterwaarts compatibel met 2025-03-26).
• Transport: Streamable HTTP POST naar /mcp/ op de basis-URL van uw omgeving.
• Inhoud: JSON-RPC 2.0-verzoeken en -antwoorden.
• Authenticatie: Authorization: Bearer aud_live_… (uw tenant-API-sleutel, dezelfde als voor REST).
• Staatlos: Geen sessies, geen cookies. Elk verzoek is onafhankelijk; elke replica kan het bedienen.

Wat OAuth hier betekent

OAuth wordt niet ondersteund. MCP-clients die voor externe servers verplicht OAuth vereisen, kunnen geen verbinding maken. Ondersteunde clients (Claude Code, Cursor, Claude Desktop via mcp-remote, MCP SDK's) geven headers rechtstreeks door:

• ✅ Claude Code, Cursor, Claude Desktop met mcp-remote: werkt
• ✅ MCP SDK-clients met --header of omgevingsvariabele: werkt
• ✅ Aangepaste MCP-implementaties die Bearer-tokens ondersteunen: werkt
• ❌ Clients die voor externe servers uitsluitend OAuth ondersteunen: niet ondersteund in v1

2. Uw AI-assistent verbinden

Claude Code

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

Vervang aud_live_… door uw werkelijke API-sleutel (zie Uw sleutel ophalen hieronder).

Ter verificatie: Start Claude Code opnieuw op na het toevoegen en vraag: "Geef een lijst van mijn agenten." Als daarbij list_agents zonder fout wordt aangeroepen, is de verbinding tot stand gebracht.

Claude Desktop

Gebruik mcp-remote om de MCP-server achter de lokale gateway te laten draaien:

# In het configuratiebestand van Claude Desktop (~/.config/Claude/claude_desktop_config.json op Linux/Mac,
# of %APPDATA%\Claude\claude_desktop_config.json op Windows):

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

Start Claude Desktop opnieuw op. De Audact-tools zouden nu in uw toollijst moeten verschijnen.

Cursor

Hetzelfde als Claude Desktop: voeg toe aan de mcp_server_config.json van Cursor:

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

3. Uw sleutel ophalen

1. Log in op het Audact-dashboard via uw omgevings-URL.
2. Ga naar API-sleutels (of Instellingen → API-sleutels).
3. Kopieer een sleutel met de benodigde rol (Viewer, Developer of Owner; zie Rolkoppeling hieronder).
4. Gebruik hem in de bovenstaande configuratie.

Houd uw sleutel geheim. Behandel hem als een wachtwoord. Als hij is blootgesteld, trek hem dan onmiddellijk in via het dashboard.

4. Wat u kunt doen: tools per rol

De MCP-server stelt in totaal 161 tools beschikbaar, gegroepeerd per machtigingsniveau en domein. Een tool verschijnt in de beschikbare tools van uw assistent alleen als uw sleutel de vereiste rol heeft. Zelfs als u een tool opvraagt waarvoor u geen machtiging hebt, wijst de backend de aanroep af met een duidelijke foutmelding.

Rolniveaus

• Viewer: Alleen-lezen toegang. Bekijk gesprekken, bewijzen, configuraties, webhooks en nummers.
• Developer: Lees- en schrijftoegang. Maak/update agenten, tools, webhooks en toewijzingen. Geen verwijderen/wissen.
• Owner: Volledige toegang, inclusief verwijderen en instellingswijzigingen.

Toolcategorieën

Legenda: R = alleen-lezen | D = vernietigend | C = bevestiging vereist (vraag de gebruiker eerst, probeer daarna opnieuw met confirm: true)

Agenten

Tools

Kennisbanken

Stemmen

Integraties

Configuraties

Gesprekken en bewijzen

Webhooks

Telefoonnummers

Tenant, sleutels en sessie

BYO-telefonie (Bring Your Own)

KYC (Know Your Customer)

PII-kluis

Gesprekken (SIP) — Beheer van live gesprekken

Doorverbindingen en overdrachten

SIP-routering

Compliance Runtime API

LLM-proxy

5. Bevestiging voor gevaarlijke acties

Sommige tools vereisen expliciete bevestiging voordat ze worden uitgevoerd. Dit zijn operaties die geld kosten, onomkeerbaar zijn of invloed hebben op de beveiliging:

De 33 tools die bevestiging vereisen:

• Gelduitgevend: create_number, create_number_order, initiate_outbound_call
• Onomkeerbare verwijderingen: 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
• Gespreksbesturing: initiate_inbound_call, create_browser_call, hangup_call, initiate_transfer, initiate_handover, bridge_transfer, cancel_transfer, end_transfer
• Configuratie: create_dispatch_rule, create_inbound_trunk, create_outbound_trunk, set_admission_url, rotate_kyc_dek, pii_add_exemption, pii_put_settings
• Beveiliging: generate_key, exchange_key, create_event, proxy_openai

Hoe bevestiging werkt

Wanneer een tool bevestiging vereist:

1. Eerste aanroep mislukt met 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. Het model vraagt de gebruiker: "Dit zal {consequence}. Wilt u doorgaan?"

3. Na goedkeuring door de gebruiker herhaalt het model de aanroep met confirm: true:

   json

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

Belangrijk: confirm is een beveiliging tegen prompt-injectie, geen machtigingssysteem. De rol van uw API-sleutel bepaalt nog steeds of u de tool kunt aanroepen. Een confirm: true zonder de vereiste rol wordt nog steeds afgewezen met een 403-fout van de backend.

6. KYC-documenten uploaden

Het uploaden van KYC-documenten (Know Your Customer) verloopt via de MCP-server door het binaire bestand te coderen als base64 in JSON.

Parameters

• file_base64 (vereist): De bestandsinhoud gecodeerd in base64 (standaard of URL-veilige base64 worden beide geaccepteerd; ongeldige codering → toolfout INVALID_FILE_ENCODING)
• file_name (vereist): Oorspronkelijke bestandsnaam (bijv. "passport.pdf")
• file_content_type (optioneel): MIME-type (bijv. "application/pdf"). Weglaten indien onbekend.
• doc_type (vereist): Documenttypecode die door de KYC-backend wordt geaccepteerd (bijv. "passport" of "proof_of_address")

Limieten

• Maximale decoderingsgrootte: 10 MiB. Grotere bestanden → toolfout FILE_TOO_LARGE.
• Maximale verzoekgrootte: 15 MiB voor het volledige /mcp/-verzoek, waardoor er ruimte is voor een bestand van 10 MiB als base64.
• Tools zonder een bestand zijn beperkt tot 1 MiB aan argumenten (ARGUMENTS_TOO_LARGE), behalve validate_audio en reconcile_audio, die tot de limiet van 15 MiB voor verzoeken kunnen gebruiken.

Voorbeeld

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

Om base64 te genereren uit uw bestand via de opdrachtregel:

base64 < my_passport.pdf

7. Persoonsgegevens

pii_decrypt_call en pii_list_call_identities geven persoonsgegevens in platte tekst (namen, e-mailadressen, telefoonnummers, enz.) rechtstreeks in het contextvenster van de AI-assistent terug.

Audact logt geen tool-argumenten of -resultaten, dus wij loggen zelf geen PII. Of de eigen AI-assistent van een tenant echter persoonsgegevens in platte tekst mag ontvangen, is de verantwoordelijkheid van de tenant op grond van diens Gegevensverwerkingsovereenkomst. Elke klant moet ervoor zorgen dat diens gegevensovereenkomst dit toestaat.

Als u werkt met een verwerkingsverantwoordelijke die PII in AI-contexten beperkt, gebruikt u de REST API rechtstreeks met de juiste toegangscontroles in plaats van de MCP-server.

Aanmeldgegevens in het gesprek. generate_key geeft een nieuw API-sleutelgeheim terug en exchange_key geeft een sessietoken terug. Beide komen in de gespreksgeschiedenis van de assistent (en overal waar uw AI-client die opslaat). Beide vereisen confirm: true; trek een sleutel die mogelijk blootgesteld is in met revoke_key.

Opmerking over delete_call_recording: de API vereist de Owner-rol, en de MCP-server vereist bovendien confirm: true.

8. Limieten

Snelheidslimiet

• Eindpunt /mcp/: 600 verzoeken/minuut per sleutel. Telt elke tool-aanroep, elke tools/list.
• Time-out: 30 seconden per aanroep.

Argumentgrootte-limieten

Opmerking: Audio groter dan ca. 11 MiB vereist nog steeds de REST API; gebruik POST /v1/validate-audio en POST /v1/audio-reconciliation rechtstreeks voor zeer grote bestanden.

Antwoordgrootte

• Limiet van 256 KiB: Als een lijstresultaat 256 KiB overschrijdt, worden volledige items vanaf het einde afgekapt zodat het resultaat geldige JSON blijft. Een veld _mcp_truncated geeft aan hoeveel er zijn teruggegeven en hoeveel er op de pagina passen. Probeer opnieuw met een kleinere limit of engere filters.
• Antwoorden voor één item: Als één item 256 KiB overschrijdt (zeldzaam), krijgt u in plaats daarvan een toolfout RESPONSE_TOO_LARGE.

Overige limieten

• Bestandscodering: Alleen base64 (standaard of URL-veilig) wordt geaccepteerd voor file_base64. Ongeldige codering → INVALID_FILE_ENCODING.
• Base64-decodering: De gecodeerde grootte moet passen binnen 10 MiB (gedecodeerd); te groot → FILE_TOO_LARGE.

9. LLM-proxy

De tool proxy_openai stuurt een verzoek door naar de Audact LLM-proxy, die authenticatie en routering naar uw geconfigureerde LLM-provider beheert.

Parameters

• call_id (vereist): UUID van de gesprekscontext (X-Audact-Call-ID-header)
• config_id (vereist): UUID van de LLM-configuratie (X-Audact-Config-ID-header)
• turn (vereist): Beurtnummer in het gesprek (X-Audact-Turn-header)
• Andere velden: Worden als verzoeklichaam doorgegeven aan de LLM-provider (bijv. messages, temperature, enz.)

Belangrijke opmerkingen

• Tenant komt altijd van uw sleutel: U kunt geen andere tenant opgeven; dit wordt automatisch ingevuld vanuit de geverifieerde API-sleutel.
• Bevestiging vereist: Roept proxy_openai aan met "confirm": true omdat het een betaalde LLM-aanroep doet.
• Streamen niet beschikbaar via MCP: Streamen (text/event-stream) is alleen via REST. MCP is JSON-only; gebruik /v1/llm-proxy/openai rechtstreeks voor streaming-antwoorden.
• Latentie: Deze aanroep loopt op het kritieke pad (harde deadline van 40 ms voor compliance-validatie); verwacht sub-second antwoorden voor de proxy zelf.

Voorbeeld

{
  "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. Wat NIET beschikbaar is (en waarom)

De MCP-server sluit in v1 bewust bepaalde operaties uit:

De gezaghebbende lijst, met één reden per vermelding, wordt bijgehouden in de uitsluitingsconfiguratie van de MCP-server.

Voor elk van deze, gebruikt u de REST API rechtstreeks met uw sleutel, of het Audact-dashboard.

11. Fouten en snelheidslimieten

Toolfouten

Wanneer een tool-aanroep via de MCP-server mislukt, krijgt u een toolfout met:

• code: De Audact API-foutcode (bijv. CALL_NOT_FOUND, INVALID_API_KEY, CONFIRMATION_REQUIRED, ARGUMENTS_TOO_LARGE, FILE_TOO_LARGE, INVALID_FILE_ENCODING)
• hint: Een voor mensen leesbare suggestie
• message: Volledige fouttekst

Voorbeeld:

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

Authenticatie en snelheidslimieten

• Transport 401 (HTTP 401): Ongeldige of ingetrokken API-sleutel. Controleer of uw sleutel correct is en niet is ingetrokken.
• Toolfout 403 (van backend): De rol van uw sleutel is onvoldoende voor deze tool. Upgrade naar Developer of Owner indien nodig.
• HTTP 429 (snelheidslimiet): /mcp/ heeft een snelheidslimiet van 600 verzoeken/minuut per sleutel, waarbij elk MCP-verzoek wordt geteld. Wanneer de limiet is bereikt, krijgt u HTTP 429 met een Retry-After-header; wacht dat aantal seconden voordat u het opnieuw probeert.
• Antwoordgroottelimiet (256 KiB): Als een lijstresultaat groter is dan 256 KiB, worden items vanaf het einde weggelaten zodat het resultaat geldige JSON blijft, en een veld _mcp_truncated geeft aan hoeveel er zijn weergegeven. next_cursor wordt verwijderd van een afgekapte pagina. Eén item boven de limiet geeft in plaats daarvan een toolfout RESPONSE_TOO_LARGE terug.

Time-outs

• Elke tool-aanroep heeft een time-out van 30 seconden. Netwerkvertragingen of trage upstream-operaties kunnen dit soms activeren. Als dit gebeurt, probeer het dan opnieuw na een korte vertraging.

12. Doorsturen en architectuur

Uw MCP-aanroepen worden met uw sleutel doorgestuurd naar de echte Audact REST API (/v1), precies zoals wanneer u die rechtstreeks had aangeroepen. Dit betekent:

• Machtigingen: De rol van uw sleutel bepaalt wat u kunt doen. Een Viewer-sleutel ziet alleen leestools; een Developer- of Owner-sleutel kan schrijven.
• Tenant-isolatie: Uw sleutel is gebonden aan één tenant. U kunt de gegevens van een andere tenant niet lezen of wijzigen, zelfs als u hun ID's op de een of andere manier doorgeeft.
• Controlelogboek: Elke aanroep wordt gelogd onder uw sleutel, net als een REST-aanroep.
• Idempotentie: Afgehandeld door dezelfde backendservices die REST afhandelen; geef idempotency_key door waar een tool dat aanbiedt.

Kortom: Een tool-aanroep via de MCP-server kan nooit meer doen dan dezelfde sleutel rechtstreeks tegen /v1 zou kunnen doen.

13. Voorbeelden

Agenten weergeven

Tool: list_agents
Argumenten: (geen)
→ Geeft een lijst van de agenten van uw tenant terug

Een webhook aanmaken

Tool: create_webhook
Argumenten:
  - body:
      url: "https://example.com/hook"
      events: ["call_ended", "call_summary"]
      scope: "account"
→ Geeft het nieuwe webhook-ID en de configuratie terug

Aflevering bevestigen

Tool: confirm_delivery
Argumenten:
  - body:
      call_id: "aaaabbbb-cccc-dddd-eeee-ffff00001111"
      delivered_text: "Your balance is low"
      mechanism: "voice"
→ Geeft 200 OK terug; bewijsgebeurtenis geregistreerd

Een KYC-document uploaden

Tool: upload_kyc_document
Argumenten:
  - doc_type: "passport"
  - file_base64: "JVBERi0xLjQK..." (base64-gecodeerd PDF)
  - file_name: "my_passport.pdf"
  - file_content_type: "application/pdf"
→ Geeft het document-ID en de uploadtijdstempel terug

14. Ondersteuning en feedback

• REST API-referentie: Audact API-referentie
• MCP-protocolspecificatie: Model Context Protocol
• Probleemoplossing:
  • Controleer of uw API-sleutel correct is en niet is ingetrokken.
  • Controleer of u https://api.audact.ai/mcp/ gebruikt als eindpunt-URL.
  • Als tools/list een lege lijst teruggeeft: de rol van uw sleutel is mogelijk onvoldoende. Probeer een Developer-sleutel.
  • Voor specifieke toolfouten: de foutcode en hint verwijzen naar de REST API-documentatie.
• Problemen melden: Audact Support

Snelle naslag