MCP

ZeroClaw is an MCP client: it connects to external Model Context Protocol servers and exposes their tools to the agent. Each MCP tool is namespaced as <server>__<tool> (for example filesystem__read_file), so tools from different servers never collide.

Enable MCP

MCP is off by default. Set mcp.enabled = true, then add one entry per server under mcp.servers. Configure through the gateway, zerocode, or zeroclaw config set:

zeroclaw config set mcp.enabled true

Transports

A server is reached over one of three transports (the transport field):

Transport	When to use	Required fields
`stdio` (default)	A local process you spawn (a Node.js or Python MCP server)	`command`, optional `args`, `env`
`http`	A remote server speaking MCP over HTTP POST	`url`, optional `headers`
`sse`	A remote server speaking MCP over HTTP + Server-Sent Events	`url`, optional `headers`

env (stdio) and headers (http/sse) are stored as secrets; headers commonly carries the Authorization: Bearer … token for the upstream server.

Add a server through the gateway, zerocode, or zeroclaw config set (for example zeroclaw config set mcp.servers.filesystem.command npx). A stdio server needs command plus optional args/env; an http/sse server needs url plus optional headers. The per-field commands are in the field table below.

Server fields

Per-server fields ([[mcp.servers]]), generated from the schema:

args string[] · default []

Command arguments for stdio transport.

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.args field.

zerocode

In the Config pane, set the mcp.servers.args field.

zeroclaw config

zeroclaw config set mcp.servers.args <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__args=

command string · default ""

Executable to spawn for stdio transport.

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.command field.

zerocode

In the Config pane, set the mcp.servers.command field.

zeroclaw config

zeroclaw config set mcp.servers.command <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__command=

env 🔑 secret · default {}

Optional environment variables for stdio transport.

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.env field.

zerocode

In the Config pane, set the mcp.servers.env field.

zeroclaw config

zeroclaw config set mcp.servers.env    # masked input, stored encrypted

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__env=

headers 🔑 secret · default {}

Optional HTTP headers for HTTP/SSE transports. Treated as secret: the values commonly carry Bearer tokens for the upstream MCP server.

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.headers field.

zerocode

In the Config pane, set the mcp.servers.headers field.

zeroclaw config

zeroclaw config set mcp.servers.headers    # masked input, stored encrypted

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__headers=

name string · default ""

Display name used as a tool prefix (<server>__<tool>). Filled in from the supplied map_key when the entry is created via create_map_key("mcp.servers", "<name>"); #[serde(default)] lets the macro default-construct from {} before the name gets injected.

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.name field.

zerocode

In the Config pane, set the mcp.servers.name field.

zeroclaw config

zeroclaw config set mcp.servers.name <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__name=

tool_timeout_secs integer? · default null

Optional per-call timeout in seconds (hard capped in validation).

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.tool_timeout_secs field.

zerocode

In the Config pane, set the mcp.servers.tool_timeout_secs field.

zeroclaw config

zeroclaw config set mcp.servers.tool_timeout_secs <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__tool_timeout_secs=

transport McpTransport · default "stdio"

Transport type (default: stdio).

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.transport field.

zerocode

In the Config pane, set the mcp.servers.transport field.

zeroclaw config

zeroclaw config set mcp.servers.transport <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__transport=

url string? · default null

URL for HTTP/SSE transports.

Set it on any surface:

Gateway dashboard

Open /config/mcp.servers and set the mcp.servers.url field.

zerocode

In the Config pane, set the mcp.servers.url field.

zeroclaw config

zeroclaw config set mcp.servers.url <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers__url=

tool_timeout_secs is an optional per-call timeout; it must be greater than 0 and is capped at 600 seconds.

Top-level fields

deferred_loading bool · default true

Load MCP tool schemas on-demand via tool_search instead of eagerly including them in the LLM context window. When true (the default), only tool names are listed in the system prompt; the LLM must call tool_search to fetch full schemas before invoking a deferred tool.

Set it on any surface:

Gateway dashboard

Open /config/mcp and set the mcp.deferred_loading field.

zerocode

In the Config pane, set the mcp.deferred_loading field.

zeroclaw config

zeroclaw config set mcp.deferred_loading <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__deferred_loading=

servers McpServerConfig[] · default []

Configured MCP servers. The #[nested] annotation makes the macro expose this as a List section in map_key_sections(), so the dashboard’s + Add MCP server affordance and the POST /api/config/map-key?path=mcp.servers&key=<name> endpoint pick it up automatically (no hand-table on the gateway side).

Set it on any surface:

Gateway dashboard

Open /config/mcp and set the mcp.servers field.

zerocode

In the Config pane, set the mcp.servers field.

zeroclaw config

zeroclaw config set mcp.servers <value>

Environment variable

Export the override (POSIX shells; drop into ~/.bashrc, ~/.zshrc, .env, or a Dockerfile). Replace <alias> with the literal alias:

export ZEROCLAW_mcp__servers=

Deferred loading

mcp.deferred_loading is true by default. With it on, only MCP tool names are placed in the system prompt; the LLM calls the built-in tool_search tool to fetch a tool’s full schema before invoking it. This keeps the initial context window small when a server exposes many tools. Set it to false to eagerly include every MCP tool’s full schema up front.

Security and approval

MCP tool calls go through the same approval gate as every other tool, governed by the agent’s risk profile (risk_profiles.<alias>):

At autonomy level = full, no tool call prompts (MCP tools included).
Otherwise, an MCP tool call prompts for approval unless its prefixed name (<server>__<tool>) is in the profile’s auto_approve list. auto_approve = ["*"] approves everything; an exact entry like auto_approve = ["filesystem__read_file"] approves just that tool.
always_ask is the inverse: a name (or "*") there always prompts, overriding auto_approve.

See Autonomy levels for the full per-profile field surface, and the Config reference for every MCP field and default.

Keyboard shortcuts

ZeroClaw Docs