Protocol and lifecycle
On this page
The extension exposes a local, line-oriented diagnostic/control endpoint on
127.0.0.1:8765 while the controller is running. Each request is one UTF-8
line and each response is one JSON line. This is the native bridge contract;
the MCP server maps its tools onto this surface and adds offline/session
management.
A copied extension file, a listening socket, or a historical response does not
prove that the intended code is loaded. Save work, restart Bitwig after a
replacement, then check protocol: 4, host identity, and capability flags.
Do not use a throwaway native attach probe as an activation test.
Common commands
| Command | Result |
|---|---|
ping |
Bridge liveness response. |
capabilities |
Protocol 4, host version/platform, public host flags, and nested Grid flags. |
state |
Selected-device exposed controls and values. |
inspect |
Selected-device inspection. |
history |
Project name/modified and application undo/redo state. |
set INDEX VALUE |
Set one exposed selected-device control. |
batch ... |
Apply a validated batch of exposed-control writes. |
tracks |
Read the current track bank. |
track INDEX |
Select a track by bank index. |
track-first, track-next, track-previous |
Navigate track selection. |
device-first, device-primary, device-editor |
Navigate the device selection. |
next, previous, parent |
Navigate relative device selection. |
actions [QUERY...] |
List native application actions, optionally filtered. |
action ACTION_ID |
Invoke a reviewed native application action. |
undo, redo |
Request the host application's global undo/redo. |
device-catalog [QUERY...] |
Search the native device package catalog. |
Unknown commands and invalid values return an error JSON response. Host-thread and document-thread work is scheduled by the extension; a successful response is not a guarantee that a public host write has completed.
Capability response
capabilities includes "protocol":4, host version/platform, public flags
for song state, transport, track bank, mix, device inventory/insertion,
application actions, undo/redo, and graph availability. The nested
grid_graph object reports private-runtime compatibility and capabilities for
inspection, catalogs, insertion, parameters, connections, revision guards,
display-value resolution, and native undo.
The native Grid graph is private and version/signature checked. It can be unavailable for an unsupported Bitwig version or an unsupported selected format while public selected-device controls still work. Never infer graph availability from the bridge package version or from a historical catalog.
Public host commands
These commands are also exposed as MCP tools. Arguments below are positional and are shown without shell quoting.
| Command | Arguments | Notes |
|---|---|---|
song-state |
none | Reads project token, transport, recording, tracks, and capabilities. |
song-transport |
PROJECT_TOKEN OPERATION [VALUE...] |
Operations are play, continue, restart, stop, seek POSITION_BEATS, tempo BPM, meter NUMERATOR/DENOMINATOR, and loop ENABLED [START_BEATS DURATION_BEATS]. |
track-state |
PROJECT_TOKEN INDEX MUTED ARMED |
MUTED and ARMED are true, false, or keep; at least one must change. |
mix-state |
[TRACK_INDEX] |
Reads mix controls and mix revision. |
mix-set |
PROJECT_TOKEN TRACK_INDEX MIX_REVISION CONTROL_ID EXPECTED VALUE |
Normalized values are 0..1 and the expected current value is guarded. |
devices |
none | Reads the selected-device bank and selection token. |
device-remove |
SELECTION_TOKEN |
Removes the selected device. |
device-insert |
POSITION DEVICE_UUID SELECTION_TOKEN |
Position is before, after, start, end, or replace. |
Song transport accepts seek positions 0..24576 beats, tempo 40..220 BPM, and meter denominators 4 or 8 with numerators 2..12. Loop ranges must be bounded; changing a loop range requires stopped transport. Recording and unsupported automated targets are rejected. Track indices are 0..63.
Public host mutation responses use a submitted/immediate-proxy contract. A
response can report the request and an observed value while
"verified":false; call song-state, mix-state, or devices again and
compare the new observation before treating the operation as complete.
Grid graph reads and catalogs
| Command | Arguments | Result |
|---|---|---|
graph-capabilities |
none | Native graph/runtime capability flags. |
graph-state |
none | Current graph ID, revision, modules, parameters, ports, and connections. |
graph-catalog [QUERY...] |
optional query | Current insertable module catalog. |
graph-modulators [QUERY...] |
optional query | Current semantic modulator catalog. |
graph-host-modulators |
none | Host-provided modulation sources. |
graph-resolve |
REVISION MODULE_ID PARAMETER_ID DISPLAY_VALUE_B64 |
Read-only display-value resolution through the current parameter definition. |
graph-resolve requires a fresh graph revision and a base64url-encoded UTF-8
display value. The decoded value is 1..256 characters and must match the
current native enum label or accepted display notation. It returns a resolved
native value; it does not write the parameter.
Revision-guarded graph edits
All graph edits use the form:
graph-edit REVISION OPERATION ...
The supported operation forms are:
graph-edit REVISION insert PACKAGE_UUID X Y
graph-edit REVISION insert-modulator PACKAGE_UUID X Y
graph-edit REVISION set MODULE_ID PARAMETER_ID_B64 VALUE
graph-edit REVISION set-modulator MODULE_ID PARAMETER_ID_B64 VALUE
graph-edit REVISION connect SOURCE_MODULE_ID SOURCE_PORT TARGET_MODULE_ID TARGET_PORT
graph-edit REVISION connect-modulator SOURCE_MODULE_ID SOURCE_PORT TARGET_MODULE_ID TARGET_PORT
graph-edit REVISION disconnect TARGET_MODULE_ID TARGET_PORT
graph-edit REVISION move MODULE_ID X Y
graph-edit REVISION clear
Coordinates are bounded to -4096..4096. Parameter IDs are base64url encoded;
module IDs and ports must be exact identities from the fresh graph-state.
The native implementation checks the expected revision at submission and
performs the operation on the document thread. A stale revision rejects the
call. Read graph-state after every mutation.
clear is destructive. Native undo and redo are global application
operations, not a private transaction for one graph edit. Preserve a project
copy before destructive work.
Mapping to MCP and explicit absences
The MCP host tools map to the host commands as follows:
grid_song_state→song-state;grid_song_transport→song-transport;grid_set_track_state→track-state;grid_inspect_mix/grid_set_mix→mix-state/mix-set;grid_list_devices/grid_insert_device/grid_remove_device→devices/device-insert/device-remove;grid_list_actions/grid_invoke_action→actions/action; andgrid_move_module/grid_clear_graph/grid_resolve_parameter_value→ revision-guardedgraph-edit move/graph-edit clear/graph-resolve.
The native protocol does not implement arranger note/clip/automation editing, MIDI import or voice realization, live capture, audio rendering/export, or project save/new/load/delivery. MCP offline MIDI and audio tools do not fill those native gaps: they export/analyze files without importing, rendering, or saving a Bitwig project.