MCP server
rho mcp serve turns Rho into a Model Context Protocol server. Another agent, such as Claude Code, Codex, or a Rho session, can then start Rho sessions in any workspace, follow their turns, and read their answers. The sessions run in the daemon, which the server starts if needed.
The server speaks stdio by default. For hosts that connect by URL, use --http. A Rho agent gets the same tools through its sessions tool.
Tools
| Tool | What it does | Access |
|---|---|---|
list | Lists sessions with their id, workspace, state, and parent session. Filter by workspace or state. | read |
read | Returns a session's transcript as text, a page at a time. | read |
new | Starts a session in workspace (an absolute path) with a first prompt. Optional agent and model. worktree: true runs it in a new git worktree. | write |
prompt | Starts the session's next turn with text. | write |
steer | Sends text to the running turn. | write |
cancel | Stops the turn in progress. | write |
wait | Waits for the turn to end or ask for input. See Following a turn. | read |
watch | HTTP only. POSTs the session's news to a webhook until it settles. Returns where the session is now, as wait does. | read |
unwatch | HTTP only. Stops watching the session. | read |
Over HTTP, new and prompt also take notify, a webhook name, to watch the session from that turn on.
Over stdio the host has write access unless you start the server read-only. Over HTTP each token has read or write access.
Following a turn
new and prompt return as soon as the turn starts. wait follows the session, and returns when it settles, with no turn running and none rho will start for its background work, when it needs a person, or after timeout_secs (30 by default, at most 50). A session the TUI opened ends its turn while a subagent runs and starts a turn of its own to deliver the result; wait returns that turn's outcome:
{
"session": "8c1e…",
"state": "completed",
"done": true,
"outcome": {"type": "answered", "text": "…", "stop": "end_turn"},
"cursor": "4f0a…:42"
}- If
doneis false, a turn is still running, or the last one ended but background work is still due, such as a subagent or task whose result rho will deliver in a turn of its own. Callwaitagain with the returnedcursor. outcomeis how the last turn ended, present once it ended even whiledoneis false. It is final oncedoneis true; until then a later turn, such as the one that delivers a result, may replace it.outcome.textis the final answer.readreturns the whole conversation.inputslists the approvals or questions the turn waits on. A subagent's question stopswaittoo, even with no turn running.turnis the turnstateis of.
Approvals stay with people
No tool answers a session's approvals or questions. When a turn asks for one, wait returns with done: true, state: "waiting_for_input", and the request in inputs. A person answers it from rho attach <session> or the TUI, and the next wait follows the turn from there.
To let a session work unattended, give it a permission mode that does not ask, as you would for rho run.
Limits
Sessions can start sessions, so the server checks two budgets on every new and prompt:
- Session depth. A session started by a person or an outside agent is depth 1, a session it starts is depth 2, and so on.
--max-depthsets the limit, 3 by default. - Concurrent sessions. Each caller may run
--max-sessionssessions at once, 10 by default. Each HTTP token is a separate caller. A session counts until its turn ends, including time waiting for a person.
Over HTTP, each token may also watch --max-watches sessions at once: unless set, 5 × --max-sessions (50 by default). A watch counts until its news is delivered or it is removed, including while it is stopped on an error. rho mcp webhook list shows each token's count against the limit.
A request past a budget is refused with the budget, its limit, and the value asked for:
session depth budget: limit 3, asked 4; a session at depth 3 may not start or prompt another
concurrent sessions budget for token "ci": limit 10, asked 11
session watches budget for token "ci": limit 50, asked 51These limits stop runaway recursion. They are not a sandbox, since a session with a shell can reach the daemon directly.
Sessions' environment
Sessions get the server's environment, including its PATH, as if you started them from the server's shell. Under a service manager that is the service's environment; see Running as a service.
Registering over stdio
The host starts rho mcp serve itself. If the host does not inherit your shell's PATH, give it the full path to rho.
Claude Code:
claude mcp add --transport stdio rho -- rho mcp serveCodex, in ~/.codex/config.toml:
[mcp_servers.rho]
command = "rho"
args = ["mcp", "serve"]Rho, in ~/.rho/config.toml, so one Rho session can drive others:
[mcp.servers.rho]
transport = "stdio"
command = "rho"
args = ["mcp", "serve"]A Rho host starts stdio servers with a sanitized environment, and the sessions this server starts inherit it. List any variables their tools need in env_from_env.
Add --max-depth or --max-sessions after serve to change the limits.
Read-only over stdio
Add --scope read for a host that should watch sessions but never start or change one:
claude mcp add --transport stdio rho-watch -- rho mcp serve --scope readThe write tools are refused:
this server's caller has read access; `new` needs write--scope write is the default. --scope does not work with --http, where each token carries its own scope.
Over HTTP
rho mcp serve --http 127.0.0.1:8765The server prints its URL, http://127.0.0.1:8765/mcp, on stderr. Port 0 picks a free port.
It binds only to a loopback address. To reach it from another machine, use a tunnel such as an SSH forward. Running as a service has a systemd unit and a launchd agent that keep it running.
Tokens
Every HTTP request needs a bearer token. Create one and name the workspaces it may reach:
rho mcp token rotate laptop --scope write --workspace ~/src/app --workspace ~/src/librotate prints the secret once on stdout. Rho keeps only a hash of it, in your credential store. Clients send it as Authorization: Bearer <secret>.
--scope read, the default, allowslist,read, andwait.--scope writealso allowsnew,prompt,steer, andcancel.--workspacegrants a directory and everything under it. A new token needs at least one. The token cannot see or touch sessions anywhere else.- Running
rotateon an existing token issues a new secret. It keeps the token's scope and workspaces unless you pass new ones.
rho mcp token list # names, scopes, and workspaces; --json for JSON
rho mcp token revoke laptop # reject further requests with this tokenRotations and revokes apply from the next request, without a restart. They do not stop work already in progress. A request with a missing or unknown token gets 401 Unauthorized.
Token scope
A turn that a token starts or prompts runs with the token's scope and workspaces. Any rho mcp serve the session calls holds it to that scope too. A session the token started keeps that limit for good, so a person who prompts it later does not give it their own access.
Like the limits, this is not a sandbox. A write token can also steer a turn someone else started.
Hosts and origins
The server accepts requests whose Host is localhost, 127.0.0.1, or ::1. Behind a tunnel that keeps the public hostname, allow that name:
rho mcp serve --http 127.0.0.1:8765 --allow-host mcp.example.comRequests with an Origin header get 403 Forbidden unless --allow-origin names the origin, so a web page cannot drive the server. Non-browser MCP hosts send no Origin. Both flags can be repeated.
Registering by URL
These examples assume the token's secret is in RHO_MCP_TOKEN.
Claude Code:
claude mcp add --transport http rho https://mcp.example.com/mcp \
--header "Authorization: Bearer $RHO_MCP_TOKEN"Codex, in ~/.codex/config.toml:
[mcp_servers.rho]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "RHO_MCP_TOKEN"Rho, in ~/.rho/config.toml (see Streamable HTTP servers), with RHO_MCP_AUTHORIZATION="Bearer <secret>" in Rho's environment:
[mcp.servers.rho]
transport = "streamable_http"
url = "https://mcp.example.com/mcp"
headers_from_env = { Authorization = "RHO_MCP_AUTHORIZATION" }Webhooks
An HTTP server can POST to a webhook when a session has news, so a remote host such as a bot routine does not have to keep calling wait. Grok Bot walks through a full setup. Add a target, bound to the tokens that may use it, with its bearer secret on stdin:
printf %s "$ROUTINE_KEY" | rho mcp webhook add grok --url https://example.com/hooks/abc --token grok
rho mcp webhook list # targets, last delivery, stalled watches, each token's watch count; --json for JSON
rho mcp webhook remove grok--urlmust behttps, orhttpto a loopback host, with no user name or password in it.--tokencan be repeated. A token can use only the targets bound to it. Runningaddagain replaces the target.- The secret is kept in your credential store. No list, tool result, or log shows it.
Then a caller with a token watches a session with watch, or with notify on the new or prompt that starts its turn:
{"workspace": "/home/me/src/app", "prompt": "Fix the flaky test", "notify": "grok"}The server POSTs to the target's URL with Authorization: Bearer <secret> and Content-Type: application/json. The body is what wait would return, plus server, the server's --name, which defaults to the host name:
{"server": "lab-box", "session": "8c1e…", "state": "completed", "done": true, "turn": "…", "outcome": {"type": "answered", "text": "…", "stop": "end_turn"}, "cursor": "4f0a…:42"}What fires:
- Each time the session stops for a person, with
state: "waiting_for_input"and the requests ininputs. - Once when the session settles, with no turn running and none rho will start for its background work. That ends the watch. To hear about the next turn, pass
notifyto thepromptthat starts it. - If the session already settled when you call
watch, the answer is the news: it returnswatching: falseand nothing is POSTed. If it is waiting for a person, the answer is that news, and it is not POSTed again.
Once new or prompt with notify has started the turn, the call succeeds even if the watch could not be set up, so a retry never starts the turn twice. Such a result has watch_error saying what went wrong; watch and unwatch report a watch they could not save the same way.
Only watched sessions fire. A turn a person starts from the TUI on a session nobody watches, or whose watch already delivered, sends nothing.
Delivery happens at least once, so the same news can arrive twice. To skip a repeat, compare turn, state, and the ids in inputs with news you already handled: the waiting_for_input news and the settle of one turn share its turn.
A timeout, a network error, 408, 429, or a 5xx is retried, 2 seconds later, then at gaps doubling up to 10 minutes. That is at most 15 attempts for one piece of news: 10 in the first 17 minutes of gaps, then one every 10 minutes (at most 6 an hour), the last after about 67 minutes of gaps. Those times count the gaps alone: each attempt can also take up to 30 seconds before it times out, so a receiver that never answers is given up on about 75 minutes after the first attempt, plus the server's own checks before each attempt. Any other answer, including a redirect, stops the watch at once. Redirects are never followed. rho mcp webhook list shows the last delivery of each target and the error of each watch that stopped. Restarting the server, or watching the session again, retries a stopped watch.
Watches survive a server restart, in mcp-serve/watches.json in the rho home (~/.rho by default). News that came while the server was down is sent when it starts again; the server starts the rho daemon then if it is not running, so a turn a reboot interrupted is reported too. After that, a watch never starts the daemon: if you stop it, the watch stops with an error until the server restarts or the session is watched again. One server per rho home keeps the watches; a second one serves the other tools, does not offer watch, unwatch, or notify, and refuses them.
Security:
- A caller names only a target. Its URL and secret come from
rho mcp webhook add, so a token holder cannot make the server POST anywhere else. - Before every POST the server checks again that the token exists, the target is still bound to it, and the session is in the token's workspaces. If not, it drops the watch without POSTing.
- The body carries final answers and approval summaries, including paths and commands, to the target.
- If the target is a paid bot routine, each POST is a billed run, including each approval a person has to answer.