Audact MCP-Server — Einrichtungsanleitung für Clients

Was ist das? Der Audact-MCP-Server (Model Context Protocol) stellt eine ausgewählte Menge von Audact-Operationen als Werkzeuge für KI-Assistenten bereit – Claude, Cursor, Claude Desktop oder jeden MCP-kompatiblen Client – über eine einfache HTTP-Schnittstelle. Verbinden Sie sich mit Ihrem Mandanten-API-Schlüssel und prüfen Sie Anrufe, verwalten Sie Agenten und Webhooks, erstellen Sie Compliance-Automatisierungen und steuern Sie Sprachoperationen.

Verfügbare Werkzeuge: 161 über alle Rollen hinweg

Endpunkte:

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

1. Was es ist

Der MCP-Server ist ein zustandsloser HTTP-Endpunkt, der Werkzeugaufrufe in Audact-REST-API-Operationen übersetzt. Er läuft über Streamable HTTP (den MCP-Standard für Server-zu-Client- und Client-zu-Server-JSON-RPC), erfordert zur Authentifizierung ausschließlich Ihren API-Schlüssel (Bearer-Token) und setzt exakt dieselben Berechtigungen und die Isolierung wie die REST-API selbst durch.

Warum MCP?

• Einrichtung mit einer Zeile: Keine handgeschriebenen Integrationen oder eigenen Brücken.
• Echtzeitkontext: Ihr KI-Assistent hat Live-Zugriff auf Agenten, Webhooks, Nummern, Anrufe und Nachweise.
• Berechtigungssicher: Jeder Werkzeugaufruf wird mit Ihrem Schlüssel weitergeleitet – ein Assistent kann nur das tun, was Ihre Schlüsselrolle erlaubt.
• Keine gespeicherten Geheimnisse: Der MCP-Server hält keine Anmeldedaten vor und schafft keine neue Angriffsfläche; er leitet Ihren Schlüssel Byte für Byte an die zugrunde liegende API weiter.

Transport und Protokoll

• Protokoll: Model Context Protocol (MCP), Version 2025-06-18 (rückwärtskompatibel mit 2025-03-26).
• Transport: Streamable HTTP POST an /mcp/ auf der Basis-URL Ihrer Umgebung.
• Inhalt: JSON-RPC 2.0 Anfragen und Antworten.
• Authentifizierung: Authorization: Bearer aud_live_… (Ihr Mandanten-API-Schlüssel, derselbe wie für REST).
• Zustandslos: Keine Sitzungen, keine Cookies. Jede Anfrage ist unabhängig; jedes Replikat kann sie bedienen.

Was OAuth hier bedeutet

OAuth wird nicht unterstützt. MCP Clients, die für Remote-Server zwingend OAuth erfordern, können sich nicht verbinden. Unterstützte Clients (Claude Code, Cursor, Claude Desktop über mcp-remote, MCP SDKs) übergeben Header direkt:

• ✅ Claude Code, Cursor, Claude Desktop mit mcp-remote: funktioniert
• ✅ MCP SDK Clients mit --header oder Umgebungsvariable: funktioniert
• ✅ Eigene MCP-Implementierungen, die Bearer-Token unterstützen: funktioniert
• ❌ Clients, die für Remote-Server ausschließlich OAuth unterstützen: in v1 nicht unterstützt

2. Ihren KI-Assistenten verbinden

Claude Code

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

Ersetzen Sie aud_live_… durch Ihren tatsächlichen API-Schlüssel (siehe Ihren Schlüssel abrufen weiter unten).

Zur Überprüfung: Starten Sie Claude Code nach dem Hinzufügen neu und fragen Sie: „Liste meine Agenten auf." Wenn dabei list_agents fehlerfrei aufgerufen wird, ist die Verbindung hergestellt.

Claude Desktop

Verwenden Sie mcp-remote, um den MCP-Server hinter dem lokalen Gateway zu betreiben:

