Coding agents and MCP
benchbar mcp is a Model Context Protocol server on stdio, so Claude
Code, Cursor and other agents can see and drive your benches:
claude mcp add benchbar -- benchbar mcpFor another client, add a stdio server whose command is benchbar with
the argument mcp.
Tools
| Tool | What it does |
|---|---|
benchbar_list | Every bench benchbar knows: path, default site, sites, ports, whether its service is installed |
benchbar_status | Live state of one bench, with pid, ports, the bench its service runs (bench_bin), sites and the ping of every site while the bench runs. A bench folder benchbar does not manage has state not_adopted |
benchbar_doctor | The read only health report of one bench, every check with its level and fix |
benchbar_logs_tail | The last lines of one log file: file is bench (logs/bench.log, honcho’s stream), worker (logs/worker.log, where the worker writes), worker_error or previous; process keeps one honcho process of bench.log. Each line has a time in ts; since (ISO 8601, a date or HH:MM:SS today) and since_restart keep only the newer lines |
benchbar_site_list | The sites of one bench, the default, the hosts line, the ping code, the database name and the MariaDB port (never the password) |
benchbar_app_list | Every app of one bench: repo, branch, commit, local changes, version, sites (from the last read, the database is not asked) and how far behind its dependencies it is |
benchbar_profile_list | Built in and team profiles: where each comes from, how far a subscription is behind, what hides what |
benchbar_profile_check | Whether git can read every repo of a team profile (name) with your credentials, and which apps install --profile would leave out |
benchbar_up | Start a bench and wait for its default site |
benchbar_down | Stop a bench and keep it stopped, also across reboots |
benchbar_restart | Restart every process of a bench |
benchbar_app_add_plan | The plan of adding an app from a git URL or a known name, with its token (read only) |
benchbar_app_add | Apply that plan: needs the token, returns the output and a fresh app list |
benchbar_list, benchbar_status, benchbar_doctor,
benchbar_logs_tail, benchbar_site_list, benchbar_app_list,
benchbar_profile_list, benchbar_profile_check and
benchbar_app_add_plan read; benchbar_up, benchbar_down,
benchbar_restart and benchbar_app_add act. Each one runs
benchbar ... --json and returns what the CLI printed. The server sets
BENCHBAR_NONINTERACTIVE=1, so a command that needs an answer it cannot
ask for stops and names the missing input. An action also returns the
CLI’s done line as result, with changed, warnings and
next_actions, next to the fresh status. Nothing that
repairs, installs a bench or needs sudo is offered. It needs only
python3, which the Command Line Tools provide.
Calls run side by side: a status answers while an app add runs, and the
client can cancel a running call (notifications/cancelled), which
stops the CLI and everything it started. Arguments are checked against
the schema first; a bad value (lines: 99999, process: "nope") is a
tool error that names the rule. What the bench itself says, log lines,
git output, hooks.py, profile files and the output of an action, comes
back with a first line that labels it as data from the bench, not
instructions, with terminal colors removed and a 200 kB cap; the
mcp reference has the details.
Adding an app
Paste a GitHub URL into the chat and the agent can add the app, from a
plan it should show you first. Adding an app runs its code on your Mac:
its Python and Node requirements are installed and, on each site you
name, bench install-app runs its install hooks and writes its tables
into that site’s database. A running bench is restarted at the end. So
add only repos you trust, and read the plan:
benchbar_app_add_planwithurl_or_name(andbranch,name,siteorall_sites) reads the repo and itshooks.pyand returns the plan: repo, branch, the required apps and where each comes from, the sites, the steps, and atoken. Nothing changes.- The agent shows you that plan and waits for your OK. benchbar cannot tell whether you saw it: the token proves only that the bench has not changed since the plan, and the tool says so, so ask your agent to show the plan before it applies.
benchbar_app_addwith the same arguments and thetokenruns exactly that plan. Ifsites/apps.txt,apps/or the sites changed in between, the token is refused and the agent plans again.
The apply can take several minutes (clone, pip, yarn, build); the server
waits up to an hour and returns everything at the end. Some clients stop
waiting sooner: the run goes on, and benchbar_status or app list
shows the outcome.
Every tool but benchbar_list and the two profile tools takes an
optional bench, the absolute path from benchbar_list; without it the
tool acts on the default bench. The tools that change a bench refuse a
path that is not in benchbar_list; register it first in a terminal
with benchbar register PATH.
The JSON each one returns is described in the JSON schema.
The CLI as an agent contract
An agent that runs benchbar in a terminal gets the same contract as the
MCP tools:
benchbar COMMAND --help # flags, what the command needs, whether it changes thingsbenchbar commands --json # the same for every command, flag and environment variablebenchbar up --for-agent # JSON lines, nothing is ever askedbenchbar doctor --for-agent # one JSON document--for-agentprints JSON lines (plan,step,progress,done) for a command that changes things, and one document for a command that only reads. It also setsBENCHBAR_NONINTERACTIVE=1,NO_COLOR=1and--plain.--jsonlasks for the stream alone.- The
doneline ends every command that changes things. It hasexit,changed[](what the run really changed),warnings[],next_actions[](the commands to run next, each with a reason) andstate_after(the bench’sstatus --jsonafter the run). A second run that has nothing to do has an emptychanged. The JSON schema has every field. - With
--jsonstdout holds JSON and nothing else. A refusal is text on stderr. - With
BENCHBAR_NONINTERACTIVE=1a command that lacks an input (ADMIN_PASSWORD,MARIADB_ROOT_PASSWORD,--yes, asudothat would ask) names all of them in one error before it takes the lock or touches the bench. It exits 2 when the MariaDB root password is one of them. benchbar doctor --quickskips the slow checks and names them.doctor --ack CHECKsilences one warning until its message changes;--unack CHECKundoes it. A failure cannot be acknowledged, andrepairignores acknowledgements.benchbar logs --json --since TIMEand--since-restartreturn the new lines only, each with its time ints.
Repairs and installs
Repairs and bench installs are deliberately not tools. An agent runs them in a terminal, with you, and shows the plan first:
benchbar doctor --jsonbenchbar repair --dry-runbenchbar repair --yesAGENTS.md in the repository is written for agents that
are pointed at BenchBar with “set up Frappe on my Mac” or “my bench is
broken, fix it”: how to start from the facts, the rules they must keep
(never rm -rf inside a bench, never bench update unless asked, never
print the MariaDB root password), and how to read the output.