Model Context Protocol (MCP)

Overview

MCP (Model Context Protocol) lets AI agents call TTS tools without custom HTTP integration. The server exposes 35 tools covering generation, voices, jobs, shares, library management, and storage — the same capabilities as the REST API.

Two connection methods are available: a local stdio CLI for desktop AI apps, and a remote HTTP endpoint for server-side agents.

Connection Methods

Local stdio (recommended for desktop)

Add this to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "aittsm": {
      "command": "npx",
      "args": ["@theproductivepixel/aittsm"],
      "env": { "AITTSM_API_KEY": "tts_YOUR_KEY" }
    }
  }
}

Set AITTSM_API_KEY to your API key. Optionally set AITTSM_BASE_URL to override the default API base URL.

Remote HTTP (server-to-server)

Send JSON-RPC messages directly to POST /api/v1/mcp. Stateless — no session tracking required.

# Remote HTTP — single request
curl -X POST https://aitts.theproductivepixel.com/api/v1/mcp \
  -H "Authorization: Bearer tts_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available Tools (35)

Each tool requires specific API key permissions. Tools are grouped by function:

Patterns

Pagination

Paginated tools accept page_size (1–100, default 20) and page_token (opaque cursor). Results include next_page_token (null when done).

Delivery Mode

generate_speech supports two modes:

• async (default): Returns job_id. Poll get_job_status until completed, then get_audio_link.
• stream: Returns one-time stream_url for real-time audio. URL expires and is single-use. Durable artifact saved after stream completes.

Stream supports all 7 formats (wav, mp3, ogg_opus, pcm, mulaw, alaw, ogg_vorbis). Async supports wav, mp3, ogg_opus only.

Idempotency

Pass idempotency_key to generate_speech for safe retries. Same key + same body returns cached result. Same key + different body returns IDEMPOTENCY_KEY_REUSE (409). Key still processing returns REQUEST_IN_PROGRESS (409).

Rate Limiting

Tools use two buckets: read (higher limits, queries) and generate (lower limits, mutations). Limits are per-account. HTTP 429 with Retry-After header when exceeded.

Permissions

Examples

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "my-app", "version": "1.0.0" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "generate_speech",
    "arguments": {
      "text": "Hello from MCP!",
      "voice_id": "google:en-US-Chirp3HD-Charon"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "generate_speech",
    "arguments": {
      "text": "Stream this audio in real time.",
      "voice_id": "google:en-US-Chirp3HD-Charon",
      "delivery_mode": "stream",
      "idempotency_key": "my-unique-key-123"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "search_voices",
    "arguments": { "language": "en-US", "gender": "female" }
  }
}

Tool Reference

Complete parameter tables, response shapes, and error codes for every tool.

Error Codes

Tool errors are returned as text content with isError: true and a JSON payload: { error: "message", code: "ERROR_CODE", status: 400 }. Protocol-level errors (invalid JSON-RPC, unknown method) use standard JSON-RPC 2.0 error format.

Protocol Errors

Tool-Level Errors