MCP Tool Reference
Every tool the actor.sh MCP server exposes to the main session, its parameters, and its behaviour.
The complete MCP tool surface. The main session drives the other sessions
through these tools, exposed by actor.sh's MCP server (each appears to the
agent as mcp__actor__<name>). Every tool maps to the same operation as the
matching CLI command.
Background runs are asynchronous: when a session finishes a turn, the
completion arrives as a notifications/claude/channel notification rather than
as the tool's return value — so main reacts to events instead of polling.
list_sessions
List sessions and their status.
| Parameter | Meaning |
|---|---|
status | Optional filter: working / idle / stopped |
show_session
Show details (workspace, agent, config, status, timestamps) for one session.
| Parameter | Meaning |
|---|---|
name | Session name (required) |
host | Trusted remote host — EndpointId or name (see Remote Hosts) |
new_session
Create a new session; if prompt is supplied, also fire an immediate
background run, whose completion arrives over the channel.
| Parameter | Meaning |
|---|---|
name | Session name (required) |
prompt | Seed task; also starts the session |
agent | Agent to run (claude / codex) |
role | Apply a role |
dir | Base directory for the worktree (absolute) |
base | Branch to fork the worktree from |
no_worktree | Run in dir directly, no worktree |
use_subscription | Subscription vs. API-key auth |
host | Run on a trusted remote host — EndpointId or name |
run_session
Send a prompt to an existing session. Returns immediately; the session runs in the background and each finished turn arrives as a channel notification. If the session is mid-turn, the prompt is queued behind the current turn — not an error.
| Parameter | Meaning |
|---|---|
name | Session name (required) |
prompt | Prompt to send (required) |
host | Trusted remote host — EndpointId or name |
stop_session
Interrupt the session's current turn. Keeps the agent alive; a channel event
with status=stopped follows.
| Parameter | Meaning |
|---|---|
name | Session name (required) |
host | Trusted remote host — EndpointId or name |
discard_session
Discard a session: delete its definition and remove its worktree (the branch is kept).
| Parameter | Meaning |
|---|---|
name | Session name (required) |
force | Bypass a failing on-discard hook |
host | Trusted remote host — EndpointId or name |
logs_session
Read a session's transcript — user/assistant text, tool calls (name + args), and tool results, in order. Works for both Claude and Codex sessions.
| Parameter | Meaning |
|---|---|
name | Session name (required) |
tail | Show only the last N messages (default: all) |
list_servers
List this daemon (with its EndpointId) and the peers it trusts, each with its connection state. Use it to read your own EndpointId. No parameters.
trust_peer
Trust a peer daemon. Trust is mutual: sessions cross only once the peer trusts this daemon back.
| Parameter | Meaning |
|---|---|
peer | The peer's EndpointId (64 hex — its iroh public key, confirmed out of band) or, for a peer already listed, its name |
name | Optional friendly label for the peer (defaults to peer-<prefix>) |
untrust_peer
Remove a peer from the local trust store. Less sensitive than trust_peer —
removal can't be spoofed.
| Parameter | Meaning |
|---|---|
peer | The peer's EndpointId or its name |
list_roles
List roles defined in ~/.actor/settings.kdl and <cwd>/.actor/settings.kdl.
No parameters.
daemon_status
Local daemon liveness, version, and pid. Daemon lifecycle (start/stop/restart) is CLI-only — stopping it would tear down the MCP connection mid-call. No parameters.