Use Arqenne with your AI agent

Arqenne ships with a built-in Model Context Protocol (MCP) server. Once you connect your AI agent to it, you can ask the agent to generate speech directly — no API keys, no per-call charges, no monthly credit caps. Audio is generated locally on your Mac using Arqenne's TTS engine.

This guide walks through setup for the four agents most users have:

• Claude Desktop
• Claude Code
• Cursor
• OpenCode

If your agent supports MCP and isn't on this list, the generic configuration at the bottom should work.

Before you start

You need:

1. Arqenne installed in /Applications. If you're running it from the DMG window, drag it to the Applications folder first. Apps run from the DMG use a temporary path that breaks after a reboot.
2. Signed in to Arqenne. Open the app and sign in with your account.
3. Arqenne running. The MCP server only works while Arqenne is running. If you want it always available, enable "Launch at login" in Arqenne's settings.

That's it. No API key generation, no token copying, no separate authentication step. Arqenne handles its own auth, and the MCP server inherits your signed-in session.

What your agent can do

Once connected, the agent has access to three tools:

A few example things you can ask your agent:

"Read me back the function I just wrote."

"Generate a voiceover for this script using a British male voice."

"After every response in this conversation, also generate audio of your reply."

Free accounts use one voice — Morpheus (am_michael). Paid accounts have access to all 29 voices.

Claude Desktop

The simplest setup. Edit your Claude Desktop config:

macOS:

open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the file doesn't exist, create it. Add the arqenne entry to mcpServers:

{
  "mcpServers": {
    "arqenne": {
      "command": "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp"
    }
  }
}

Restart Claude Desktop. You should see a small tool icon appear in the chat input — that's the indicator that an MCP server is connected. Click it to verify Arqenne's three tools are listed.

Test it:

"Use Arqenne to say hello world out loud."

Claude should call text_to_speech and return a file path. By default, the file lands in Arqenne's cache directory (~/Library/Caches/com.arqenne.studio/tts_mcp/), which macOS may purge under disk pressure. If you want audio in a persistent, easy-to-find place, see keeping audio files below.

Optional: customize the audio output

Add an env block to control where files go:

{
  "mcpServers": {
    "arqenne": {
      "command": "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp",
      "env": {
        "ARQENNE_MCP_OUTPUT_DIR": "~/Desktop"
      }
    }
  }
}

Now generated audio lands on your Desktop. See the environment variables reference for all options.

Claude Code

Claude Code reads MCP config from .mcp.json in your project root, or from a user-level config file.

For a single project:

Create .mcp.json in the project root:

{
  "mcpServers": {
    "arqenne": {
      "command": "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp"
    }
  }
}

For all projects (user-level):

claude mcp add --scope user arqenne /Applications/Arqenne.app/Contents/MacOS/arqenne-mcp

After either approach, restart Claude Code. Verify the connection:

claude mcp list

You should see arqenne listed.

Speak responses with a Stop hook

A common pattern: have Claude Code speak its response after every turn. You can wire MCP into a Stop hook for spoken responses — see the Claude Code hooks docs for the current hook variable names and event shapes.

Cursor

Cursor's MCP config lives in its settings.

1. Open Cursor settings (Cmd+,)
2. Search for "MCP"
3. Add a new MCP server with these values:
   • Name: Arqenne
   • Command: /Applications/Arqenne.app/Contents/MacOS/arqenne-mcp
   • Arguments: (leave empty)

Or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "arqenne": {
      "command": "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp"
    }
  }
}

Restart Cursor. The MCP indicator in Cursor's chat will show Arqenne as connected.

OpenCode

OpenCode reads MCP config from its config.json — see the OpenCode docs for the current path on your system. On most setups it lives at ~/.config/opencode/config.json. Create the file if it doesn't exist:

{
  "mcpServers": {
    "arqenne": {
      "command": "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp"
    }
  }
}

Restart OpenCode. Verify by asking:

"List the MCP tools available."

Arqenne's three tools should appear.

Verifying the setup

Before plugging Arqenne into any agent, you can test that the bridge works using the MCP Inspector — Anthropic's official testing tool:

npx @modelcontextprotocol/inspector /Applications/Arqenne.app/Contents/MacOS/arqenne-mcp

This opens a local web UI showing all three tools. Click get_health and run it — you should see your account tier in the response. If get_health works here but your agent can't see Arqenne, the issue is in the agent's config, not in Arqenne.

If get_health doesn't work, see troubleshooting.

Environment variables