# In der Konfigurationsdatei von Claude Desktop (~/.config/Claude/claude_desktop_config.json unter Linux/Mac,
# oder %APPDATA%\Claude\claude_desktop_config.json unter Windows):

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

Starten Sie Claude Desktop neu. Die Audact-Werkzeuge sollten nun in Ihrer Werkzeugliste erscheinen.

Cursor

Wie bei Claude Desktop: Fügen Sie es zur mcp_server_config.json von Cursor hinzu:

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

3. Ihren Schlüssel abrufen

1. Melden Sie sich beim Audact-Dashboard unter Ihrer Umgebungs-URL an.
2. Navigieren Sie zu API-Schlüssel (oder Einstellungen → API-Schlüssel).
3. Kopieren Sie einen Schlüssel mit der benötigten Rolle (Viewer, Developer oder Owner; siehe Rollenzuordnung weiter unten).
4. Verwenden Sie ihn in der obigen Konfiguration.

Halten Sie Ihren Schlüssel geheim. Behandeln Sie ihn wie ein Passwort. Falls er bekannt wird, widerrufen Sie ihn sofort im Dashboard.

4. Was Sie tun können: Werkzeuge nach Rolle

Der MCP-Server stellt insgesamt 161 Werkzeuge bereit, gruppiert nach Berechtigungsstufe und Fachbereich. Ein Werkzeug erscheint in den verfügbaren Werkzeugen Ihres Assistenten nur, wenn Ihr Schlüssel die erforderliche Rolle besitzt. Selbst wenn Sie ein Werkzeug auflisten, für das Sie keine Berechtigung haben, lehnt das Backend den Aufruf mit einer eindeutigen Fehlermeldung ab.

Rollenstufen

• Viewer: Nur-Lese-Zugriff. Prüfen Sie Anrufe, Nachweise, Konfigurationen, Webhooks und Nummern.
• Developer: Lese- und Schreibzugriff. Agenten, Werkzeuge, Webhooks und Zuweisungen erstellen/aktualisieren. Kein Löschen/Bereinigen.
• Owner: Vollzugriff, einschließlich Löschen und Einstellungsänderungen.

Werkzeugkategorien

Legende: R = nur lesend | D = destruktiv | C = erfordert Bestätigung (den Benutzer zuerst fragen, dann mit confirm: true erneut versuchen)

Agenten

Werkzeuge

Wissensdatenbanken

Stimmen

Integrationen

Konfigurationen

Anrufe und Nachweise

Webhooks

Telefonnummern

Mandant, Schlüssel und Sitzung

BYO-Telefonie (Bring Your Own)

KYC (Know Your Customer)

PII-Tresor

Anrufe (SIP) — Live-Anrufverwaltung

Weiterleitungen und Übergaben

SIP-Routing

Compliance-Laufzeit-API

LLM-Proxy

5. Bestätigung für gefährliche Aktionen

Einige Werkzeuge erfordern explizite Bestätigung, bevor sie ausgeführt werden. Dabei handelt es sich um Operationen, die Geld ausgeben, nicht rückgängig gemacht werden können oder die Sicherheit betreffen:

Die 33 Werkzeuge, die eine Bestätigung erfordern:

• Geldausgaben: create_number, create_number_order, initiate_outbound_call
• Irreversible Löschungen: 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
• Anrufsteuerung: initiate_inbound_call, create_browser_call, hangup_call, initiate_transfer, initiate_handover, bridge_transfer, cancel_transfer, end_transfer
• Konfiguration: create_dispatch_rule, create_inbound_trunk, create_outbound_trunk, set_admission_url, rotate_kyc_dek, pii_add_exemption, pii_put_settings
• Sicherheit: generate_key, exchange_key, create_event, proxy_openai

Wie die Bestätigung funktioniert

Wenn ein Werkzeug eine Bestätigung erfordert:

1. Der erste Aufruf schlägt mit CONFIRMATION_REQUIRED fehl:

   json

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

2. Das Modell fragt den Nutzer: „Dies wird {consequence}. Soll ich fortfahren?"

