MCP tools
The gate serves MCP at https://HOST/mcp over streamable HTTP. A client signs
in with OAuth, and every call acts as the person who signed in. A person sees
and changes only their own Boxes. https://HOST/.well-known/oauth-protected-resource
names the issuer and the scopes.
moor does not register clients. The client registers with the sign-in
provider, so the provider must allow the client’s redirect URIs. A
dcr: invalid redirect_uri error comes from the provider’s client or dynamic
registration settings, not from moor. The gate refuses a token whose aud is
not its --mcp-resource-url, so the provider must put that URL in the
token’s audience.
Scopes
| Scope | Allows |
|---|---|
moor:read |
list_boxes, list_nodes, box_status, inspect_box, get_artifact, list_webhooks, list_workflows, list_workflow_runs, get_repo_config, list_events, GET /events, artifact downloads, the Box resources, subscriptions/listen |
moor:write |
start_box, send_to_box, exec_in_box, close_box, retry_box, close_failed_boxes, add_webhook, remove_webhook, add_workflow, remove_workflow, set_workflow_enabled, answer_run, run_workflow, set_repo_config |
Tools
| Tool | Arguments |
|---|---|
list_boxes |
none |
list_nodes |
none |
start_box |
repos; optional name, prompt, base, node, config, wait |
box_status |
box |
inspect_box |
box; optional lines, said |
get_artifact |
box, name; optional version |
send_to_box |
box, text |
exec_in_box |
box, command; optional timeout_seconds |
close_box |
box; optional force |
retry_box |
box |
close_failed_boxes |
optional force |
add_webhook |
url; optional events, header |
list_webhooks |
none |
remove_webhook |
id |
list_events |
optional after, kinds, box, limit, wait_seconds |
add_workflow |
name, repos, prompt. Optional: cron with timezone (none means by hand or on pull requests), config, timeout_minutes, plan, expected_revision, enabled (false stores it disabled), on_pull_request (true also fires on the first repo’s pull requests) |
list_workflows |
none |
list_workflow_runs |
optional after, limit, workflow (one workflow’s runs) |
remove_workflow |
name |
set_workflow_enabled |
name, enabled |
answer_run |
workflow, answer (yes or no); optional note, pull (OWNER/NAME#NUMBER, which run when several wait) |
run_workflow |
name, with optional expected_revision and pull (OWNER/NAME#NUMBER) |
get_repo_config |
repo |
set_repo_config |
repo, text; optional expected_revision |
get_node_settings |
name |
set_node_settings |
name; optional max_boxes, no_cap, labels, expected_revision |
list_nodesgives each node’s name, scope, runtime, online state, Boxes,max_boxeswhen it caps them, and free memory. Itsstartfield names the node a start with nonodewould use.start_boxtakesreposas a list ofowner/name, first one first. The agent works in the first, and the rest are cloned beside it. A list of one adds yourbox.alsobeside it. It refuses before it creates anything when you lack a secret, and links the portal. It returns once the Box exists, with the fieldsbox_statusgives. Withwait: true, it returns once setup and the agent launch finish. A start on a name that is open attaches to that Box.send_to_boxanswers a pending question with an option’s name or its 1-based number.close_boxrefuses a Box with commits that are not pushed or files that are not committed.force: truediscards that work and also stops a setup that is running.exec_in_boxruns shell text beside the agent, with no stdin and no terminal. It wakes an asleep Box. The timeout is 30 seconds by default and 120 at most. It returnsexit,timed_out, and the first 64 KiB ofstdoutandstderr. Each call records anexec_ranevent.retry_boxreruns setup on a Box insetup_failed. It returns once setup has restarted, while setup goes on. Follow it withbox_status.add_workflowon an existing name keeps every optional field you leave out. That coverscronandtimezone,config,timeout_minutes,enabledandon_pull_request. To clear the cron, sendcron: null. To clear the config, sendconfig: "". Theplanis the exception, so send the whole plan again. A new workflow is enabled, with no pull request trigger, no cron, no config and a 180 minute timeout.run_workflowreturns once the run is recorded and its Box start has begun, while the Box sets up. A start the controller refuses after that shows as a refused run inlist_workflow_runs.- No tool waits for setup by default. Only
start_boxwithwait: truedoes. add_webhookreturns the webhook’sidand asetup_url, never a secret.
box_status
| Field | Meaning |
|---|---|
status |
One line, such as ready · waiting on CI or ready · stuck: stalled. |
agent_said |
{text, at}, the agent’s newest message. |
stuck |
{kind, since, detail}, or null. |
artifacts |
The latest version of each published artifact. |
reports |
The latest version of each Report. |
events |
The last five events. |
stuck.kind is stalled, egress_refused, egress_aborted,
credential_withheld, proxy_credential_failed, agent_rate_limited,
agent_unreachable, agent_link_lost, or death_capped. stalled means the agent
reported busy and wrote nothing for ten minutes. The next sign of progress clears it.
death_capped means the Box’s places died, so moor did not resume it on its own.
Waking the Box or messaging it clears it.
The egress_aborted detail asks whether the Box clock is behind, because a
guest clock behind the host makes the Proxy’s certificates not yet valid.
It clears once the Proxy allows a request to that host again.
inspect_box
Returns pane, the last lines lines of the agent’s terminal (40 by default,
200 at most), with a status of live, exited, or gone. Also returns
said, the agent’s newest messages (5 by default, 20 at most), agent, and
stuck. It changes nothing.
list_events
Reads your events from the log, from an offset you keep.
| Argument | Default | Meaning |
|---|---|---|
after |
0 | Return events with a greater offset. |
kinds, box |
all | Only these kinds, only this Box. |
limit |
50 | At most 100. |
wait_seconds |
0 | When nothing is past after, wait up to this long. At most 30. |
It returns {events, next, caught_up}. Events lists
the kinds, such as closed and close_refused. Pass next as after in the
next call. The same arguments return the same events. Offsets increase with gaps,
because other users’ events share the log.
HTTP endpoints
The same bearer token works on these paths.
| Path | Scope | Returns |
|---|---|---|
GET /events |
moor:read |
The list_events result. Takes after, kind (repeatable), box, limit, and wait_seconds. |
GET /boxes/{box}/artifacts/{name}[/{version}] |
moor:read |
The artifact’s bytes, with its Content-Type and an ETag of its sha256. |
| Status | When |
|---|---|
| 401, 403 | No valid token, or a token without the scope. |
| 404 | No such Box, artifact name, or version. |
| 409 | The stored bytes do not match their sha256. |
| 410 | The artifact is recorded but its bytes are gone. |
Box resources
Each open Box is the resource moor://box/<name>. resources/read returns the
box_status JSON.
A client on MCP 2026-07-28 can call subscriptions/listen once and keep the
stream open. It needs no initialize. Each POST carries
MCP-Protocol-Version: 2026-07-28, Mcp-Method, and, for resources/read,
Mcp-Name. params._meta carries the protocol version, clientInfo, and
clientCapabilities.
{"jsonrpc": "2.0", "id": 7, "method": "subscriptions/listen", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": {"name": "me", "version": "1"}, "io.modelcontextprotocol/clientCapabilities": {} }, "notifications": { "resourcesListChanged": true, "resourceSubscriptions": ["moor://box/app/fix-login"] }}}A state change of a listed Box sends notifications/resources/updated with its
URI. A Box that starts, closes, or is deleted sends
notifications/resources/list_changed. Read the resource to see what changed.
Events while no stream is open are not replayed. The gate sends an SSE comment
every 15 s.