> For the complete documentation index, see [llms.txt](https://docs.acestudio.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acestudio.ai/ai-agent/external-agent-access.md). # External Agent Access Connect ACE Studio to AI assistants and agents through MCP and CLI. {% hint style="warning" %} #### Experimental Status External agent access in ACE Studio is currently experimental and under active development. **Please note:** * **Breaking changes:** Tool commands, formats, and conventions may change between updates. * **Work in progress:** Not all ACE Studio features are fully accessible to agents yet. * **Rough edges:** You may encounter bugs, unexpected edge cases, or unnatural behavior as we refine agent interactions. If you run into issues or have suggestions, please let us know at [**support@acestudio.ai**](mailto:support@acestudio.ai). {% endhint %} Connect AI assistants and agents (such as Claude, ChatGPT, OpenClaw, or Hermes Agent) directly to ACE Studio to understand and edit your music projects in real time. ### What Your Agent Can Do Once connected, an agent can inspect and edit your project across most of what ACE Studio does: * **Arrangement & Composition** — Manage tracks, clips, notes, lyrics, chords, and the playhead. * **Vocals & Instruments** — Adjust voice models, sound sources, multi-singer choir layers, and vocal parameters (pitch, breath, tension), and load third-party instrument plug-ins. * **Timing & Structure** — Set BPM, time signatures, loop markers, and transport. * **Production & AI Tools** — Trigger Add a Layer, Vocal to MIDI, Stem Splitter, Music Enhancer, and load FX chains or presets. * **Session Control & Delivery** — Spin up and save projects, import audio and MIDI, and export full mixdowns, individual stems, video, and more. Just describe what you want in plain language, and your assistant will inspect the project and make the changes. *** ### Connecting Your Assistant Choose the setup method that fits your workflow: #### Path A: Let Your AI Agent Configure It for You If you use an agent with local environment or computer access (such as **Claude Code**, **Codex**, **OpenClaw**, or **Hermes Agent**), it can configure itself automatically. {% hint style="info" %} This path requires an agent running on the same computer as ACE Studio with permissions to execute commands and edit its configuration files. {% endhint %} The quickest way is from inside ACE Studio. Click the **agent icon** in the lower-right corner of the window, pick **ChatGPT**, **Claude**, or **Other Agents**, and follow the three steps shown: open your agent, copy the connection prompt with the **Copy** button and send it, then start creating with one of the example prompts. The same connection prompt is reproduced here. Copy and paste it into your agent and hit Send: ``` Connect to ACE Studio for me using acestudio-cli or MCP. Default locations: - macOS MCP: "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server" - macOS CLI: "/Applications/ACE Studio.app/Contents/Helpers/acestudio-cli" - Windows MCP: "C:\Program Files\ACE Studio\ace-mcp-server.exe" - Windows CLI: "C:\Program Files\ACE Studio\acestudio-cli.exe" Try using the CLI first and remember the tool path in your instructions/memory. If CLI access is restricted by sandboxing or permissions, register the MCP server (under the name "ace-studio" with user/global scope). If not found at the default location, ask me for the path from ACE Studio's Preferences → General → External Agent Access. Then, install skills/agent plugin from ACE Studio's official repo at https://github.com/BeatMagic/acestudio_agent_plugin. It is important to have this installed and available to you since it provides know-how you will need when interacting with ACE Studio. If you need more context on ACE Studio and its agent integration, refer to the documentation at https://docs.acestudio.ai/llms.txt. If your harness cannot configure itself or execute local commands, please guide me through the manual setup steps for your platform. ``` *** #### Path B: Configure Manually in Your Harness If your agent harness cannot configure itself automatically, you will need to add ACE Studio's MCP server to its configuration manually. [The Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open standard that connects AI assistants to external applications. ACE Studio runs as a local STDIO server, allowing any MCP-compatible client to connect directly using the launch command. **Configure via Terminal** If you use Claude or Codex and prefer configuring directly from your terminal: {% tabs %} {% tab title="Claude" %} Run in your terminal: **macOS:** ```bash claude mcp add --scope user ace-studio -- "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server" ``` **Windows:** ```cmd claude mcp add --scope user ace-studio -- "C:\Program Files\ACE Studio\ace-mcp-server.exe" ``` {% endtab %} {% tab title="Codex" %} Run in your terminal: **macOS:** ```bash codex mcp add ace-studio -- "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server" ``` **Windows:** ```cmd codex mcp add ace-studio -- "C:\Program Files\ACE Studio\ace-mcp-server.exe" ``` {% endtab %} {% endtabs %} **Desktop Chat Apps** For full step-by-step guides with configuration walkthroughs: * [**Claude Desktop & Cowork**](/ai-agent/external-agent-access/claude-desktop-and-cowork.md) — Step-by-step configuration for Claude Desktop with configuration file walkthroughs. * [**ChatGPT for desktop**](/ai-agent/external-agent-access/chatgpt-for-desktop.md) — Step-by-step setup for ChatGPT Work and Codex modes. **Other Harnesses & IDEs (VS Code, Cursor, Custom Clients)** Most MCP clients and IDEs ask for the same configuration parameters: * **Transport type:** STDIO (sometimes labeled "Local" or "Command") * **Command:** The launch command copied from ACE Studio * **Arguments / Environment:** None For harnesses configured via JSON files: {% tabs %} {% tab title="Standard MCP Config (Cursor, etc.)" %} Used by Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`) and most standard MCP harnesses: ```json { "mcpServers": { "ace-studio": { "command": "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server" } } } ``` {% endtab %} {% tab title="VS Code (GitHub Copilot)" %} Add to `.vscode/mcp.json` in your project workspace: ```json { "servers": { "ace-studio": { "type": "stdio", "command": "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server" } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Windows Path Escaping in JSON:** If you manually write Windows paths using backslashes in JSON files, escape each backslash as a double backslash (`\\`), or use forward slashes (`/`). {% endhint %} {% hint style="warning" %} **Browser-based AI Assistants:**\ ACE Studio's MCP server runs locally on your machine over STDIO. Web-only interfaces (such as ChatGPT or Claude in a web browser) cannot connect to local STDIO servers directly. Use their respective desktop applications or terminal clients instead. {% endhint %} {% hint style="info" %} **Custom Installation Paths:** If you installed ACE Studio to a custom directory, open **Preferences → General → External Agent Access** in ACE Studio: * Click **Copy command** next to **MCP Server (stdio)** for the MCP server path. * Click **Copy** next to **acestudio-cli binary path** for the CLI path. {% endhint %} *** ### Verifying the Connection Make sure ACE Studio is open and running, then ask your assistant: ``` Please check the current ACE Studio project information ``` If your assistant responds with your project's tempo, key signature, and track list, your setup is complete and ready. *** ### Creative Prompt Examples Here are some real-world examples of how you can collaborate with your AI assistant in ACE Studio: #### 1. Vocal Production & Multi-Singer Harmonies ``` Turn on Choir mode on the lead vocal track (Track 1), add two backing singer voices, widen the stereo spread, and lower their level by -3 dB for a lush background harmony. ``` #### 2. Custom Voice Blending ``` Create a custom blended voice on Track 2: mix 70% of a warm acoustic pop seed with 30% of an airy, breathy voice seed, then name the blend "Velvet Air". ``` #### 3. Chords & Song Drafting ``` In bars 1–8 of the chord track, insert a Neo-Soul progression: Ebmaj9 — G7#9 — Cm9 — F13 (2 bars each). Then add a Rhodes piano track and a groovy bassline following the root notes. ``` #### 4. AI Accompaniment & Audio Extraction ``` Split the imported audio clip on Track 1 into vocal, drum, bass, and other stems. Then run Vocal to MIDI on the extracted vocal stem to create an editable Sing track. ``` #### 5. Generative Song Ideas & Layers ``` Listen to the arrangement from bar 9 to 25 and use Add a Layer to generate a matching cinematic string pad accompaniment layer at the current project tempo. ``` #### 6. Expressive Vocal Tuning & Dynamics ``` Inspect the chorus vocal notes on Track 1: smooth out the pitch transitions, increase breathiness on the entry notes, and add a subtle vibrato curve on sustained notes. ``` #### 7. FX Chains & Stem Delivery ``` Load a vintage vocal compressor and warm plate reverb onto the lead vocal FX chain, then export all individual tracks as 24-bit 48kHz WAV stems to a "Stems" folder on my Desktop. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.acestudio.ai/ai-agent/external-agent-access.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.