Tool reference

Tool names and JSON argument schemas are the MCP contract. Required fields are listed below; “optional” does not mean arbitrary extra fields are accepted. The server's advertised schemas are authoritative. See the Workflow playbook for ordering and Data and safety for response identities and evidence limits.

Package/extension 0.2.0 exposes 90 MCP tools. Native operations use exact private Bitwig Studio 6.1.1 bindings; the public Controller API minimum and compile dependency are 25. These numbers describe different interfaces. After an upgrade, reconnect the MCP client to refresh its advertised catalog and schemas; do not reuse a cached catalog as proof of extension readiness.

Graph/device writes, native note/automation/voice edits, shaping apply, patch steps, song import/save, clip loop control, engine/transport, track mute/arm and host actions require confirm: true, or cooperative: true only under explicit cooperative authorization. Selection, snapshot restore, exposed-control batch writes and undo/redo do not have that boolean gate; they still change state and need authorization at the orchestration layer.

Read and planning tools

Tool	Arguments	Result
get_grid_capabilities	{}	Host/extension/protocol versions, selected-device flags and nested grid_graph capabilities
get_selected_device_state	{}	Selected device, exposed parameters and optional graph
get_grid_graph	{}	Live graph identity/revision, modules, ports, connections, coordinates and native parameters
get_grid_host_modulators	{}	Host modulation sources for the selected Grid
search_grid_modules	query string	Installed module catalog
search_grid_modulators	query string	Semantic modulation catalog
search_bitwig_devices	Optional query string	Installed device names and exact device_id UUIDs
grid_list_devices	{}	Selected device's 16-sibling window, native identities, selection_token and window_complete; not a recursive chain inventory
grid_list_tracks	{}	Flat bank indexes, including hidden group children, FX and master
grid_list_actions	Optional query string	Exact currently exposed host action IDs
grid_analyze	Optional role string, 1–512 characters	Evidence-linked topology hypotheses and uncertainty, not listening proof
grid_resolve_parameter_value	module_id, parameter_id, display_value string, 1–64 characters	Native continuous value and reviewed revision; no mutation
grid_live_set_plan	brief; optional style, tempo 80–200, scenes 3–12, density/motion/agency 0–1	Live-set roles, scenes, macros and bounded routes; no clips created
grid_list_live_set_styles	{}	Live-set style vocabulary
grid_soundscape_plan	brief; optional style, density/motion/contrast/temperature 0–1	Generic Grid recipe, not an applied graph
grid_list_soundscape_styles	{}	Generic soundscape vocabulary
grid_list_style_presets	{}	Authored shaping profiles and behavioral principles

Catalog UUIDs are not live module instance IDs. Parameter IDs are exact live strings, including punctuation/spaces; MCP callers do not base64-encode them. For musical-unit resolution, pass a display such as 65 ms compatible with the live native unit, then inspect value, current_value, current_display, display_unit and revision. Write the resolved value separately, guarded by that revision; only post-write read-back establishes the resulting display.

Full-song composition and delivery

grid_track_plan and grid_track_start share the composition arguments below. They can run offline; start additionally owns an immutable reviewed revision. The producer grammar explains brief parsing, aliases, explicit-field conflicts and musical limits.

Argument	Contract
brief	Required string, 1–8192 characters
style	Optional supported live-set/soundscape style or alias; unknown styles reject
tempo	Optional finite number, 40–220 BPM
key / scale	Optional supported pitch/key and scale strings
meter	Optional string, numerator 2–12, denominator 4 or 8
bars	Optional integer, 1–2048; default form needs six phrases, explicit custom forms do not
duration_seconds	Optional positive finite number, at most 1800; duration is tick-quantized
phrase_bars	Optional integer: 2, 4, 8, 16 or 32
density / motion	Optional finite numbers, 0–1
seed	Optional integer, 0–4294967295
negative_constraints	Optional array, at most 32 supported exclusions
intent	Bounded independent rhythm, timbre, articulation, arrangement and mix objects
source_policy	Native-only mode and native procedural dependency categories; prohibited sources reject
sections	Optional 1–128 contiguous section specifications; exact bars or seconds, stable IDs, energy/activity/phrase structure
locks	Target IDs with notes/rhythm/tuning/sound/arrangement aspects; conflicting revisions reject

Composition has no host mutation. grid_track_export writes local artifacts; it is not a read-only filesystem operation. Composition/export do not install instruments or render audio. Bitwig MIDI import can supply default Organ instruments; inspect and replace those explicitly rather than stacking voices.

