MCP Server

Give AI agents scoped access to ToneBoard — voices, characters, content, and audio generation as MCP tools

Overview

ToneBoard hosts a Model Context Protocol (MCP) server, so AI agents like Claude Code, Claude Desktop, and claude.ai projects can work with your organization directly: browse voices, create characters, search saved content, and generate speech or sound effects.

The server authenticates with the same scoped API keys as the REST API — and the tool list itself is filtered by the key's scopes. An agent connected with a read-only key never even sees the write tools.

Property	Value
Endpoint	`https://<host>/api/v1/mcp`
Transport	Streamable HTTP (stateless, JSON responses)
Authentication	`Authorization: Bearer <api key>` or `X-API-Key` header
Capabilities	Tools only

Connecting

Claude Code (CLI)

claude mcp add --transport http toneboard https://<host>/api/v1/mcp \
  --header "Authorization: Bearer <your-api-key>"

Project config (.mcp.json)

{
  "mcpServers": {
    "toneboard": {
      "type": "http",
      "url": "https://<host>/api/v1/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Try it

After connecting, ask the agent to run verify_access — it reports the organization and scopes the connection has, which explains exactly which tools are available.

Tools

Tool	Required scope	What it does
`verify_access`	—	Show the connection's organization and scopes
`list_projects`	`projects:read`	List projects
`list_characters`	`characters:read`	List characters (optional project filter)
`get_character`	`characters:read`	Get one character
`create_character`	`characters:write`	Create a character (internal or external voice)
`delete_character`	`characters:write`	Delete a character (guarded against live-endpoint use)
`list_voices`	`voices:read`	List project voices
`create_voice`	`voices:write`	Adopt an external provider voice into a project
`delete_voice`	`voices:write`	Delete a project voice (guarded against character use)
`list_internal_voices`	`internal_voices:read`	List Voice Studio custom voices
`design_internal_voice`	`internal_voices:write`	Design voice previews from a prompt (spends tokens)
`save_internal_voice`	`internal_voices:write`	Persist a designed preview (spends tokens)
`delete_internal_voice`	`internal_voices:write`	Delete an internal voice (guarded)
`list_voice_providers`	`external_voices:read`	List provider connections
`list_external_voices`	`external_voices:read`	Browse a provider's available voices
`list_content`	`lines:read \| sfx:read`	Search saved lines and sound effects
`get_content`	`lines:read \| sfx:read`	Get one item with full version history
`set_active_content_version`	`lines:write \| sfx:write`	Pin which version of an item is active
`delete_content`	`lines:write \| sfx:write`	Delete an item and all version audio
`generate_sfx`	`sfx:write`	Generate a sound effect; optional save to the library
`generate_speech`	`tts:generate`	Generate speech for a character; optional save as a line (needs lines:write)

Per-item scoping

Content tools check the item's type at call time: a key with only sfx:write can manage sound effects but gets a scope error on lines, even through the same tool.

Example Session

A typical agent workflow with a key scoped to characters:read, tts:generate, and lines:write:

You: "Generate a greeting line for the Narrator character and save it as 'Greeting v3'."

Agent:
1. verify_access            -> sees tts:generate, lines:write, characters:read
2. list_characters          -> finds "Narrator" (id: chr_...)
3. generate_speech          -> { characterId: "chr_...", text: "Welcome...",
                                 saveName: "Greeting v3" }
4. Replies with the audio URL; the line is in Saved Content as the active version.

Notes

Topic	Behavior
Rate limit	60 requests/minute per key, shared with the REST API
Tokens	Generation tools spend organization tokens; failures refund automatically
Sessions	The server is stateless — no session ids, safe behind serverless scaling
Errors	Tool failures return readable messages (scope, validation, balance) the agent can act on