3. Nach Zustimmung des Nutzers wiederholt das Modell den Aufruf mit confirm: true:

   json

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

Wichtig: confirm ist eine Schutzmaßnahme gegen Prompt-Injection, kein Berechtigungssystem. Die Rolle Ihres API-Schlüssels bestimmt weiterhin, ob Sie das Werkzeug aufrufen dürfen. Ein confirm: true ohne die erforderliche Rolle wird mit einem 403-Fehler des Backends abgewiesen.

6. KYC-Dokumente hochladen

Der Upload von KYC-Dokumenten (Know Your Customer) erfolgt über den MCP-Server, indem die Binärdatei in JSON als base64 kodiert wird.

Parameter

• file_base64 (erforderlich): Der Dateiinhalt in base64 kodiert (Standard- oder URL-sicheres base64 werden beide akzeptiert; ungültige Kodierung → Werkzeugfehler INVALID_FILE_ENCODING)
• file_name (erforderlich): Originaldateiname (z. B. "passport.pdf")
• file_content_type (optional): MIME-Typ (z. B. "application/pdf"). Weglassen, wenn unbekannt.
• doc_type (erforderlich): Dokumenttyp-Code, der vom KYC-Backend akzeptiert wird (z. B. "passport" oder "proof_of_address")

Limits

• Dekodierte Dateigrößenbeschränkung: 10 MiB. Größere Dateien → Werkzeugfehler FILE_TOO_LARGE.
• Anfragegrößenlimit: 15 MiB für die gesamte /mcp/-Anfrage, was Platz für eine 10-MiB-Datei als base64 lässt.
• Werkzeuge ohne Datei sind auf 1 MiB Argumente begrenzt (ARGUMENTS_TOO_LARGE), außer validate_audio und reconcile_audio, die bis zum 15-MiB-Anfragelimit verwenden dürfen.

Beispiel

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

So erzeugen Sie base64 aus Ihrer Datei in der Kommandozeile:

base64 < my_passport.pdf

7. Personenbezogene Daten

pii_decrypt_call und pii_list_call_identities geben personenbezogene Daten im Klartext (Namen, E-Mail-Adressen, Telefonnummern usw.) direkt in das Kontextfenster des KI-Assistenten zurück.

Audact protokolliert keine Werkzeugargumente oder -ergebnisse, daher protokollieren wir selbst keine personenbezogenen Daten. Ob der KI-Assistent eines Mandanten personenbezogene Daten im Klartext empfangen darf, liegt in der Verantwortung des Mandanten gemäß seinem Datenverarbeitungsvertrag. Jeder Kunde muss sicherstellen, dass sein Datenvertrag dies zulässt.

Falls Sie mit einem Verantwortlichen zusammenarbeiten, der personenbezogene Daten in KI-Kontexten einschränkt, verwenden Sie statt des MCP-Servers direkt die REST-API mit angemessenen Zugriffskontrollen.

Zugangsdaten im Gespräch. generate_key gibt einen neuen API-Schlüssel zurück und exchange_key gibt ein Sitzungstoken zurück. Beide landen im Gesprächsverlauf des Assistenten (und überall, wo Ihr KI-Client diesen speichert). Beide erfordern confirm: true; widerrufen Sie einen Schlüssel, der möglicherweise offengelegt wurde, mit revoke_key.

Hinweis zu delete_call_recording: Die API erfordert die Eigentümer-Rolle, und der MCP-Server erfordert zusätzlich confirm: true.

8. Limits

Ratenlimit

• /mcp/-Endpunkt: 600 Anfragen/Minute pro Schlüssel. Zählt jeden Werkzeugaufruf, jedes tools/list.
• Timeout: 30 Sekunden pro Aufruf.

Argumentgrößenlimits

Hinweis: Audio größer als etwa 11 MiB erfordert weiterhin die REST-API; verwenden Sie für sehr große Dateien direkt POST /v1/validate-audio und POST /v1/audio-reconciliation.

Antwortgröße