Tool	Required arguments	Optional arguments / result
grid_track_plan	brief	Composition fields above; returns bitwig-track/2 plan without a session
grid_track_start	brief	Same fields; returns session_id, 64-hex revision, plan and delivery state
grid_track_revise	session_id, revision, scope	Optional exact role/section/phrase target, flat changes, deliberate regenerate; returns semantic diff, preserves unrelated/locked material, invalidates old export authority
grid_track_status	session_id	Current review and exports; no recompile
grid_track_export	session_id, revision	Optional output_dir; full-duration type-1 MIDI and bitwig-track-artifact/1 manifest
grid_track_import	session_id, revision, artifact_sha256, expected_project_token	Authorization; workflow-owned current export only, one attempt including ambiguity
grid_track_import_status	receipt_id	Native receipt and inventory observation, never an import retry
grid_song_state	{}	Current project token, target/inventory, transport/recording, audio_engine_active, arranger-loop enabled/start/duration, project_save_pending, meters and capabilities including project_save
grid_song_save	expected_project_token	Authorization; optional nonempty string output_dir; fresh private native project checkpoint, not MIDI export or Collect and Save
grid_inspect_arranger	track_index integer 0–63	One native track's bounded primary clips/source-note summaries; {ok, project_token, track_index, track_name, atomic: false, arranger}
grid_set_clip_loop	track_index integer 0–63, native_clip_id signed 32-bit integer, expected_loop_enabled boolean, enabled boolean, expected_project_token	Authorization; exact observed clip/loop state, no recording; loop flag only
grid_song_transport	operation, expected_project_token	Authorization; play/stop/tempo/meter/seek/loop; tempo 40–220 only for tempo, meter 2–12/4 or 8 only for meter, finite position_beats 0–24576 quarter-note beats only for seek; loop requires boolean enabled, optionally paired start_beats/duration_beats
grid_song_engine	Boolean active, expected_project_token	Authorization; exact stopped non-recording project; may switch away from another project's engine, never starts playback; submitted, not verified
grid_set_track_state	track_index, expected_project_token	Authorization; at least one of boolean muted or armed; index 0–63
grid_track_prepare_role	session_id, revision, role_id, expected_project_token, expected_selection_token	Preview empty-Grid construction or parameter-only refinement of its exact binding; requires_voice_configuration returns separate voice corrections before a patch; no selection, replacement, clearing or playback
grid_track_reconcile_role	session_id, revision, role_id, expected_project_token, expected_selection_token, expected_graph_revision, complete module_bindings alias-to-live-instance map	Read-only recovery of an existing role after reload; any required correction rejects; notes, automation and fresh audio/listening remain separate
grid_track_observe_role	session_id, revision, role_id	Fresh currently selected role readback and bounded arranger evidence; not complete source-note equality or listening
grid_track_preview_automation	session_id, revision, role_id, expected_project_token	Bound, applied native vocal score to reviewed score-time vowel curve previews; resolves native scales and phrase resets; no mutation
grid_track_delivery	session_id, revision	Actual role bindings, capabilities and unmet acceptance gates; does not promote receipts into acceptance
grid_track_listening	session_id, revision, audio_path, audio_sha256, decision, notes, confirm_user_judgment	Explicit human accepted/rejected judgment, optional output_dir; digest-bound durable record, separate from technical/native acceptance
grid_inspect_mix	track_index	Native gain/pan/send identities, normalized values/displays and exact mix_revision
grid_set_mix	track_index, expected_project_token, expected_mix_revision, control_id, expected_normalized, normalized	Authorization; one stopped, non-recording, unautomated native scalar. Values are normalized 0–1, not dB or signed pan

Song revision, artifact digest and project token are distinct 64-lowercase-hex values. Import receipt IDs are 32-lowercase-hex strings. Do not manufacture or reuse them across sessions. The MCP default output root is ~/Music/BitwigGridBridge, configurable with BITWIG_MCP_SONG_OUTPUT_DIR; each export publishes into a unique private subdirectory without overwrite.

Save takes no song session, revision or artifact hash: it checkpoints the current controller-owned project. Its schema allows only expected_project_token (64-lowercase-hex), optional output_dir, and optional boolean confirm/ cooperative; one authorization flag must be true under the policy above. output_dir is a parent root, not a project filename: the adapter allocates a new bitwig-project-* child. Native validation requires that child to be real, absolute, empty and outside existing Bitwig project folders. This avoids existing destinations but is not an atomic general no-clobber guarantee: the host writer can replace files. See checkpoint results and recovery.

