Use Arqenne with your AI agent

Arqenne ships with a built-in Model Context Protocol (MCP) server, on macOS and Linux. Once you connect your AI agent to it, the agent can work in your Arqenne projects — read and write your files, narrate chapters, build storyboards — and generate speech directly, with no API keys, no per-call charges and no monthly credit caps. Speech is generated locally on your computer by Arqenne's text-to-speech engine.

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

• Claude Desktop (macOS)
• 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.
   • macOS: 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.
   • Linux: installed from Arqenne's repository or a .deb (see Arqenne on Linux).
2. Signed in to Arqenne. Open the app and sign in with your account.
3. Arqenne running, with its agent connection switched on. The MCP server only works while Arqenne is running, and in this release the connection is off unless Arqenne is started with STUDIO_MCP_ENABLED=1. Quit Arqenne, then start it from a terminal:

macOS:

STUDIO_MCP_ENABLED=1 /Applications/Arqenne.app/Contents/MacOS/Arqenne

Linux:

STUDIO_MCP_ENABLED=1 arqenne

Your agent must run on the same computer as Arqenne; the two talk over a local socket.

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.

Where the server lives

Every configuration below points your agent at the arqenne-mcp program that comes with Arqenne:

The examples use the macOS path. On Linux, use /usr/bin/arqenne-mcp wherever you see it.

What your agent can do

Once connected, the agent can drive the whole creation loop — 24 tools across six areas, plus the init prompt that starts a session (next section):

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."

"Narrate chapter three of my novel with the narrator voice."

Free accounts use one voice — Morpheus (am_michael). Paid accounts have access to all 28 built-in voices.

Start every session with init

Arqenne ships a prompt called init. Run it once at the start of each session, before you ask for anything else. It does three things:

1. Puts the Arqenne guide in front of your agent — the rules for working in your projects without losing work: how to wait for narration and image jobs, how paragraph ids survive edits, when to ask before deleting. The guide is also available as the resource arqenne://guide/best-practices.
2. Checks the connection — whether Arqenne is running and signed in, your plan, whether the speech engine is ready, and which features your version offers.
3. Lists your projects and asks what you want to make.

It changes nothing. If Arqenne isn't running or you're signed out, it tells you and stops.

How to run it:

Claude Desktop

Claude Desktop is available for macOS; there is no official Linux version. On Linux, use Claude Code, Cursor or OpenCode.

Edit your Claude Desktop config:

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 tools are listed (24 of them), then start your first chat with init.

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 folder, which the system may clear (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 (on Linux, use /usr/bin/arqenne-mcp as the command):

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

For all projects (user-level):

macOS:

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

Linux:

claude mcp add --scope user arqenne /usr/bin/arqenne-mcp

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

claude mcp list

You should see arqenne listed. Start each session with /mcp__arqenne__init (see Start every session with init).

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+, on macOS, Ctrl+, on Linux)
2. Search for "MCP"
3. Add a new MCP server with these values:
   • Name: Arqenne
   • Command: /Applications/Arqenne.app/Contents/MacOS/arqenne-mcp on macOS, /usr/bin/arqenne-mcp on Linux
   • 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 servers from the mcp section of its config file, ~/.config/opencode/opencode.json (see the OpenCode docs if your install keeps it elsewhere). Create the file if it doesn't exist. Note that command is a list:

{
  "mcp": {
    "arqenne": {
      "type": "local",
      "command": ["/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp"]
    }
  }
}

On Linux, use ["/usr/bin/arqenne-mcp"] as the command.

Restart OpenCode. Verify by asking:

"List the MCP tools available."

Arqenne's 24 tools should appear. Then start with init.

Verifying the setup

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

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

On Linux:

npx @modelcontextprotocol/inspector /usr/bin/arqenne-mcp

This opens a local web UI showing all 24 tools, one resource (the Arqenne guide) and one prompt (init). 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 the Claude Desktop section for an example).

ARQENNE_MCP_OUTPUT_DIR

The directory where generated audio files are saved.

• Default: Arqenne's cache folder — ~/Library/Caches/com.arqenne.studio/tts_mcp/ on macOS, ~/.cache/com.arqenne.studio/tts_mcp/ on Linux. The system or a cleanup tool may clear it.
• Common override: ~/Desktop (visible, persistent)
• Other examples: ~/Audio/Arqenne, or a folder on an external drive

"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 folder (~/Library/Caches/com.arqenne.studio/tts_mcp/ on macOS, ~/.cache/com.arqenne.studio/tts_mcp/ on Linux). macOS purges that folder under disk pressure, and cleanup tools on Linux may empty it, 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 (open -a Arqenne on macOS, arqenne on Linux). Once it's running, your agent can connect.

If Arqenne is running and you still see this error, the agent connection is probably switched off: quit Arqenne and start it with STUDIO_MCP_ENABLED=1, as shown in Before you start. If it still fails, restart Arqenne — the connection may have been left in a bad state by a previous session.

"Sign in to Arqenne Studio, then try again"

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 28 built-in voices.

Agent can't see Arqenne even though config looks right

1. Verify the path in your config exists. On macOS run ls -l "/Applications/Arqenne.app/Contents/MacOS/arqenne-mcp"; on Linux run ls -l /usr/bin/arqenne-mcp.
2. On macOS, 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 program 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 text-to-speech model the first time it's used, not at startup, so the first call after launch can take a few seconds. Your agent can retry after a moment, or call get_health and wait for engine_ready before retrying. The speech model must also be downloaded in Settings › Models.

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 on macOS, /usr/bin/arqenne-mcp on Linux
• 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 program and speak MCP over its stdin/stdout will work.

Pricing and limits

The MCP server is included with every Arqenne plan, including Free. These limits apply to text_to_speech:

No per-call charges, no monthly credit caps, no surprise lockouts on any tier — speech is generated locally on your computer, 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.

text_to_speech speaks with the built-in Standard voices. narrate_file narrates with your project's speakers, so on Creator and Studio a chapter can be narrated in a cloned or fine-tuned voice. Images rendered in Arqenne Cloud draw on your plan's included cloud usage, exactly as they do in the app; images rendered on your own ComfyUI server don't.

See full pricing →

Privacy

• Speech is generated locally. Your text never leaves your computer during synthesis.
• No third-party services are called for text-to-speech. Arqenne uses on-device models. Image generation is the exception: prompts go to Arqenne Cloud or to the ComfyUI server you configured, as they do in the app.
• Authentication uses Arqenne's existing account system; the MCP server inherits your signed-in session via filesystem permissions on a local socket.
• Your generated audio files are stored where you configure (ARQENNE_MCP_OUTPUT_DIR); we never collect them.
• Crash reporting: Arqenne's crash reporting is on by default and includes MCP errors alongside other app errors. Tool call content (the text you synthesize) is never reported. You can turn crash reporting off in Arqenne's settings.