nanoclaw MCP server (container/agent-runner/src/mcp-tools/), so the agent sees them with the mcp__nanoclaw__ prefix — e.g. mcp__nanoclaw__send_message. As an operator you never call them directly; you see their effects: messages arriving in chats, schedule changes, and approval cards.
Each tool module ships with an instructions file that’s composed into the agent’s CLAUDE.md, telling it when and how to use the tools. Per-group MCP servers from the container config add more tools alongside these, under their own prefixes.
These tools write to the container’s outbound database — the host reads, authorizes, and applies the effects. Approval gating happens host-side; the container is untrusted and never gates itself.
Core messaging
Outbound tools resolveto against the group’s destination map — a unified namespace covering both channels (chats the group is wired to) and agents (sub-agents created with create_agent). to is required: every send_message and send_file call names its destination explicitly.
send_message
Used for mid-turn updates while the agent is still working — final responses go through
<message> blocks in the agent’s output, not this tool. Sending to another agent is the same call with to set to the agent’s name.
send_file
Copies the file to
/workspace/outbox/<id>/ for the host to deliver. Fails if the file doesn’t exist.
edit_message
Targets the same destination the original message went to — the routing is looked up from the sent-message record.
add_reaction
Lightweight acknowledgment when a full reply would be noise.
Scheduling
Scheduling is no longer an MCP tool. Theschedule_task, list_tasks, update_task, cancel_task, pause_task, and resume_task tools were removed. Scheduling now lives in the ncl admin CLI as the tasks resource — the agent runs ncl tasks create | list | get | run | update | pause | resume | cancel | delete through the same CLI it already uses for group config. See the ncl tasks reference and Setting up scheduled tasks.
Interactive
ask_user_question
Blocking — the agent’s turn pauses while it polls for your answer. You see a question card with buttons; tapping one returns its
value to the agent (selectedLabel replaces the button text after selection). Errors out if the timeout expires.
send_card
Non-blocking — renders the card and returns immediately, with no response collected. Actions are link buttons only: each needs a non-empty
label and an HTTP or HTTPS url. Invalid actions, including callback buttons, #, relative paths, mailto: and tel: links, are dropped; the tool result reports the dropped count. style can be primary, danger, or default; unrecognized styles render as default.
children accepts strings or objects with a text field. Nested action blocks are unsupported. Use ask_user_question for choices that must return a value to the agent. fallbackText supplies a text rendering for channels that need one; it does not enable callback buttons.
Agents
create_agent
Provisions a long-lived companion agent: its own group, container, and persistent workspace under
groups/<folder>/, wired bidirectionally as a destination on both sides. Fire-and-forget — the call returns immediately and messages queue until the agent is up.
Approval-gated by CLI scope: groups with cli_scope: global create directly; everything else (including the default group scope) requires admin approval. There is no send_to_agent tool — messaging an agent is just send_message with to set to its name. See Agent swarms.
Self-modification
Both tools are always approval-gated and fire-and-forget: the request is submitted, an admin gets an approval card, and the agent is notified of the outcome via a system message. Package names are sanitized in the container and re-validated on the host.install_packages
*At least one apt or npm package required; max 20 per request. On approval the per-agent image is rebuilt and the container restarts — packages persist across all future sessions, unlike a workspace
pnpm install.
add_mcp_server
Exactly one of
command or url is required. A url must be HTTPS — plain HTTP passes only for localhost, 127.0.0.1, [::1], and host.docker.internal — and URLs that embed credentials (userinfo, fragments, or credential-looking query parameters) are rejected with a pointer to OneCLI for authentication. On approval the server is added to the group’s container config and the container restarts (no image rebuild needed). The agent is instructed to use "onecli-managed" as the placeholder for credential env vars rather than asking you for keys.
The ncl CLI
Not an MCP tool, but documented alongside them in the agent’s instructions: the agent also has the ncl admin CLI at /usr/local/bin/ncl for querying and modifying NanoClaw’s central configuration — its own group config, destinations, members, sessions, and the wiring for the current chat (wirings get/update — updates limited to engage_mode and engage_pattern, and approval-gated like other writes). Read commands are open; write commands return approval-pending and execute only after an admin approves. What it can reach is controlled by the group’s cli_scope — see the ncl CLI reference.