Audact MCP server — client setup guide

What is it? The Audact MCP (Model Context Protocol) server exposes a curated set of Audact operations as tools for AI assistants—Claude, Cursor, Claude Desktop, or any MCP-compatible client—over a simple HTTP interface. Connect with your tenant API key and inspect calls, manage agents and webhooks, build compliance automations, and control voice operations.

Tools available: 161 across all roles

Endpoints:

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

1. What It Is

The MCP server is a stateless, HTTP endpoint that translates tool calls into Audact REST API operations. It runs over Streamable HTTP (the MCP standard for server-to-client and client-to-server JSON-RPC), requires only your API key for authentication (Bearer token), and enforces the exact same permissions and isolation as the REST API itself.

Why MCP?

• One-line setup: No handwritten integrations or custom bridges.
• Real-time context: Your AI assistant has live access to agents, webhooks, numbers, calls, and evidence.
• Permission-safe: Every tool call is forwarded with your key—an assistant can only do what your key role allows.
• No secrets held: The MCP server holds no credentials and creates no new security surface; it forwards your key byte-for-byte to the underlying API.

Transport & Protocol

• Protocol: Model Context Protocol (MCP), version 2025-06-18 (backward compatible with 2025-03-26).
• Transport: Streamable HTTP POST to /mcp/ on your environment's base URL.
• Content: JSON-RPC 2.0 requests and responses.
• Authentication: Authorization: Bearer aud_live_… (your tenant API key, same one you use for REST).
• Stateless: No sessions, no cookies. Every request is independent; any replica can serve it.

What OAuth Means Here

OAuth is not supported. MCP clients that require OAuth with remote servers cannot connect. Supported clients (Claude Code, Cursor, Claude Desktop via mcp-remote, MCP SDKs) all pass headers directly:

• ✅ Claude Code, Cursor, Claude Desktop with mcp-remote: works
• ✅ MCP SDK clients with --header or env var: works
• ✅ Custom MCP implementations that support Bearer tokens: works
• ❌ Clients that only support OAuth for remote servers: not supported in v1

2. Connect Your AI Assistant

Claude Code

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

Replace aud_live_… with your actual API key (see Getting Your Key below).

To verify: After adding, restart Claude Code and ask it: "List my agents." If it calls list_agents without error, it's connected.

Claude Desktop

Use mcp-remote to run the MCP server behind the local gateway:

# 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_…"
      }
    }
  }
}

Restart Claude Desktop. The Audact tools should now appear in your Tools list.

Cursor

Same as Claude Desktop: add to Cursor's mcp_server_config.json:

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

3. Getting Your Key

1. Log in to the Audact dashboard at your environment URL.
2. Navigate to API Keys (or Settings → API Keys).
3. Copy a key with the role you need (Viewer, Developer, or Owner; see Role Mapping below).
4. Use it in the config above.

Keep your key secret. Treat it like a password. If exposed, revoke it immediately from the dashboard.

4. What You Can Do: Tools by Role

The MCP server exposes 161 tools in total, grouped by permission level and domain. A tool appears in your assistant's available tools only if your key has the required role. Even if you list a tool you don't have permission for, the backend will reject the call with a clear error.

Role Levels

• Viewer: Read-only access. Inspect calls, evidence, configurations, webhooks, and numbers.
• Developer: Read and write. Create/update agents, tools, webhooks, and assignments. No delete/purge.
• Owner: Full access, including delete and settings changes.

Tool Categories

Legend: R = read-only | D = destructive | C = requires confirmation (ask the user first, then retry with confirm: true)

Agents

Tools

Knowledge Bases

Voices

Integrations

Configurations

Calls & Evidence

Webhooks

Phone Numbers

Tenant, Keys & Session

BYO Telephony (Bring Your Own)

KYC (Know Your Customer)

PII Vault

Calls (SIP) — Live Call Management

Transfers & Handovers

SIP Routing

Compliance Runtime API

LLM Proxy

5. Confirmation for Dangerous Actions

Some tools require explicit confirmation before they execute. These are operations that spend money, are irreversible, or affect security:

The 33 tools that require confirmation:

• Money-spending: create_number, create_number_order, initiate_outbound_call
• Irreversible deletes: 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
• Call control: 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
• Security: generate_key, exchange_key, create_event, proxy_openai

How Confirmation Works

When a tool requires confirmation:

1. First call fails with 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. The model asks the user: "This will {consequence}. Should I proceed?"

3. After user approval, the model retries with 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 is a safeguard against prompt injection, not a permission system. Your API key's role still determines whether you can call the tool. A confirm: true without the required role still gets rejected with a 403 error from the backend.

6. Uploading KYC Documents

KYC (Know Your Customer) document upload works through the MCP by converting the binary file to base64 in JSON.

Parameters

• file_base64 (required): The file content encoded in base64 (standard or URL-safe base64 are both accepted; invalid encoding → tool error INVALID_FILE_ENCODING)
• file_name (required): Original filename (e.g., "passport.pdf")
• file_content_type (optional): MIME type (e.g., "application/pdf"). Omit if unknown.
• doc_type (required): Document type code accepted by the KYC backend (e.g., "passport" or "proof_of_address")

Limits

• Decoded file size limit: 10 MiB. Larger files → tool error FILE_TOO_LARGE.
• Request size limit: 15 MiB for the whole /mcp/ request, which leaves room for a 10 MiB file as base64.
• Tools without a file are capped at 1 MiB of arguments (ARGUMENTS_TOO_LARGE), except validate_audio and reconcile_audio, which may use up to the 15 MiB request limit.

