Model Context Protocol (MCP)

Connect AI assistants directly to TTS generation via the MCP standard.

Overview

MCP (Model Context Protocol) lets AI agents call TTS tools without custom HTTP integration. The server exposes 34 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.) — no install needed, npx handles it:

MCP client config

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

Set AITTS_API_KEY to your API key. Optionally set AITTS_API_URL to override the default API base URL. The CLI proxies tool calls to the v1 API over HTTP.

Remote HTTP (server-to-server)

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

Remote HTTP

# 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 (34)

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

Voice & Generation

Permissions: tts:generate, tts:status, voices:list

search_voicesgenerate_speechget_job_statusget_audio_link

Jobs

Permissions: jobs:read, jobs:write

list_jobsget_job_textupdate_job_metadatadelete_job_audio

Permissions: shares:read, shares:write

create_sharelist_sharesget_shareupdate_sharerevoke_sharebulk_revoke_sharestoggle_share_permanentupdate_track_order

Access Codes & QR

Permissions: shares:read, shares:write

create_access_codeslist_access_codesupdate_access_codedelete_access_codeexport_access_codesget_qr_code

Library

Permissions: library:read, library:write

list_collectionsmanage_collectionlist_tagscreate_bookmarklist_bookmarksdelete_bookmarkmanage_bookmark_collection

Storage & Usage

Permissions: storage:read, storage:write, usage:read, pricing:estimate

get_storagelist_storage_itemsbulk_delete_storageget_usageestimate_cost

Examples

Initialize

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

List tools

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

Generate speech

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

Generate speech (stream)

{
  "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"
    }
  }
}

Search voices

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

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.

Code	Meaning
-32700	Parse error — malformed JSON body
-32600	Invalid request — bad method or params
-32001	Authentication failed — missing or invalid API key
-32603	Internal server error

Next: API Reference · Examples · npm package

Back to Documentation