Two environment variables let you customize how Arqenne handles audio output. Add them to the env block of your MCP server config (see Claude Desktop section for an example).

ARQENNE_MCP_OUTPUT_DIR

The directory where generated audio files are saved.

• Default: Arqenne's cache directory (~/Library/Caches/com.arqenne.studio/tts_mcp/). macOS may purge this directory under disk pressure.
• Common override: ~/Desktop (visible, persistent)
• Other examples: ~/Audio/Arqenne, /Volumes/External/tts

"env": {
  "ARQENNE_MCP_OUTPUT_DIR": "~/Desktop"
}

~/... expands against your home directory. Bare relative paths (e.g. Audio/Arqenne) also resolve against $HOME, not the agent's working directory. If the directory doesn't exist, Arqenne creates it.

ARQENNE_MCP_OUTPUT_MODE

How generated audio is delivered to the agent.

Today only files is honored. Setting resources or both falls back to files mode with a warning.

"env": {
  "ARQENNE_MCP_OUTPUT_MODE": "files"
}

Keeping audio files

By default, generated audio goes to Arqenne's cache directory (~/Library/Caches/com.arqenne.studio/tts_mcp/). macOS purges that directory under disk pressure, which is right for most cases — agents speak the line, audio plays, no one needs the file later.

If you want to keep audio files (e.g., you're using Arqenne as part of a recording workflow):

"env": {
  "ARQENNE_MCP_OUTPUT_DIR": "~/Desktop"
}

Or any directory you prefer. Files there persist until you delete them.

Troubleshooting

"Arqenne Studio is not running"

The most common error. Open Arqenne from /Applications (or use open -a Arqenne from the terminal). Once it's running, your agent can connect.

If Arqenne is running and you still see this error, restart Arqenne. The MCP socket may have been left in a bad state from a previous session.

"Sign in to Arqenne Studio to use TTS"

You're signed out. Open Arqenne and sign in. The MCP server inherits your session — there's no separate login.

"Voice X is not available on your tier"

Free accounts have access to one voice — Morpheus (am_michael). Either ask your agent to use that voice, or upgrade to Starter or higher for all 29 voices.

Agent can't see Arqenne even though config looks right

1. Verify the path in your config is correct: /Applications/Arqenne.app/Contents/MacOS/arqenne-mcp should exist. Run ls -l "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp" to check.
2. If you're running Arqenne from the DMG (not from /Applications), the path won't match. Drag Arqenne to /Applications first.
3. Restart your agent after editing the config.
4. Test the binary directly with the MCP Inspector (see verifying the setup). If it works there, the issue is in the agent's config.

"The TTS engine is still loading"

Arqenne loads the TTS model on app startup. On a fresh launch this takes a few seconds. Your agent can re-try the call after a moment, or call get_health to check the engine_ready field before retrying.

Audio file isn't being created

Check that the directory in ARQENNE_MCP_OUTPUT_DIR exists and is writable. Arqenne tries to create it on first write, but if the parent path is locked or read-only, generation will fail.

Generic MCP configuration

If your agent supports MCP and isn't covered above, the configuration is the same shape:

• Command to run: /Applications/Arqenne.app/Contents/MacOS/arqenne-mcp
• Arguments: none
• Transport: stdio (the default for local MCP servers)
• Optional environment variables: ARQENNE_MCP_OUTPUT_DIR, ARQENNE_MCP_OUTPUT_MODE

Any agent that can spawn a binary and speak MCP over its stdin/stdout will work.

Pricing and limits

The MCP server is included with every Arqenne plan, including Free.

No per-call charges, no monthly credit caps, no surprise lockouts on any tier — audio is generated locally on your Mac, so the marginal cost is zero. Concurrency caps apply per Arqenne process; in practice you'll only hit them if your agent fires many parallel text_to_speech calls at once.

Voice cloning and Enhanced TTS aren't yet exposed through the MCP server — they remain available in the Arqenne app, and a future MCP release will surface them.

See full pricing →

Privacy

• Audio is generated locally. Your text never leaves your Mac during synthesis.
• No third-party services are called for TTS generation. Arqenne uses on-device models.
• Authentication uses Arqenne's existing account system; the MCP server inherits your signed-in session via filesystem permissions on a Unix socket.
• Your generated audio files are stored where you configure (ARQENNE_MCP_OUTPUT_DIR); we never collect them.
• Telemetry: if you've opted into Arqenne's crash reporting, MCP errors are reported alongside other app errors. Tool call content (the text you synthesize) is never reported. You can opt out in Arqenne's settings.