aethexai-mcp

Aethex MCP Server

Drive the Aethex voice platform from any MCP client.
Synthesize speech, transcribe audio, build voice agents and their knowledge bases,
place calls, browse conversations, and read usage, from Claude, Cursor, Codex, and more.

Documentation  ·  Dashboard  ·  API Reference  ·  Discord  ·  Support

The Model Context Protocol (MCP) server for the Aethex voice-AI platform. It wraps the public Aethex API through the aethexai Python SDK and exposes it as MCP tools, so clients like Claude Desktop, Claude Code, Cursor, Windsurf, and Codex can run voice workflows directly. Authentication is one variable, AETHEX_API_KEY; every tool runs scoped to that key's tenant.

Install

Run it with uv; your MCP client launches it on demand, with no install step:

uvx aethexai-mcp

Or install it into an environment:

pip install aethexai-mcp

Requires Python 3.11+. Get an AETHEX_API_KEY from the developer portal.

Quickstart

Add the server to Claude Desktop under Settings > Developer > Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "Aethex": {
      "command": "uvx",
      "args": ["aethexai-mcp"],
      "env": { "AETHEX_API_KEY": "ae_live_..." }
    }
  }
}

Restart Claude and ask it to "list my Aethex voices". On Windows, enable Help > Enable Developer Mode first.

MCP clients

Any MCP client works. Common setups:

Codex (~/.codex/config.toml):

[mcp_servers.aethex]
command = "uvx"
args = ["aethexai-mcp"]
env = { AETHEX_API_KEY = "ae_live_..." }

To override the API base URL, add AETHEX_BASE_URL to the env.

Core workflows

⚠️ Synthesizing speech, transcribing audio, and placing calls consume Aethex credits.

Everything is driven in natural language. A few examples:

Text to speech

"List my available voices, then read this paragraph aloud with the most neutral one."

Transcription

"Transcribe this recording and summarize what the caller asked for."

Voice agents and knowledge

"Create a voice agent that books dentist appointments, attach our FAQ as a knowledge document, then place a test call to my number."

Conversations and usage

"Search my conversations for anyone who mentioned a refund and pull the full transcript of the most recent one."

"Show me this month's usage and which model handled the most minutes."

Tools

32 tools across 7 domains. Every tool runs scoped to the tenant behind your AETHEX_API_KEY and requires that key to carry the listed scope.

Voices & text-to-speech

Transcription

Voice agents

Agent knowledge bases

Calls

Conversations

Usage & models

Configuration

The server is configured entirely through environment variables; only the API key is required.

Output modes

AETHEX_MCP_OUTPUT_MODE controls how the audio-producing tools (synthesize_speech, preview_voice) return results:

1. files (default): save the audio to disk and return the file path.
2. resources: return the audio inline as a base64-encoded MCP resource, with no disk I/O. Handy for containerized or sandboxed clients.
3. both: save to disk and return the resource; a saved resource can be fetched later via its aethex://<filename> URI.

Troubleshooting

Claude Desktop logs:

• macOS: ~/Library/Logs/Claude/mcp-server-Aethex.log
• Windows: %APPDATA%\Claude\logs\mcp-server-Aethex.log

AETHEX_API_KEY environment variable is required: the server refuses to start without a key. Set it in the env block of your client config (or your shell), using a valid key from the developer portal.

Timeouts on long-running tools: large transcriptions especially can take a while, and the MCP Inspector may report a timeout even though the tool finished. Prefer submit_transcription_job + get_transcription_job over a single synchronous call.

spawn uvx ENOENT: your client can't find uvx on its PATH. Run which uvx and use that absolute path as the command (e.g. /usr/local/bin/uvx).

Development

Run from source:

git clone https://github.com/aethexai/aethexai-mcp
cd aethexai-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

./scripts/test.sh                            # pytest (add --verbose / --fail-fast)
uv run fastmcp dev aethexai_mcp/server.py    # explore every tool in the MCP Inspector

Questions can be sent to developers@aethexai.com.

Community

• GitHub: github.com/aethexai
• X: @aethexailabs
• LinkedIn: AethexAI
• Discord: discord.gg/ccyuJNZm7x

License

Released under the MIT License.