• 256-KiB-Limit: Überschreitet ein Listenergebnis 256 KiB, werden vollständige Einträge vom Ende her abgeschnitten, sodass das Ergebnis gültiges JSON bleibt. Ein _mcp_truncated-Feld zeigt an, wie viele zurückgegeben wurden und wie viele auf die Seite gepasst hätten. Wiederholen Sie den Aufruf mit einem kleineren limit oder engeren Filtern.
• Einzel-Element-Antworten: Überschreitet ein einzelnes Element 256 KiB (selten), erhalten Sie stattdessen einen Werkzeugfehler RESPONSE_TOO_LARGE.

Weitere Limits

• Dateikodierung: Für file_base64 wird nur base64 (Standard oder URL-sicher) akzeptiert. Ungültige Kodierung → INVALID_FILE_ENCODING.
• Base64-Dekodierung: Die kodierte Größe muss in 10 MiB (dekodiert) passen; zu große Dateien → FILE_TOO_LARGE.

9. LLM-Proxy

Das Werkzeug proxy_openai leitet eine Anfrage an den Audact-LLM-Proxy weiter, der die Authentifizierung und das Routing zu Ihrem konfigurierten LLM-Anbieter verwaltet.

Parameter

• call_id (erforderlich): UUID des Anruf-Kontexts (X-Audact-Call-ID-Header)
• config_id (erforderlich): UUID der LLM-Konfiguration (X-Audact-Config-ID-Header)
• turn (erforderlich): Turnnummer im Gespräch (X-Audact-Turn-Header)
• Weitere Felder: Werden als Anfragekörper an den LLM-Anbieter übergeben (z. B. messages, temperature usw.)

Wichtige Hinweise

• Mandant immer aus Ihrem Schlüssel: Sie können keinen anderen Mandanten angeben; er wird automatisch aus dem authentifizierten API-Schlüssel ermittelt.
• Bestätigung erforderlich: proxy_openai wird mit "confirm": true aufgerufen, da es einen kostenpflichtigen LLM-Aufruf tätigt.
• Streaming über MCP nicht verfügbar: Streaming (text/event-stream) ist nur per REST möglich. MCP ist rein JSON-basiert; verwenden Sie für Streaming-Antworten direkt /v1/llm-proxy/openai.
• Latenz: Dieser Aufruf läuft auf dem Hot Path (40 ms harte Frist für die Compliance-Validierung); erwarten Sie Sub-Sekunden-Antworten für den Proxy selbst.

Beispiel

