Integration overview

This section is for MCP clients, scripts, and orchestration layers. It defines the supported transport, startup contract, tool entry points, and safety gates. For producer-facing procedures, use the Producer guide.

Supported integration path

MCP client
        │ MCP stdio
        ▼
Python adapter: offline compiler, review sessions, optional Nitro evidence
        │ UTF-8 command line → JSON response over 127.0.0.1:8765
        ▼
Bitwig Grid Bridge extension
        │ serialized host-thread calls
        ▼
Bitwig Controller API 25 (minimum, host and compile API)

The Java extension is authoritative for live Bitwig state. Direct scripts may use the same line-command/JSON-response endpoint without MCP. The adapter owns offline song composition, artifact review and incremental workflow state; it never reconstructs live topology from stale or static evidence. Private bindings are exact Bitwig 6.1.1 and reject unknown runtimes.

The former OSC compatibility transport is deprecated, disabled by default, and not started by the MCP adapter. Existing direct OSC modules remain only for legacy callers; new integrations must use the Grid Bridge endpoint.

Start the adapter

From a source checkout or release bundle:

uv sync --frozen
BITWIG_MCP_GRID_BRIDGE_ENABLED=true uv run bitwig-mcp

Example MCP client configuration:

{
  "mcpServers": {
    "bitwig-grid-bridge": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/bitwig-grid-bridge", "bitwig-mcp"],
      "cwd": "/absolute/path/to/bitwig-grid-bridge",
      "env": {
        "BITWIG_MCP_GRID_BRIDGE_ENABLED": "true",
        "BITWIG_MCP_GRID_BRIDGE_HOST": "127.0.0.1",
        "BITWIG_MCP_GRID_BRIDGE_PORT": "8765"
      }
    }
  }
}

The adapter keeps stdout reserved for MCP messages. Capture logs through the client's stderr facility.

Startup contract

1. The adapter attempts the configured loopback bridge connection.
2. An unavailable extension does not prevent stdio startup: offline song composition/export and local Nitro discovery remain usable.
3. Live tools require the enabled extension and return unavailable-service errors rather than inferred state. Reconnect/observe before a live operation.
4. No UDP socket or legacy compatibility listener is required.
5. Readiness is surface-specific: MCP startup, live capabilities and successful Nitro decryption are separate observations.

After copying an extension, wait for asynchronous reload and read-only capability/readiness responses; refresh identities before mutation and never replay a timed-out write. Public state/inspect may work with null native selection tokens, but those tokens cannot authorize device insertion/removal.

First calls

For live graph/device work, begin with:

get_grid_capabilities
get_selected_device_state

If the capability response reports graph_available: false, do not call graph inspection or mutation tools. Selected-device inspection and exposed-control operations may still be available.

For device edits, inspect grid_list_devices (16-sibling window, check window_complete), then pass its fresh selection_token as required expected_selection_token to grid_insert_device or grid_remove_device. Insertion supports before/after/start/end/replace; authorization is required. Destructive grid_clear_graph instead requires a reviewed graph expected_revision and authorization.

For offline music, use grid_track_plan or grid_track_start, review/revise and export. For native delivery/loop control/transport/track state, begin with grid_song_state and its exact project token. Use grid_inspect_arranger per role, disable enabled loops for linear scores with grid_set_clip_loop, then re-inspect flags, source counts/spans and clip geometry before listening. For static installed DSP evidence, begin with grid_nitro_status and search_grid_nitro; readable catalog names do not prove decryption or live graph access.

Reference pages

• Workflow playbook: safe end-to-end tool sequences and completion evidence.
• Tool reference: MCP names, arguments, and mutation classes.
• Data and safety: snapshots, identities, ranges, and revisions.
• Protocol and lifecycle: transport and recovery invariants.
• Automation scripts: direct bridge use without MCP.