Transport loop always requires explicit enabled. Omit both range fields to change only the global arranger-loop flag; supply both finite start_beats ≥0 and duration_beats >0 to set a quarter-note range with end ≤24576. Range edits require stopped transport and work with either enabled state. Loop edits refuse recording and do not change clip loops. The acknowledgment is asynchronous and submitted/unverified: observe arranger_loop_enabled, arranger_loop_start_beats and arranger_loop_duration_beats until the requested state is read back. These fields participate in the project token; refresh it before the next write. Engine activation is also submitted/unverified: re-read audio_engine_active and rediscover output ports before playback or capture.

Native import targets new arranger tracks after the selected native track at beat 0, not clip-launcher slots. Source MIDI retains tempo/meter; a private submitted copy strips those events to avoid the observed import modal, and its hash is reported separately. Use explicit tempo/meter operations with fresh project tokens. queued/submitted and ok: true do not prove arranger notes, instrument assignment or audio; inspect the arranger and listen.

Inspect each imported role with grid_inspect_arranger, checking available, truncation and metadata/count/detail completeness, clip geometry, source counts and spans. Beats are quarter notes. For linear scores, use each clip's observed native_id as native_clip_id and loop_enabled as expected_loop_enabled, with a fresh project token, to set enabled: false. Re-inspect flags, counts and spans afterward. Source notes are not loop-expanded or audible-playback proof; see arranger evidence limits.

Native note refinement

Tool	Required arguments	Result / boundary
grid_inspect_notes	track_index 0–63, observed signed-32-bit native_clip_id	Complete bounded primary source notes, expressions, identities, geometry and content_revision; no selection or edit
grid_track_bind_notes	session_id, song revision, role_id, track_index, native_clip_id	Read-only complete score/source comparison and process/document-local ownership; never binds from names or counts
grid_track_preview_notes	session_id, current song revision, role_id	Minimal insert/update/delete diff against the bound source; separate preview_id and 64-hex preview revision
grid_track_apply_notes	preview_id, preview revision, expected_project_token	Authorization; stopped, non-recording, arranger record disabled; exact content/identity guards, native undo and complete read-back; consumed attempts never replay

Bind the matching score before revising it. The source must be exclusive, complete and compatible with a linear, unmuted, non-looping score. Preview quantization and overlap checks are binding constraints, not permission to rewrite clip geometry. Updates preserve exact note identities, native attributes and expressions; unchanged notes and other clips remain protected. Bindings and previews expire and do not survive reopening or process restart. After undo or external edits, inspect the complete source and reconcile against a matching review; never reuse a stale preview.

Native automation and voice controls

An automation destination uses track_index 0–63, kind (mix or grid) and exact parameter_id. Grid destinations additionally require current device_id and module_id; mix destinations must omit both. Resolve all identities live.

Tool	Required arguments	Result / boundary
grid_automation_inspect	Destination fields above	Complete bounded primary arranger curve, point identities, ownership, base and effective values
grid_automation_normalize	Destination, finite native_value	Native-scale conversion to automation normalization, not a guessed linear map
grid_automation_preview	Destination, expected_project_token, points	Stopped/non-recording preview of 2–8192 {time, normalized, interpolation} points; no playback-time write stream
grid_automation_apply	automation_id, exact integer revision ≥1, expected_project_token	Authorization; stopped/non-recording, exact snapshot/ownership guards, native undo and point/outside-span/base preservation verification
grid_automation_status	automation_id	Retained preview/application receipt, not fresh native observation or replay
grid_voice_state	expected_project_token	Selected native Grid allocation, mono/retrigger/priority and glide; optional glide_ms 0–500 resolves native musical units without mutation
grid_set_voice_parameter	expected_project_token, expected_selection_token, expected_voice_revision, parameter, value	Authorization; one stopped/non-recording native voice edit with undo and read-back
grid_device_parameters	expected_project_token	Native Grid direct/inspector scalar identities, exact choices and parameter revision; voice allocation uses its own inspector
grid_set_device_parameter	expected_project_token, expected_selection_token, expected_parameter_revision, parameter_id, expected_normalized, normalized	Authorization; one stopped/non-recording, unautomated inspector scalar, normalized 0–1; exact identity/content guards and read-back

