Tutorial : How to use the MCP server in Usine

Usine has a built-in MCP server. Connect an AI assistant such as Claude to it and you can ask, in plain language, for a patch, a module chain, a script module or a parameter change: the assistant builds it in Usine while you watch.

In short

  1. In Usine, turn enable MCP on (Setup panel, AI tab).
  2. Connect your assistant to Usine: paste the prompt below into it, or double-click the install script.
  3. Restart the assistant and ask it something about Usine.

That is all. The rest of this page gives the details, and what to do when something does not work.

Step 1 — Turn the server on in Usine

Open the Setup panel, go to the AI tab and turn enable MCP on. Leave MCP port at 3100 unless another program uses it. The setting is saved: the server starts with Usine from now on.

If the AI tab is missing or shows not available, your Usine edition does not include the AI features.

Step 2 — Connect your assistant

Let the assistant install itself

If your assistant can run commands on your computer (Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf...), paste this and let it work:

Usine by BrainModular is installed on this computer and I want you to use its MCP server.

1. Find the Usine installation folder: it contains Resources/AI/mcp-bridge.js
   (on macOS the folder is Usine.app/Contents).
2. Check that Node.js is installed (the "node" command). If it is not, tell me how to
   install it from https://nodejs.org and stop here.
3. Register the MCP server:
   - Windows: run <Usine folder>\Resources\AI\install\install-mcp.cmd
   - macOS, Linux: run sh "<Usine folder>/Resources/AI/install/install-mcp.sh"
   The script registers the server named "usine" for Claude Desktop and Claude Code.
   If you are another client, register it yourself as a stdio MCP server:
   command "node", argument "<Usine folder>/Resources/AI/mcp-bridge.js",
   environment variable USINE_WS_URL=ws://localhost:3100.
4. Read <Usine folder>/Resources/AI/README.md and tell me what you did.
5. Remind me to start Usine with "enable MCP" turned on (Setup panel, AI tab),
   and to restart you so that the Usine tools appear.
6. Once connected, call the Usine tool get_engine_status and show me the answer.

Or do it yourself in one click

Windows: in your Usine folder, double-click Resources\AI\install\install-mcp.cmd.

macOS: open a terminal and run sh "/Applications/Usine.app/Contents/Resources/AI/install/install-mcp.sh" (adapt the path).

The script needs Node.js (it tells you if it is missing), registers the server for Claude Desktop and Claude Code, and reminds you to turn enable MCP on. For Claude Desktop, which cannot run commands by itself, this is the way.

Then restart the assistant completely: the Usine tools appear in its tool list.

Step 3 — Talk to Usine

Start with a check:

What is the state of the Usine audio engine?

The assistant answers with the sample rate, the block size and whether the audio is running. If it does, everything is connected. Then ask for real things:

  • Show me the workspace, then create a patch named "First test" with an analog oscillator connected to the audio output.
  • Add a low-pass filter between the oscillator and the output, cutoff at 800 Hz.
  • Rename the modules of this patch with clear names.
  • List the links of the current patch and tell me what the patch does.
  • Write a script module that outputs the average of its array inlet.
  • Save this patch as C:\Usine\my-patch.pat.

The assistant works on the target patch: the one it created, or the one it selected when you named it. When you work on several patches, say which one you mean.

Before every change, the assistant stores the patch for undo. If the result is not what you wanted, the usual undo of the patch brings you back.

If something does not work

What you see What to do
Failed to connect to Usine: ECONNREFUSED Usine is not running, or enable MCP is off, or the port differs. The connection retries every 2 seconds.
No Usine tools in Claude Desktop Restart Claude Desktop completely. If still nothing, a syntax error in its configuration file disables every server: run the install script again.
node not found Install Node.js from nodejs.org, then run the install script again.
The assistant builds a patch but nothing moves or sounds Ask it for the engine status: with the audio stopped, the patches are not processed. Check the audio setup.
No active patch found Ask the assistant to select or create a patch.

Turn trace MCP messages on (Setup, AI tab) to see every request and answer in the trace panel.

What the assistant can do

About fifty tools, which the assistant picks by itself:

