MCP (AI agent integration)

MCP (Model Context Protocol) lets compatible AI agents inspect and edit the project currently open in skulpton. For example, you can ask an agent to set the BPM to 120 or quantize a clip to a 1/16 grid.

Keep skulpton running while connected

MCP connects locally to the running skulpton app. Closing skulpton also closes the connection.

Enable MCP

1. Open Preferences → AI Agent in skulpton.
2. Turn on Enable MCP bridge.
3. To allow operations that change the project, turn on Allow write operations. It is off by default.
4. Register skulpton-mcp as a stdio server in your MCP client.

The bridge listens on localhost only. Its connection details and temporary token are stored in a descriptor file only while it is enabled. Your MCP client reaches the bridge through skulpton-mcp.

Start with read-only access

You can inspect the project and available plugins while Allow write operations is off. Enable it only when you need editing access.

Confirming write operations

Write operations require confirm: true. Use the same operation with dryRun: true to inspect the proposed result before applying it. A dry run still validates arguments and target ids, and returns a change plan listing the affected entities, counts, runtime impact, and any files that would be overwritten — without modifying the project or any file. Read operations need neither write permission nor confirmation.

Supported operations

“Read” operations do not change the project. “Write” operations require Allow write operations and confirm: true.

Area	MCP tool	Type	Operation
Project	project.get_current	Read	Get a composition-focused project, selection, and transport summary
Project	project.get_raw	Read	Get the complete current project state
History	history.get_status	Read	Get undo/redo availability and bounded history depths
History	history.undo	Write	Undo the latest project edit
History	history.redo	Write	Redo the latest undone project edit
Timeline	project.get_timeline	Read	Get bounded tempo, meter, track-order, and clip-range summaries
Mixer	mixer.get_state	Read	Get persisted mixer and routing state
Mixer	mixer.master.update	Write	Update master gain, pan, mute, or name
Mixer	mixer.return.add	Write	Add a return bus
Mixer	mixer.return.update	Write	Update return gain, pan, mute, or name
Mixer	mixer.return.remove	Write	Remove a return and clean dependent sends and routing
Mixer	mixer.track.set_send	Write	Set or clear a track send target, gain, and pre/post-fader mode
Mixer	mixer.bus.set_send	Write	Route a return with cycle validation or restore its master output
Automation	automation.get_state	Read	Get automation lanes and points for an arrangement
Plugin	plugin.get_chains	Read	Get plugin chains for tracks and buses
MIDI ports	midi.get_ports	Read	List connected MIDI input and output ports
Project	project.save_current	Write	Save to the current or specified path
Project	project.set_name	Write	Change the project name
Project	project.set_bpm	Write	Change the BPM
Project	project.set_tempo_map	Write	Replace the tempo map
Project	project.set_time_signature_map	Write	Replace the time-signature map
Project	project.set_quantize_settings	Write	Replace project quantize settings
Project	project.set_length_bars	Write	Change the project length in bars
Project	project.set_scale	Write	Set or clear the project scale
Project	project.set_notes	Write	Update or clear project notes
MIDI export	midi.export_clip	Write	Export one clip as a Standard MIDI File
MIDI export	midi.export_project	Write	Export the current arrangement as a Standard MIDI File
Plugin	plugin.list_available	Read	List cached available plugins
Plugin	track.assign_instrument	Write	Assign an instrument plugin to an Instrument Track
Arrangement	arrangement.create	Write	Create an arrangement
Arrangement	arrangement.duplicate	Write	Duplicate an arrangement
Arrangement	arrangement.set_active	Write	Switch the active arrangement
Arrangement	arrangement.rename	Write	Rename an arrangement
Arrangement	arrangement.remove	Write	Remove a Scratch Pad
Arrangement	arrangement.copy_clips	Write	Copy active-arrangement clips to another arrangement
Track	track.add	Write	Add a MIDI, Audio, or Instrument Track
Track	track.update	Write	Update metadata and MIDI routing fields
Track	track.remove	Write	Remove a track and dependent clips and routing
Track	track.reorder	Write	Change track order
Track	track.set_initial_program	Write	Set the MIDI Program Change sent when playback starts
Track	track.set_output_bus	Write	Route the main output to a master or folder bus
Track	track.set_mixer_input	Write	Set audio or instrument track input routing
MIDI clip	midi_clip.add	Write	Add a MIDI clip to the active arrangement
Automation lane	automation_lane.add	Write	Add a gain, pan, MIDI CC, or plugin parameter lane to a track
Automation lane	automation_lane.update	Write	Update the lane name or authoritative target and sync owned clips
Automation lane	automation_lane.remove	Write	Remove the lane and its clips across all arrangements
Automation clip	automation_clip.add	Write	Add a validated envelope clip to an existing lane
Automation clip	automation_clip.update	Write	Atomically update clip name, range, or point envelope
Automation clip	automation_clip.remove	Write	Remove a clip from the active arrangement
Automation clip	automation_clip.move	Write	Move multiple clips to absolute beats in one transaction
Automation clip	automation_clip.duplicate	Write	Duplicate a clip immediately after its stable source ID
Automation clip	automation_clip.slice	Write	Split at an absolute beat with an interpolated continuous boundary
Automation clip	automation_clip.merge	Write	Merge clips sharing one track, lane, and target
Automation point	automation_point.add_many	Write	Add validated clip-local beat, normalized value, and curve points
Automation point	automation_point.update_many	Write	Atomically validate and update points by current index
Automation point	automation_point.delete_many	Write	Atomically validate and delete points by current index
Automation point	automation_point.replace_all	Write	Replace the complete point envelope with validated points
Automation point	automation_point.simplify	Write	Deterministically simplify all points or an index subset
MIDI clip	midi_clip.update	Write	Update start, length, or name
AudioClip	audio_clip.add	Write	Add an AudioClip with an AudioFileRef
AudioClip	audio_clip.update	Write	Update placement, length, or persistent media reference
AudioClip	audio_clip.update_edit	Write	Update source-native-frame trim, gain, fades, and gain envelope
AudioClip	audio_clip.set_warp	Write	Set warp mapping in source-native frames and clip-local beats
AudioClip	audio_clip.remove	Write	Remove an AudioClip
AudioClip	audio_clip.move	Write	Move an AudioClip between audio tracks
AudioClip	audio_clip.duplicate	Write	Duplicate an AudioClip by stable ID
AudioClip	audio_clip.slice_many	Write	Split at multiple beats in one transaction after atomic validation
AudioClip	audio_clip.merge	Write	Rejoin contiguous slices of the same source in one transaction
AudioClip	audio_clip.toggle_crossfade	Write	Toggle the equal-power crossfade for two overlapping clips
AudioClip	audio_clip.consolidate	Write	Replace clips only after a successful bounded offline render
AudioClip	audio_clip.bounce_instrument	Write	Offline-render instrument clips into a new AudioTrack
MIDI clip	midi_clip.move	Write	Move to another track or start beat
MIDI clip	midi_clip.duplicate	Write	Duplicate one or more clips as a block
MIDI clip	midi_clip.slice	Write	Split at an absolute beat
MIDI clip	midi_clip.merge	Write	Merge clips on one track
MIDI clip	midi_clip.bounce	Write	Freeze rendered notes into MIDI clips
coding note	coding_note.set_code	Write	Update a clip’s coding note source
coding note	coding_note.render	Write	Run code and generate notes and CC lanes
coding note	coding_note.clear_render	Write	Clear stored render output
coding note	coding_note.set_loaded_libs	Write	Set the clip’s loaded libs/codes files
coding note	coding_note.set_disabled_factory_libs	Write	Set disabled factory libraries for the clip
coding note	coding_note.bounce_render	Write	Freeze render output into editable source notes
Note	note.add_many	Write	Add source notes
Note	note.update_many	Write	Update source notes
Note	note.delete_many	Write	Delete source notes
Note	note.replace_all	Write	Replace all source notes in a clip
Note	note.quantize	Write	Quantize selected notes to a beat grid
Note	note.nudge	Write	Move selected notes by beat or pitch deltas
Note	note.copy_bar	Write	Copy notes from one bar to another
Channel lane	channel_lane.add	Write	Add a CC, pitch bend, or channel aftertouch lane
Channel lane	channel_lane.update	Write	Update a channel lane
Channel lane	channel_lane.delete	Write	Delete a channel lane
Channel event	channel_event.add	Write	Add a CC, pitch bend, or channel aftertouch event
Channel event	channel_event.update	Write	Update a channel event
Channel event	channel_event.delete	Write	Delete a channel event
Transport	transport.play	Write	Play from the insertion marker
Transport	transport.pause	Write	Pause at the current position
Transport	transport.stop	Write	Stop playback
Transport	transport.seek	Write	Seek to an absolute beat
Transport	transport.set_loop	Write	Set, update, or clear the loop range

Currently out of scope

MCP v1 does not support plugin scanning and management, plugin window control, or device operations. Mixer support covers persistent master, return-bus, and send edits; runtime views such as meters remain out of scope. plugin.list_available only returns plugin information already cached by skulpton.

Troubleshooting

• Make sure skulpton is running.
• Make sure Enable MCP bridge is on.
• Check that Preferences shows the status as Listening.
• Restart the MCP client so it reads the descriptor again.
• If only edits fail, check Allow write operations and the confirmation parameter.