Automation times are absolute arranger quarter notes, 0–24576, strictly ordered after native quantization. Values are normalized 0–1; interpolation is hold or linear in the native automation domain. Start and end must equal the preserved neutral value; the final point must hold. Only an empty span or exact still-owned span can be edited; unowned points and outside content are protected. Ownership is bridge-session-local and exact-point-bound: restart does not authorize overwriting retained curves.

has_automation means a native lane is attached, not that it contains points or played. has_timeline_points reports native timeline-point state; inspect the complete points and point_count for stored content. Compiled psx playback bytes derive from primary authored points and do not block inspection. Alternate, clip, segmented or generated curves remain unsupported. Stored/read-back values, playback/seek/loop behavior, captured audio and human listening are separate evidence.

Voice parameter choices are voices (integer 1–64), voice_stacking (1–16), mono_mode (true_mono/alternating_voices), retrigger_mode (never/on_note_on/always), note_priority (last/low/high), legato_glide (boolean) and glide_ms (finite 0–500). Read live configuration and native glide resolution first; never substitute remote-control values or infer audible note/phase behavior from configuration.

Incremental Grid patch sessions

grid_patch_start accepts the recipe object directly, not a nested recipe field. It is a non-mutating preview requiring a supported live graph.

Field	Contract
nodes	Required array, 1–64 nodes: alias, catalog package_id, integer x/y (−4096…4096); optional exact live instance_id to bind an existing node
musical_intent	Required array, at most 16 strings of 1–512 characters
parameters	Optional array with node alias and exact native id; exactly one of finite native value (number/boolean) or musical display_value such as "65 ms", "120 Hz", "-6 dB" or "20 %"
connections	Optional array of {source, source_port, target, target_port}: aliases and exact live port names; optional allow_replace boolean, false by default
protected_routing	Optional array of {target, target_port}: target is an existing live instance ID, not an alias; port is its exact input name
feedback_review	Optional {acknowledged: true, reason: "..."} with a nonempty reason, required when observed/projected feedback needs review
source_policy / role_id	Optional native-only package allowlist enforcement and stable role scope
controls	Optional bounded named controls: ID, unit, minimum/maximum, neutral, polarity, scope and exact alias/parameter destinations with scale/offset

Aliases match [A-Za-z][A-Za-z0-9_-]{0,63}. The recipe is bounded to 256 total operations; each optional operation array also has a 256-item cap. Insertion origins must not collide, but this does not prove full module-box separation. Existing bindings must match the exact package and coordinates. Unavailable metadata is deferred until the corresponding insertion is verified; names are not guessed. Feedback acknowledgment is not a stability proof.

Tool	Arguments	Result
grid_patch_start	Recipe fields above	Session, integer revision, bindings and one next-action preview
grid_patch_status	session_id	Current preview/progress; external changes can freeze the session
grid_patch_step	session_id, exact integer revision ≥1, authorization	At most one guarded operation and read-back; no-op steps may advance without mutation
grid_patch_control	Completed session_id, control_id, a bounded musical value or reset: true	New role-scoped parameter preview; native unit resolution, exact graph guards; no write
grid_patch_restore	Completed parameter-only session_id	New preview of exact before-values; refuses changed state or topology operations

Sessions last at most one hour from creation, with at most 32 retained sessions. Steps insert nodes, set parameters, then connect ports. They preserve routing by default and freeze on stale state, ambiguity, unexpected changes or failed verification. There is no automatic retry, rollback, graph replacement, move or deletion. The retained before-graph is evidence, not a restore command.

Audio audition and listening evidence

PipeWire capture requires pw-dump, pw-link, pw-record, GNU timeout, ffmpeg and ffprobe. Capture files are evidence outputs, never sample inputs.

Tool	Required arguments	Result / boundary
grid_audio_outputs	{}	Exact current Bitwig output port/node serials; no microphone or default monitor selection
grid_audio_preview	expected_project_token, two port_serials in left/right order, start_beats, end_beats	Stopped, disarmed, non-recording project with active audio engine and arranger loop off; optional tail_seconds 0.1–30, sample_rate 44100/48000/96000
grid_audio_capture	Exact capture_id, revision, confirm_capture: true, confirm_transport: true	Optional output_dir; consumes one proposal, routes only reviewed outputs, observes seek/play settling, captures the span, then observes stop before recording the release tail
grid_audio_status	capture_id	Observe progress/result/retained files; never retry a consumed attempt
grid_audio_analyze	path	Single mono/stereo audio stream, ≤1860 seconds and 2 GB; finite/peak/RMS/crest/envelope/low-band phase evidence, no native or listening acceptance
grid_audio_compare	first, second	Attenuation-only whole-file RMS comparison; optional output_dir renders verified matched WAVs. Not perceptual LUFS matching