Family Examples
Workspace, racks, patches list them, create, rename, clear, select the target patch, show a panel
Modules and links list the module classes and their ports, create, rename, delete modules, connect outlets to inlets, read the whole patch structure
Parameters read and set values, texts, colours and arrays
Scripts create a script module with its code, read or replace the code, see whether it compiles
Chunks and variables list the chunks and read their items, read and set IML variables
Files load and save patches, racks and workspaces
Undo and diagnostics undo, redo, state of the audio engine

Two prompts come with the server. Your assistant lists them with its other prompts:

  • usine-guidelines: the rules it follows with Usine (undo first, check names before linking, ask before destroying).
  • usine-scripting-reference: the reference of the script language. Load it before asking for a script module.

Going further

Configuration by hand

The install script writes this entry in the Claude Desktop configuration (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

"usine": {
  "command": "node",
  "args": ["<USINE FOLDER>/Resources/AI/mcp-bridge.js"],
  "env": { "USINE_WS_URL": "ws://localhost:3100" }
}

and runs, for Claude Code, claude mcp add usine -s user -e USINE_WS_URL=ws://localhost:3100 -- node "<USINE FOLDER>/Resources/AI/mcp-bridge.js". Any other client that starts stdio MCP servers takes the same command, arguments and variable. Options of the script: --port 3200, --host 192.168.1.20, --remove.

How it works

The server is part of Usine and listens on a WebSocket port. Assistants start their MCP servers as local processes and talk to them through standard input and output: mcp-bridge.js sits between the two and forwards the messages.

  assistant  ──stdio──►  mcp-bridge.js  ──ws://localhost:3100──►  Usine

The assistant never sees your screen: it only knows what the tools answer, which is why they describe patches, ports, values and the engine in detail.

Usine on another computer

Install the bridge on the computer running the assistant with --host <address of the Usine computer>, and open the port in the firewall of the Usine computer. See the network setup.

Security

The server has no authentication and listens on every network interface: any program that reaches the port controls Usine. On a network you do not control, keep the port closed in the firewall, or turn enable MCP off when you do not use it. The assistant can load, save and clear patches, racks and the workspace; its guidelines tell it to ask you before a destructive action, but keep your work saved.

Examples to try

Start simple, then let the requests grow. The assistant finds the module classes, the port names and the values by itself.

A small synth, with a control in the control panel:

Create a patch named "Pad" with a sawtooth oscillator, a low-pass filter (cutoff 1200 Hz,
resonance 0.3), a stereo volume at -6 dB and the audio output. Add a horizontal fader in
the control panel that drives the filter cutoff between 200 and 8000 Hz.

Change an existing patch without redoing it:

In the current patch, insert a stereo delay of 375 ms between the filter and the volume,
mixed at 30%, and add a switch to bypass it.

Understand a patch you did not build:

Describe this patch: list its modules and connections, then explain the signal path in a
few sentences. Tell me which controls are visible in the control panel.

A mixer built in one go:

Build a 4-channel mixer: for each channel an audio input, a volume fader and a mute switch
in the control panel, all summed to a stereo volume and the audio output. Name the modules
"channel 1" to "channel 4".

A script module written and compiled for you:

Write a script module with an array inlet and two data outlets, "minimum" and "maximum",
that outputs the smallest and the largest value of the array each time it changes.
Compile it, connect its inlet to an array display and tell me if it compiled.

Two scripts that share data through a chunk, without a wire between them:

Create a patch with two script modules: the first writes the array received on its
inlet into the item "array" of the chunk "example.chunk" each time it changes, the
second subscribes to that item and outputs the array. Add an array display before
and after, connect everything, and add a comment that explains the patch.

The assistant loads the scripting reference, writes the two scripts with WriteToChunk and SubscribeChunk, places and connects the displays, and checks with the chunk tools that the array goes through. Change the bars of the first display: the second one follows.

A step sequencer, data and timing together:

Make an 8-step sequencer at 120 BPM: a clock advances a step counter in a loop, each step
reads a pitch in semitones from an 8-value array shown in the control panel, and the pitch
drives a sine oscillator going to the audio output. Add a start/stop switch.

Housekeeping and files:

Rename every module of this patch with a short clear name, align them left to right in
the order of the signal, then save the patch as C:\Usine\Patches\pad.pat and give me the
final list of modules.

When something is wrong:

The output of the module "low pass 1" stays at 0. Read its parameters, check the links
around it and the state of the audio engine, and tell me why.

See also

Usine Tutorial

version 7.0.250921

Edit All Pages