MCP server

Drive Aethex from Claude Code, Codex, and other MCP clients. The Aethex MCP server turns voices, transcription, agents, calls, and usage into tools any compatible assistant can call on your behalf.

Overview

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools through one uniform interface. The Aethex MCP server is a standalone program that speaks MCP on one side and the Aethex API on the other, so an assistant like Claude can synthesize speech, transcribe audio, build voice agents, place calls, and read your usage without leaving the chat.It is published as the aethexai-mcp package and runs locally. Your MCP client launches it on demand with uvx aethexai-mcp, so there is nothing to host and no extra service to keep running. Every action it takes is a call to the same public Aethex API you already use, scoped to the API key you give it.It works with any MCP-compatible client. Claude Code and Codex are shown below; Claude Desktop, Cursor, and Windsurf are covered under More clients.

QUICKSTART

Connect Claude Code or Codex

First, create an API key in the developer portal. You also need uv, the Python package manager that ships the uvx launcher; install it with curl -LsSf https://astral.sh/uv/install.sh | sh.Claude Code registers the server with a single command. Codex reads it from ~/.codex/config.toml. Pick your client below, then ask it to list your Aethex voices to confirm the connection.

Tip

If the client reports that it cannot find uvx, set command to its absolute path, which you can find by running which uvx. To target a non-production environment, add AETHEX_BASE_URL to the env.

bash

claude mcp add aethex --env AETHEX_API_KEY=your-api-key -- uvx aethexai-mcp
claude mcp list

More clients

Any MCP client runs the same uvx aethexai-mcp command; only the configuration format differs.Claude Desktop. Open Settings, Developer, Edit Config and add the JSON block below to claude_desktop_config.json, then restart. On Windows, enable Developer Mode first from the Help menu.Cursor and Windsurf. Paste the same mcpServers block into the client's MCP settings.To generate a ready-to-paste block for any client, install the package with pip install aethexai-mcp and run python -m aethexai_mcp --api-key=your-api-key --print.

claude_desktop_config.json

json

{
  "mcpServers": {
    "Aethex": {
      "command": "uvx",
      "args": ["aethexai-mcp"],
      "env": {
        "AETHEX_API_KEY": "your-api-key"
      }
    }
  }
}

Authentication and scopes

The server needs exactly one credential: your AETHEX_API_KEY. There is no separate login, region, or environment to configure. Every tool runs against the tenant that owns the key, and each tool requires the matching scope on that key, so a key without calls:write cannot place calls. See API key scopes for what each action needs, and create a dedicated key for your assistant so you can rotate or revoke it on its own.By default the server talks to production at https://api.aethexai.com. To point it at another environment, set AETHEX_BASE_URL in the same env block.

Note

Treat the key like a password. It is stored in your client config and grants the assistant every action its scopes allow. Give the assistant a key scoped to only what it needs.

What you can do

The server groups Aethex into seven areas of tools. The assistant picks the right tool for each request and reports back the ids, file paths, and statuses it receives.Voices and text to speech. List the voices available to your tenant, audition one with a short preview, and synthesize text to speech with a chosen voice.Transcription. Transcribe short audio synchronously, or submit a longer file as a job and poll for the result.Voice agents. Create, fetch, update, list, duplicate, and delete voice agents.Knowledge bases. Attach documents to an agent, list them, run hybrid retrieval to check what the agent can find, and remove documents.Calls. Place a single outbound call or a batch, then track each call's status and pull the full record.Conversations. List and search past conversations, read their transcripts, and attach feedback.Usage and models. Report usage for the tenant or a single key, broken down by day or month, and list the available models.

Audio output modes

Tools that produce audio, such as speech synthesis and voice previews, can return their result in three ways. Set AETHEX_MCP_OUTPUT_MODE in the env block to choose.`files` is the default. It saves the audio to disk and returns the file path. The location defaults to your Desktop and can be changed with AETHEX_MCP_BASE_PATH.`resources` returns the audio inline as an MCP resource with no disk writes, which suits sandboxed or containerized clients.`both` saves to disk and returns the resource.

Return audio inline instead of writing files

json

"env": {
  "AETHEX_API_KEY": "your-api-key",
  "AETHEX_MCP_OUTPUT_MODE": "resources"
}

Cost and safe operation

Some tools spend credits and take real-world actions. Speech synthesis, voice previews, transcription, and outbound calls all consume Aethex credits, and a call dials a real phone number. Ask the assistant to check your usage before a large batch, and confirm the recipient before it places a call.The server is built so the assistant looks up real ids before it acts and confirms deletes, cancellations, and outbound calls. Keep that habit: review what the assistant proposes before you approve anything that spends credits or changes your data.

Heads up

Outbound calls and deletes are hard to undo. Use a key scoped to only the actions you want the assistant to take, and review any step that places a call or removes data before you approve it.

Next steps

Create a scoped key in API keys, pick a voice in the Voice Library, and read Agents to design the agent your assistant will build and call with. For programmatic access without an assistant, see the Python SDK.