AI agent control

An AI assistant can build and edit your patch for you. This works with any AI assistant that supports MCP, the Model Context Protocol, including Claude Code, Cursor, Windsurf, and Claude Desktop. The assistant reads the synth's own knowledge: the full list of modules, their documentation, and a way to check that a patch is valid. Once you connect it to your studio, it can also edit the patch you have open while you listen. Ask it to add a delay send and the change appears in your patch.

Two ways to work

Your agent can work on a patch in one of two ways.

The first way works on patch files saved on your computer. The agent reads, writes, and checks .studio.json files without connecting to the studio at all. It can build a whole patch this way while the studio is closed, and you open the result with File then Import. Import is a Pro feature. On the free plan, have the agent send the patch to your open studio instead, using the live connection below.

The second way works on the patch you have open. Through a connection you turn on yourself, the agent edits your current patch directly. Every change it makes is the same kind of edit you could make by hand in the studio. You hear each change right away, and you can undo it with Ctrl+Z.

The studio picks how the agent connects. When your agent runs on the same computer as your browser, the two connect directly. When you use the hosted site at vxsynth.com, the connection passes through a relay server instead. You never configure it.

The AI Agent chip

The connection lives behind the AI Agent chip in the top bar, to the left of the memory meters. The dot on the chip shows its state. Green and glowing means the agent is connected. Grey means the connection is off. Amber means it is in one of these in-between states:

  • connecting: the tab is looking for the server on your computer and retries every 2.5 seconds. Start the server and the tab connects on its own.
  • unpaired: the server answered, but it still needs the connection token you set up below.
  • busy: another studio tab already holds the connection. Only one tab can use it at a time. Work in that tab, or reload this one to take the connection over.

The connection is off until you turn it on. Your choice stays set across reloads. Turning it off ends the connection right away.

Connect your agent

Connecting the agent to your studio is called pairing. You do it once per computer.

  1. Download the server. It is one file and needs Node 18 or newer: curl -fo ~/vxsynth-mcp.mjs https://vxsynth.com/mcp/vxsynth-mcp.mjs. The file is rebuilt every time the site deploys, so it always matches the modules on this site.
  2. Add the server to your agent. In Claude Code, run claude mcp add vxsynth -- node ~/vxsynth-mcp.mjs, then reconnect the agent's MCP session. Other MCP assistants each have their own way to add a server that points at the same file.
  3. In the studio, click the AI Agent chip, turn the connection on, and copy the pairing token from the panel that opens. Tell your agent to pair with your studio and paste the token. The chip turns green. The agent saves the token in ~/.vxsynth/mcp.json, so you only pair once per computer.

For a faster setup, open the /connect-agent page and click Copy setup instructions. Paste that text into your agent and it runs the download and registration commands itself. Two steps still need you: reconnect the agent's MCP session, and read the token off the chip.

When you paste the token, case, dashes, and spaces do not matter. The token itself never travels over the connection. Instead, both ends prove they know it through a challenge and response. If the token ever leaks, click reset token in the same panel to replace it.

What the agent can do

  • Read the patch you have open.
  • Set any control on any module, including knobs, menu choices, sequencer steps, and the notes in a piano roll. Each change is a single edit you can undo.
  • Add and remove modules at spots you choose on the canvas.
  • Connect and disconnect cables by naming the jacks they plug into. Ctrl+Z undoes any of these edits.
  • Replace the whole patch at once. The agent checks the new patch first and warns you about any samples it uses that are missing from your library. Replacing the patch works like opening a file: it clears the undo history. Save your current patch first if you want to keep it. See Patches.
  • Write note lines straight into a Piano Roll track, with no MIDI file involved. Over the live connection the notes appear in your open patch. If the agent writes them to a patch file instead, the notes arrive when you open the file with File then Import.
  • Read the same module documentation the in-app "?" button opens, so its suggestions come from the real panels.

What the agent cannot do

  • The agent has no audio path, so it cannot hear the result. Tell it what you are hearing and what to change.
  • The connection gives the agent no access to your files or your account. It can only make the same edits you can make in the studio.
  • The agent cannot switch on the master audio power, and it cannot start playback in the automation dock. It can press a module's own play control, such as the Piano Roll's run button, because that control is an ordinary setting.

Tips

  • Start with "What's in my patch right now?" This confirms the pairing and gives the agent context before you ask for changes.
  • Ask the agent to build a patch one module at a time, for example "Build me a generative ambient patch from scratch, one module at a time." Each choice is then a separate edit, so Ctrl+Z steps back through them and you can hear what each module added. Replacing the whole patch at once lands as a single edit with no such history.
  • Ask for changes while you play, for example "Write a two-bar minor-pentatonic bassline into track 2 of my piano roll." See Sequencing for what each track can hold.
  • Because the agent cannot listen, describe the sound you want rather than the settings. "Darker, with a slower attack" works better than guessing parameter names.