{
  "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. Was NICHT bereitgestellt wird (und warum)

Der MCP-Server schließt in v1 absichtlich einige Operationen aus:

Die maßgebliche Liste mit einem Grund pro Eintrag wird in der Ausschlusskonfiguration des MCP-Servers gepflegt.

Für all diese Fälle verwenden Sie die REST-API direkt mit Ihrem Schlüssel oder das Audact-Dashboard.

11. Fehler & Ratenlimits

Werkzeugfehler

Wenn ein Werkzeugaufruf des MCP-Servers fehlschlägt, erhalten Sie einen Werkzeugfehler mit:

• code: Der Audact-API-Fehlercode (z. B. CALL_NOT_FOUND, INVALID_API_KEY, CONFIRMATION_REQUIRED, ARGUMENTS_TOO_LARGE, FILE_TOO_LARGE, INVALID_FILE_ENCODING)
• hint: Ein menschenlesbarer Hinweis
• message: Vollständiger Fehlertext

Beispiel:

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

Authentifizierung & Ratenlimits

• Transport 401 (HTTP 401): Ungültiger oder widerrufener API-Schlüssel. Überprüfen Sie, ob Ihr Schlüssel korrekt und nicht widerrufen ist.
• Werkzeugfehler 403 (vom Backend): Ihre Schlüsselrolle ist für dieses Werkzeug unzureichend. Wechseln Sie bei Bedarf zu Developer oder Owner.
• HTTP 429 (Ratenlimit): /mcp/ ist auf 600 Anfragen/Minute pro Schlüssel begrenzt, wobei jede MCP-Anfrage gezählt wird. Bei Erreichen des Limits erhalten Sie HTTP 429 mit einem Retry-After-Header; warten Sie die angegebene Anzahl an Sekunden, bevor Sie es erneut versuchen.
• Antwortgrößenlimit (256 KiB): Ist ein Listenergebnis größer als 256 KiB, werden vollständige Einträge vom Ende her entfernt, sodass das Ergebnis gültiges JSON bleibt, und ein _mcp_truncated-Feld gibt an, wie viele angezeigt wurden. next_cursor wird von einer abgeschnittenen Seite entfernt. Ein einzelnes Element über dem Limit gibt stattdessen einen Werkzeugfehler RESPONSE_TOO_LARGE zurück.

Timeouts

• Jeder Werkzeugaufruf hat ein 30-Sekunden-Timeout. Netzwerkverzögerungen oder langsame vorgelagerte Operationen können dies gelegentlich auslösen. Versuchen Sie es nach einer kurzen Verzögerung erneut.

12. Weiterleitung & Architektur

Ihre MCP-Aufrufe werden mit Ihrem Schlüssel an die echte Audact-REST-API (/v1) weitergeleitet, genau so, als hätten Sie sie direkt aufgerufen. Das bedeutet:

• Berechtigungen: Ihre Schlüsselrolle bestimmt, was Sie tun können. Ein Viewer-Schlüssel sieht nur Lese-Werkzeuge; ein Developer- oder Owner-Schlüssel kann schreiben.
• Mandantenisolierung: Ihr Schlüssel ist an einen Mandanten gebunden. Sie können keine Daten eines anderen Mandanten lesen oder ändern, auch wenn Sie deren IDs übergeben.
• Prüfprotokoll: Jeder Aufruf wird unter Ihrem Schlüssel protokolliert, genau wie ein REST-Aufruf.
• Idempotenz: Wird von denselben Backend-Diensten wie REST verarbeitet; übergeben Sie idempotency_key, wo ein Werkzeug dies anbietet.

Kurzgefasst: Ein Werkzeugaufruf über den MCP-Server kann niemals mehr tun, als derselbe Schlüssel direkt gegen /v1 könnte.

13. Beispiele

Agenten auflisten

Tool: list_agents
Arguments: (none)
→ Returns a list of your tenant's agents

Webhook erstellen

Tool: create_webhook
Arguments:
  - body:
      url: "https://example.com/hook"
      events: ["call_ended", "call_summary"]
      scope: "account"
→ Returns the new webhook ID and configuration

Zustellung bestätigen

Tool: confirm_delivery
Arguments:
  - body:
      call_id: "aaaabbbb-cccc-dddd-eeee-ffff00001111"
      delivered_text: "Your balance is low"
      mechanism: "voice"
→ Returns 200 OK; evidence event recorded

KYC-Dokument hochladen

Tool: upload_kyc_document
Arguments:
  - doc_type: "passport"
  - file_base64: "JVBERi0xLjQK..." (base64-encoded PDF)
  - file_name: "my_passport.pdf"
  - file_content_type: "application/pdf"
→ Returns the document ID and upload timestamp

14. Support & Feedback

• REST-API-Referenz: Audact-API-Referenz
• MCP-Protokollspezifikation: Model Context Protocol
• Fehlerbehebung:
  • Stellen Sie sicher, dass Ihr API-Schlüssel korrekt und nicht widerrufen ist.
  • Stellen Sie sicher, dass Sie https://api.audact.ai/mcp/ als Endpunkt-URL verwenden.
  • Wenn tools/list eine leere Liste zurückgibt: Ihre Schlüsselrolle könnte unzureichend sein. Versuchen Sie einen Developer-Schlüssel.
  • Bei spezifischen Werkzeugfehlern: Fehlercode und Hinweis verweisen auf die REST-API-Dokumentation.
• Probleme melden: Audact Support

Kurzübersicht