Tech docs — the agent door
A console an agent can read and write through the contract every other client uses.
OpenMixer ships an MCP server over stdio. Its tools read and write a running console through the console’s own REST contract, and read the contracts each channel stage declares at the moment they are asked. It decides nothing: every answer is data the desk or the tree already holds, named with where it came from.
01
Running it.
omx-mcp speaks MCP over stdio: an MCP client starts the process and talks to it over the pipe. That way there is no port, no daemon and nothing to leave running.
# stdio; an MCP client starts it and speaks to it over the pipe.
omx-mcp
For a client that cannot start a process, omx-mcp-http serves the same tools over MCP’s Streamable HTTP. It listens on loopback unless MCP_HOST names another address, on the port MCP_PORT names. With MCP_TOKEN set, a request without that bearer token is refused. Off loopback with no token, it starts without the tools that write and says so at start: anyone who can reach the port can read the console, and nobody can change it.
| Variable | Meaning | Default |
|---|---|---|
| OPENMIXER_CONSOLE | base URL of the console the console_*/rig_* tools talk to; named in every result | http://127.0.0.1:8080 (core's DEFAULT_WEB_PORT) |
02
6 tools, in two families.
One family is the REST entity door as it stands: the roster, a row, its declared travels, one frame of a metered row, and a write. The other reads the contracts a channel’s DSP stages declare: the laws, the parameters and their limits. The table below is generated from the package’s registered tool table, not written by hand, and the package’s own test refuses a description that has drifted from the registry.
The console
| Tool | Arguments | What it answers |
|---|---|---|
| console_discover | filter | The served entity roster from the console's own contract (OPTIONS /api/): every path template it serves, which rows are pump-fed (measured only while watched), and which carry declared travels and defaults. Optional substring filter over paths. |
| console_meters | strips | One reading of the meter frame, decoded through the windows /meters declares on OPTIONS, projected to the strips asked for (channel keys like "input/1"; all strips when omitted). A pump-fed row measures only while watched, so an unmeasured GET is followed by ONE watch that is closed the moment the first measured frame lands — no stream is held. |
| console_get | path | GET one row by path (e.g. /channel/input/3/fader). The console's status, Allow header and body come back as they are. |
| console_options | path | OPTIONS one row: what it MAY be — its methods, fields, travels (limit/taper), writability and instances, as the console declares them. |
| console_patchwrites | path, body, confirm | PATCH one row with a JSON delta. A REAL WRITE to a desk, sent exactly once and never retried; the console's answer — status, Allow, and the body with its fault, refusal and reason — is returned verbatim. A fire on a confirm-gated row (a channel-config apply that would move gain/trim/pan) is REFUSED BY THE CONSOLE with 409 CONFIRM_REQUIRED while its preview lists moves and the operator's sign-off is on; the body carries the preview. Re-call with confirm: true — it rides the delta as the row's own confirm argument — to apply anyway. |
The declared contracts
| Tool | Arguments | What it answers |
|---|---|---|
| contract_laws | stage | The declared DSP contracts for a channel fact (eq, gate, dynamics, delay, reverb, drive, pan, toMain) or a raw C function name: the closed-vocabulary laws with their operator-facing sentence, the parameters and their declared limits where the fact resolves to a numeric table, the C file:line where a contract sits, and whether the rt_contracts.test.c battery exercises it. Read from CHANNEL_CONTRACT and rt-callgraph.mjs's own function map at call time -- never a second copy. |
03
One tool writes, and it writes once.
Every tool but one reads. console_patch sends a real write to a real desk, so it sends exactly one request, never retries it, and hands back the console’s status, its Allow header and its body as they arrived. A refusal is the desk’s ruling and is returned verbatim rather than interpreted, which is the same contract every other client works under: the console decides, and what comes back is what it decided.
The tool holds nothing back on its own account. A write that fires an operation the console’s own confirms sheet gates — a channel-config apply that would move gain, trim or pan is the example — is sent, and the console refuses it with CONFIRM_REQUIRED while the preview lists moves and the operator’s sign-off is on. The refusal comes back with the preview in the body, like any other answer. Calling again with confirm: true — which rides the delta as the row’s own confirm argument — applies it, because the agent has now been shown what it is agreeing to. The gate is the desk’s, so an agent, a browser and an OSC surface are refused identically and answer identically; there is no client-side policy to keep in step.
The metered row is the one place a read is not simply a GET. A pump-fed row measures only while something is watching it, so an unmeasured frame is followed by a single watch that closes the moment the first measured frame lands. No stream is left open.
The tools stand on a fake console with the real console’s shapes, checked across the wire on values rather than on shapes — a −20 dBFS reading has to decode to −20. A live desk is not part of that suite.