# ElevenLabs Agents Platform — MCP Server

Local MCP server (stdio) that gives Claude full control of the ElevenLabs Agents Platform (Conversational AI): agents, conversations, knowledge base, tools, tests, telephony, batch calling, and workspace settings.

## Tools (50)

| Group | Tools |
|---|---|
| Agents | `el_list_agents`, `el_get_agent`, `el_create_agent`, `el_update_agent`, `el_delete_agent`, `el_duplicate_agent`, `el_get_agent_link`, `el_simulate_conversation` |
| Conversations | `el_list_conversations`, `el_get_conversation`, `el_delete_conversation`, `el_get_conversation_audio`, `el_get_signed_url`, `el_send_conversation_feedback` |
| Knowledge base | `el_list_kb_documents`, `el_get_kb_document`, `el_create_kb_document` (url/text/file), `el_delete_kb_document`, `el_get_kb_document_content`, `el_get_kb_dependent_agents`, `el_rag_index` |
| Agent tools | `el_list_tools`, `el_get_tool`, `el_create_tool`, `el_update_tool`, `el_delete_tool`, `el_get_tool_dependent_agents` |
| Tests | `el_list_tests`, `el_get_test`, `el_create_test`, `el_run_tests_on_agent`, `el_get_test_invocation` |
| Telephony | `el_list_phone_numbers`, `el_get_phone_number`, `el_import_phone_number`, `el_update_phone_number`, `el_outbound_call`, `el_submit_batch_call`, `el_list_batch_calls`, `el_get_batch_call`, `el_batch_call_action` |
| Workspace | `el_get_workspace_settings`, `el_update_workspace_settings`, `el_list_secrets`, `el_create_secret`, `el_delete_secret`, `el_list_llms`, `el_get_widget_config`, `el_search_voices` |
| Escape hatch | `el_api_request` — any other `/v1/convai/*` endpoint (branches, versions, analytics, WhatsApp, MCP integrations, …) |

Design notes:
- **Safety**: every destructive tool (`delete_*`, outbound/batch calls, workspace settings) requires `confirm=true`. `DELETE` is blocked on the raw escape hatch.
- **Tool annotations**: every tool ships MCP `ToolAnnotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients can flag safe vs. side-effecting tools. Read-only = GET-only tools (26 of 50); the destructive ones line up with the `confirm=true` gates.
- **Context-friendly**: responses truncate at 50k chars; `el_get_conversation` supports `transcript_only` / `include_transcript=false`; voice search returns slim results.
- **Data residency**: point `ELEVENLABS_API_BASE` at your regional endpoint (EU: `https://api.eu.residency.elevenlabs.io`).

## Setup

```bash
cd elevenlabs-agents-mcp
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```

### Claude Desktop / Cowork

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "elevenlabs-agents": {
      "command": "/ABSOLUTE/PATH/elevenlabs-agents-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/elevenlabs-agents-mcp/server.py"],
      "env": { "ELEVENLABS_API_KEY": "sk_..." }
    }
  }
}
```

### Claude Code

```bash
claude mcp add elevenlabs-agents \
  -e ELEVENLABS_API_KEY=sk_... \
  -- /ABSOLUTE/PATH/elevenlabs-agents-mcp/.venv/bin/python /ABSOLUTE/PATH/elevenlabs-agents-mcp/server.py
```

### As part of a Cowork/Claude Code plugin

Reference it in the plugin's `.mcp.json`:

```json
{
  "mcpServers": {
    "elevenlabs-agents": {
      "command": "python3",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.py"],
      "env": { "ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}" }
    }
  }
}
```

## Cloud Run deployment (production)

The repo ships production-ready: `http_server.py` (streamable HTTP transport, stateless JSON), `Dockerfile`, `deploy.sh`.

```bash
gcloud auth login && gcloud config set project YOUR_PROJECT_ID
ELEVENLABS_API_KEY=sk_... ./deploy.sh
```

The script enables APIs, stores the API key and a generated 64-char bearer token in **Secret Manager**, deploys from source to Cloud Run (Frankfurt `europe-west3`, 512Mi, scale-to-zero, max 3 instances), smoke-tests `/healthz` + auth, and prints the connect command:

```bash
claude mcp add --transport http elevenlabs-agents https://SERVICE_URL/mcp \
  --header "Authorization: Bearer TOKEN"
```

Production properties:

- **Auth**: every `/mcp` request needs the bearer token (constant-time compare); server refuses to boot without a ≥32-char token. Alternative IAM-only mode: `MCP_ALLOW_UNAUTHENTICATED=true` + `--no-allow-unauthenticated`.
- **Stateless JSON transport**: no sessions/SSE — safe for horizontal scaling and scale-to-zero.
- **Secrets**: only in Secret Manager, injected as env; never in image, logs, or responses.
- **Logging**: structured JSON per request (method/path/status/latency) → Cloud Logging. Bodies and transcripts are never logged (PII).
- **Resilience**: retry with exponential backoff + `Retry-After` on 429/502/503/504; pooled connections; 90s upstream timeout, 300s request timeout for long simulations.
- **Read-only mode**: deploy with `READ_ONLY=true ./deploy.sh` to hard-block all non-GET operations server-side (good for analytics-only access).
- **Cost/blast-radius caps**: `min-instances=0` (≈€0 idle), `max-instances=3`.
- **Token rotation**: `ROTATE_TOKEN=1 ./deploy.sh`.
- **Non-root container**, slim base image, layer-cached deps.

## Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `ELEVENLABS_API_KEY` | yes | — | API key (Profile → API keys) |
| `MCP_AUTH_TOKEN` | HTTP mode | — | Bearer token protecting /mcp |
| `MCP_ALLOW_UNAUTHENTICATED` | no | `false` | Skip bearer auth (only behind IAM) |
| `ELEVENLABS_MCP_READ_ONLY` | no | `false` | Block all non-GET API calls |
| `ELEVENLABS_API_BASE` | no | `https://api.elevenlabs.io` | Data-residency region |
| `ELEVENLABS_MCP_MAX_CHARS` | no | `50000` | Response truncation limit |
| `PORT` | no | `8080` | HTTP port (Cloud Run sets this) |

## Quick test

```bash
ELEVENLABS_API_KEY=sk_... npx @modelcontextprotocol/inspector .venv/bin/python server.py
```

## Example prompts once connected

- "List my ElevenLabs agents and show the config of the Projektinterview agent."
- "Duplicate agent X, change the system prompt to …, then simulate a conversation with a skeptical consultant persona."
- "Pull yesterday's conversations for agent X and summarize failure reasons."
- "Add https://example.com/faq to the knowledge base and enable RAG on it."