Skip to content

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 ​

ToolWhat it doesAccess
listLists sessions with their id, workspace, state, and parent session. Filter by workspace or state.read
readReturns a session's transcript as text, a page at a time.read
newStarts 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
promptStarts the session's next turn with text.write
steerSends text to the running turn.write
cancelStops the turn in progress.write
waitWaits for the turn to end or ask for input. See Following a turn.read
watchHTTP only. POSTs the session's news to a webhook until it settles. Returns where the session is now, as wait does.read
unwatchHTTP 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:

json
{
  "session": "8c1e…",
  "state": "completed",
  "done": true,
  "outcome": {"type": "answered", "text": "…", "stop": "end_turn"},
  "cursor": "4f0a…:42"
}
  • If done is 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. Call wait again with the returned cursor.
  • outcome is how the last turn ended, present once it ended even while done is false. It is final once done is true; until then a later turn, such as the one that delivers a result, may replace it.
  • outcome.text is the final answer. read returns the whole conversation.
  • inputs lists the approvals or questions the turn waits on. A subagent's question stops wait too, even with no turn running.
  • turn is the turn state is 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-depth sets the limit, 3 by default.
  • Concurrent sessions. Each caller may run --max-sessions sessions 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:

text
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 51

These 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:

bash
claude mcp add --transport stdio rho -- rho mcp serve

Codex, in ~/.codex/config.toml:

toml
[mcp_servers.rho]
command = "rho"
args = ["mcp", "serve"]

Rho, in ~/.rho/config.toml, so one Rho session can drive others:

toml
[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:

bash
claude mcp add --transport stdio rho-watch -- rho mcp serve --scope read

The write tools are refused:

text
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 ​

bash
rho mcp serve --http 127.0.0.1:8765

The 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:

bash
rho mcp token rotate laptop --scope write --workspace ~/src/app --workspace ~/src/lib

rotate 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, allows list, read, and wait. --scope write also allows new, prompt, steer, and cancel.
  • --workspace grants a directory and everything under it. A new token needs at least one. The token cannot see or touch sessions anywhere else.
  • Running rotate on an existing token issues a new secret. It keeps the token's scope and workspaces unless you pass new ones.
bash
rho mcp token list           # names, scopes, and workspaces; --json for JSON
rho mcp token revoke laptop  # reject further requests with this token

Rotations 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:

bash
rho mcp serve --http 127.0.0.1:8765 --allow-host mcp.example.com

Requests 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:

bash
claude mcp add --transport http rho https://mcp.example.com/mcp \
  --header "Authorization: Bearer $RHO_MCP_TOKEN"

Codex, in ~/.codex/config.toml:

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:

toml
[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:

bash
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
  • --url must be https, or http to a loopback host, with no user name or password in it.
  • --token can be repeated. A token can use only the targets bound to it. Running add again 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:

json
{"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:

json
{"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 in inputs.
  • 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 notify to the prompt that starts it.
  • If the session already settled when you call watch, the answer is the news: it returns watching: false and 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.