Example

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

To generate base64 from your file on the command line:

base64 < my_passport.pdf

7. Personal Data

pii_decrypt_call and pii_list_call_identities return plaintext personal data (names, email, phone numbers, etc.) directly into the AI assistant's context window.

Audact logs no tool arguments or results, so we do not log PII ourselves. However, whether a tenant's own AI assistant may receive plaintext personal data is the tenant's responsibility under its Data Processing Agreement. Each customer must ensure their data agreement permits this.

If you work with a data controller who restricts PII in AI contexts, use the REST API directly with proper access controls instead of the MCP server.

Credentials in the conversation. generate_key returns a new API key secret and exchange_key returns a session token. Both land in the assistant's conversation history (and wherever your AI client stores it). Both require confirm: true; revoke a key that may have been exposed with revoke_key.

Note on delete_call_recording: the API requires the Owner role, and MCP additionally requires confirm: true.

8. Limits

Rate Limit

• /mcp/ endpoint: 600 requests/minute per key. Counts every tool call, every tools/list.
• Timeout: 30 seconds per call.

Argument Size Limits

Note: Audio larger than about 11 MiB still requires the REST API; use POST /v1/validate-audio and POST /v1/audio-reconciliation directly for very large files.

Response Size

• 256 KiB cap: If a list result exceeds 256 KiB, whole items are trimmed from the end so the result stays valid JSON. An _mcp_truncated field shows how many were returned and how many fit on the page. Retry with a smaller limit or narrower filters.
• Single-item responses: If one item exceeds 256 KiB (rare), you get a tool error RESPONSE_TOO_LARGE instead.

Other Limits

• File encoding: Only base64 (standard or URL-safe) is accepted for file_base64. Invalid encoding → INVALID_FILE_ENCODING.
• Base64 decoding: Encoded size must fit within 10 MiB (decoded); oversized → FILE_TOO_LARGE.

9. LLM Proxy

The proxy_openai tool forwards a request to the Audact LLM proxy, which manages authentication and routing to your configured LLM provider.

Parameters

• call_id (required): UUID of the call context (X-Audact-Call-ID header)
• config_id (required): UUID of the LLM configuration (X-Audact-Config-ID header)
• turn (required): Turn number in the conversation (X-Audact-Turn header)
• Other fields: Passed as the request body to the LLM provider (e.g., messages, temperature, etc.)

Important Notes

• Tenant is always from your key: You cannot specify a different tenant; it is automatically filled from the authenticated API key.
• Requires confirmation: Calls proxy_openai with "confirm": true because it makes a paid LLM call.
• Streaming not available over MCP: Streaming (text/event-stream) is REST-only. MCP is JSON-only; use /v1/llm-proxy/openai directly for streaming responses.
• Latency: This call runs on the hot path (40ms hard deadline for compliance validation); expect sub-second responses for the proxy itself.

Example

{
  "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. What Is NOT Exposed (and Why)

The MCP server deliberately excludes some operations in v1:

The authoritative list, with one reason per entry, is maintained in the MCP server's exclusions configuration.

For any of these, use the REST API directly with your key, or the Audact dashboard.

11. Errors & Rate Limits

Tool Errors

When an MCP tool call fails, you get a tool error with:

• code: The Audact API error code (e.g., CALL_NOT_FOUND, INVALID_API_KEY, CONFIRMATION_REQUIRED, ARGUMENTS_TOO_LARGE, FILE_TOO_LARGE, INVALID_FILE_ENCODING)
• hint: A human-readable suggestion
• message: Full error text

Example:

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

Authentication & Rate Limits

• Transport 401 (HTTP 401): Invalid or revoked API key. Check that your key is correct and not revoked.
• Tool error 403 (from backend): Your key role is insufficient for this tool. Upgrade to Developer or Owner if needed.
• HTTP 429 (rate limit): /mcp/ is rate-limited to 600 requests/minute per key, counting every MCP request. When the limit is reached you get HTTP 429 with a Retry-After header; wait that many seconds before retrying.
• Response size cap (256 KiB): If a list result is larger than 256 KiB, whole items are dropped from the end so the result stays valid JSON, and an _mcp_truncated field says how many were shown. next_cursor is removed from a trimmed page. A single item over the cap returns a RESPONSE_TOO_LARGE tool error instead.

Timeouts

• Each tool call has a 30-second timeout. Network delays or slow upstream operations can occasionally trigger this. If it happens, retry after a brief delay.

12. Forwarding & Architecture

Your MCP calls are forwarded to the real Audact REST API (/v1) with your key, exactly as if you had called it directly. This means:

• Permissions: Your key role determines what you can do. A Viewer key sees only read tools; a Developer or Owner key can write.
• Tenant isolation: Your key is tied to one tenant. You cannot read or modify another tenant's data, even if you somehow pass their IDs.
• Audit trail: Every call is logged under your key, just like a REST call.
• Idempotency: Handled by the same backend services that handle REST; pass idempotency_key where a tool offers it.

In short: An MCP tool call can never do more than the same key could do against /v1 directly.

13. Examples

List Agents

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

Create a Webhook

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

Confirm Delivery

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

Upload a KYC Document

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 reference: Audact API reference
• MCP protocol spec: Model Context Protocol
• Troubleshooting:
  • Verify your API key is correct and not revoked.
  • Verify that you're using https://api.audact.ai/mcp/ as the endpoint URL.
  • For tools/list returning an empty list: your key's role may be insufficient. Try a Developer key.
  • For specific tool errors: the error code and hint point to the REST API documentation.
• Report issues: Audact Support

Quick Reference