ableton-live-mcp: Instructions file for Codex

Ableton Live MCP Setup

MCP initialize instructions are intentionally compact; when they point to AGENTS.md, use this file for repo-specific Ableton, Max for Live, reliability, validation, and recovery guidance.

1. From this repository checkout, install the package into the agent environment:

   python -m pip install -e ".[dev]"
   

   The dev extra intentionally includes the Ableton-only visual capture dependencies used for M4L UI verification. For a lean runtime install that still needs screenshots, install the visual extra too.

2. Install the Ableton Remote Script:

   ableton-live-mcp-install-remote-script
   

3. Start Ableton Live, open Settings, and select Ableton_Live_MCP as a Control Surface.

4. Register the MCP server in your MCP client:

   {
     "mcpServers": {
       "ableton": {
         "command": "ableton-live-mcp"
       }
     }
   }
   

5. Validate the connection while Ableton is running:

   ableton-live-mcp-validate
   

   For a deliberate quick health probe against a stressed or possibly wedged set, use a bounded strict check such as:

   ableton-live-mcp-validate --timeout 3 --strict-timeout --allow-stale-remote-script
   

The Remote Script binds only to 127.0.0.1. If Ableton was already open when the script was installed, restart Ableton or reload the Control Surface.

After changing files under Ableton_Live_MCP/, reinstall the Remote Script and reload the Control Surface before treating Live validation as current. The running Control Surface does not pick up repository edits automatically; stale installed scripts can make bridge behavior, timeout handling, or generated-device triggers look broken after the source has been fixed. ableton-live-mcp-validate checks the installed Remote Script files plus the running live_ping runtime version, loaded-code fingerprint, and script hash; do not ignore a stale/missing runtime marker, code fingerprint, or hash unless deliberately validating old code.

Reloading the Control Surface or restarting Live can interrupt playback and the user's current set. Ask for explicit user authorization before doing either, then rerun ableton-live-mcp-validate and require runtime_current: true and live_mutations_safe: true before claiming current-runtime e2e validation or sending generated-device mutations.

If a known MCP tool appears in the active client with an obviously stale or no-argument schema, such as live_agent_audio_tap rejecting {"command": "stop"} or live_transport rejecting {"action": "play"}, stop using that client schema. Run ableton-live-mcp-validate and reload/restart the MCP server or MCP client session so tools/list is refreshed; do not keep trying calls that the active schema cannot represent.

Save, crash-report, and "Recover last Live Set" dialogs are common after forced recovery. Treat any Live modal as a hard blocker for MCP mutations: inspect the Ableton Live UI, resolve only the Ableton dialog, then rerun validation before continuing. If the user has authorized a fresh disposable validation set and the open set contains only generated test material, choose the non-saving/non-recovery path such as "Don't Save" or "No"; if user work might be present, stop and ask before dismissing it.

If validation fails with live_error, preserve live_failure_type, runtime_mismatch, and runtime_next_action in the investigation notes. live_main_thread_timeout often means a modal dialog or heavy UI/indexing work is blocking Live; inspect the UI before sending more mutations. bridge_not_listening means the Control Surface bridge is not accepting localhost connections. Installed files may still be current in either case, so do not infer current-runtime behavior from source tests alone.

When the bridge socket still responds but Live's main thread does not execute scheduled work, validation reports live_failure_type: "live_main_thread_hung" and may include bridge_status.server_thread_responsive: true. Treat this as a real Live hang, not a retryable command failure: stop sending Live API mutations, avoid piling up queued callbacks, and ask for explicit authorization before reloading the Control Surface or restarting Live. Use live_bridge_status only for no-Live-API socket-thread diagnostics while the set is wedged.