Capture proposals expire after five minutes, retain at most 32 sessions, and allow at most 1830 seconds including release tails. Recorder sample and independent wall-clock limits bound capture after adapter loss. Transport recovery still requires fresh project observation and explicit authority. Routing is sampled every 250 ms, not continuously proven atomic. Preserve partial files and requires_observation; never convert them into acceptance. Capture waits for submitted transport state rather than treating acknowledgments as settled. It records end overshoot and stopped-tail evidence; recorder pre-roll and observed stop latency mean boundaries are not sample-accurate. It never implicitly activates the engine, disarms tracks or disables arranger looping.

Preview-first shaping

Tool	Arguments
grid_shape_start	Required brief; optional preset, style, intensity 0–1, controls map of names/indexes to normalized values 0–1
grid_shape_compose	Required session_id; optional preset, style, intensity, controls (not a replacement brief)
grid_shape_status	session_id
grid_shape_apply	session_id, exact integer revision, authorization
grid_shape_undo	session_id

Presets: acid, ember, glass, hollow. Styles: slow-air, deep-bed, distant-events, soft-drift, night-motion, layered-motion, pulse-lab. Review the proposed diff; apply only its current revision. Undo restores the previous applied parameter state for that process-local shaping session.

Graph and device mutations

Graph writers accept expected_revision, an exact 64-hex graph revision. It is required for grid_clear_graph; other direct graph writers may omit it to trigger a fresh adapter read, not authorization against an older preview. Supply the reviewed revision explicitly.

Tool	Required arguments	Gate
grid_insert_module / grid_insert_modulator	package_id, integer x, y	Authorization
grid_set_module_parameter / grid_set_modulator_parameter	module_id, raw exact parameter_id, native value	Authorization
grid_connect_modules / grid_connect_modulator	source_module_id, source_port, target_module_id, target_port; live nonnegative numeric ports	Authorization
grid_disconnect_module	target_module_id, target_port	Authorization
grid_clear_graph	expected_revision	Authorization; destructive clear of the selected graph, retaining a before snapshot
grid_insert_device	position: before/after/start/end/replace, catalog device_id, expected_selection_token	Authorization; selected track required, before/after/replace also selected device
grid_remove_device	expected_selection_token	Authorization; remove the exact selected native device
set_selected_device_parameters	parameters map, exposed indexes to values 0–128	Authorize at orchestration layer
grid_invoke_action	Exact action_id from grid_list_actions	Authorization; may launch live content
grid_select_track	track_index from the current flat bank	Selection change
grid_navigate_device	direction: next/previous/parent/first	Selection change; first supports an empty selected track

Coordinates are Grid points within −4096…4096. Module parameters use native metadata, not shaping's 0–1 or exposed controls' 0–128 domain. Device edits use the fresh 64-hex selection_token from selected-device properties or grid_list_devices, not a graph revision or project token. Native identity and selection are revalidated on Bitwig's document thread. A null selection token preserves public state/inspect reads but cannot authorize native device edits. Re-read after navigation or a write; never replay a timed-out mutation.

Nitro evidence

Tool	Arguments	Result
grid_nitro_status	{}	Dependency/image/key prerequisites; no decryption test
search_grid_nitro	Required printable query (empty lists all); optional integer limit 1–100	Installed .nitrobin names from ZIP central directory, without keys/dependency
inspect_grid_nitro	Required module, exact safe relative .nitrobin name returned by search	Bounded static parsed evidence using authorized local keys and optional dependency

Search query length is at most 120 characters; default limit is 20. Nitro reads never extract keys, mutate Bitwig, execute DSP or write recovered source. See Data and safety for provenance, resource bounds and why catalog readability is not proof of successful installed DSP decryption.

Recovery tools

Tool	Arguments	Boundary
save_parameter_snapshot	name	Capture observable selected-device values in memory
compare_parameter_snapshots	first, second	Compare named snapshots, no mutation
apply_parameter_snapshot	name	Restore parameters; authorize and verify target identity
grid_project_undo / grid_project_redo	{}	Latest global host operation, not a patch/song-session transaction

Error handling

MCP transport success is not operation success. Stop on Error: ..., JSON ok: false, frozen patch sessions or Nitro failure statuses. Import receipts may carry ok: true while native status is rejected or unverified. Check the operation's status and evidence, then read current state. A timeout can follow a native submission; never automatically replay a write, patch step or import.