MCP

ZeroClaw 是一个 MCP 客户端：它连接到外部 Model Context Protocol 服务器，并将其工具暴露给智能体。每个 MCP 工具都以 <server>__<tool> 形式进行命名空间隔离（例如 filesystem__read_file），因此来自不同服务器的工具绝不会发生冲突。

配置 MCP

MCP 支持默认已启用，但在 mcp.servers 下至少配置一个服务器，并且通过其 mcp_bundles 将该服务器授予某个代理之前，不会暴露任何外部 MCP 工具（参见下文的按代理服务器作用域）。可通过网关、zerocode 或 zeroclaw config set 配置：

zeroclaw config set mcp.servers.filesystem.command npx

将 mcp.enabled = false 设置为禁用 MCP 工具加载，无需移除服务器定义。

按代理划分的服务器作用域（`mcp_bundles`）

一个 [[mcp.servers]] 条目只会定义一个服务器。某个 agent 实际连接哪些服务器，由该 agent 的 agents.<alias>.mcp_bundles 决定，而且模型默认是安全的：省略不代表授予。

即使 mcp.servers 非空，没有 mcp_bundles 的代理也不会连接到任何 MCP 服务器。
一个 bundle [mcp_bundles.<alias>] 通过其 mcp.servers 的 name 来命名它授予的服务器，并可带有可选的 exclude 列表。某个 agent 的授权是其引用的每个 bundle 所包含服务器的并集，再减去这些 bundle 中任一者排除的任何名称（deny 优先）。
未知的 bundle 别名，或与任何已配置服务器都不匹配的 bundle 服务器名称，都不会授予任何权限。两者都会按失败即拒绝处理，并且在配置校验中作为非致命警告报告，因此，拼写错误会缩小 agent 的访问范围，而不是扩大它。

[[mcp.servers]]
name = "filesystem"
command = "npx"

[mcp_bundles.files]
servers = ["filesystem"]

[agents.assistant]
mcp_bundles = ["files"]   # 连接到 `filesystem`；没有这个的 agent 不会获得任何 MCP servers

捆绑更改会在会话重启时生效。解析器（Config::mcp_servers_for_agent）在会话/代理构建时运行；在会话处于活动状态时编辑 [mcp_bundles.*] 或 agents.<alias>.mcp_bundles 不会更改该会话已连接的服务器。结束并重启受影响的会话以获取新的授权。

这是 connection 边界（也就是代理会与之通信的所有服务器）。下面的 allowed_tools / excluded_tools 控制是在已授权服务器所暴露内容之上的、按工具划分的 capability 边界。

传输

服务器通过三种传输方式之一进行访问（transport 字段）：

传输	何时使用	必填字段
`stdio`（默认）	你生成的本地进程（Node.js 或 Python MCP 服务器）	`command`、可选的 `args`、`env`
`http`	一个通过 HTTP POST 使用 MCP 通信的远程服务器	`url`，可选的 `headers`
`sse`	通过 HTTP + Server-Sent Events 进行 MCP 通信的远程服务器	`url`，可选的 `headers`

env（stdio）和 headers（http/sse）作为密钥存储；headers 通常携带用于上游服务器的 Authorization: Bearer … 令牌。

通过网关、zerocode 或 zeroclaw config set 添加服务器（例如 zeroclaw config set mcp.servers.filesystem.command npx）。stdio 服务器需要 command 以及可选的 args/env；http/sse 服务器需要 url 以及可选的 headers。各字段对应的命令请参见下方字段表。

编辑服务器

三个界面编辑同一个 [[mcp.servers]] 表：

config.toml：手动编辑下方所述的键。完整的表会在保存时往返写回。
zerocode TUI（/config -> mcp.servers）：一流的逐字段编辑器。该部分为每个服务器显示一行，并以服务器的 name 标注；进入某一行即可将 transport、command / url、headers、env 和 tool_timeout_secs 作为独立字段进行编辑。+ Add 会创建一个以你提供的名称为初始值的新条目；从别名列表中删除则会移除该条目。name 字段不支持内联编辑，因为在编辑过程中重命名这一自然键会使进行中的引用失效；目前如需重命名，请使用仪表板或手动编辑 config.toml。
Web 仪表板：目前通过 JSON 数组编辑器渲染 mcp.servers。计划迁移到 TUI 所使用的同一逐字段界面；在此之前，仪表板仍是一个可用但较为粗糙的编辑器。

服务器字段

从 schema 生成的各服务器字段（[[mcp.servers]]）：

args string[] · default []

stdio 传输的命令参数。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.args 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.args 字段。

zeroclaw config

zeroclaw config set mcp.servers.args <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__args=

command string · default ""

用于 stdio 传输的可执行文件。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.command 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.command 字段。

zeroclaw config

zeroclaw config set mcp.servers.command <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__command=

env 🔑 secret · default {}

stdio 传输的可选环境变量。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.env 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.env 字段。

zeroclaw config

zeroclaw config set mcp.servers.env    # 掩码输入，加密存储

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__env=

headers 🔑 secret · default {}

用于 HTTP/SSE 传输的可选 HTTP 标头。视为机密：这些值通常携带用于上游 MCP 服务器的 Bearer 令牌。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.headers 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.headers 字段。

zeroclaw config

zeroclaw config set mcp.servers.headers    # 掩码输入，加密存储

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__headers=

max_response_bytes integer? · default null

在读取时强制执行的单个 HTTP/SSE JSON-RPC 响应正文可接受的最大字节数，此时正文尚未被解析，也未对其中嵌入的资源进行实例化。遭到入侵或行为异常的服务器无法强制分配无界的响应正文。这是_编码后的网络传输_上限，而不是解码后的实例化预算：None/0 使用内置默认值 16,078,168 字节；该值经过设置，可确保完整的 10 MiB 解码后嵌入资源 blob（其 base64 扩展部分加上 JSON-RPC 包络开销）仍能容纳。另一个 10 MiB 数值是解析后应用的解码后聚合 blob 预算，而不是此网络传输上限。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers，并设置 mcp.servers.max_response_bytes 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.max_response_bytes 字段。

zeroclaw config

zeroclaw config set mcp.servers.max_response_bytes <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__max_response_bytes=

name string · default ""

用作工具前缀的显示名称（<server>__<tool>）。当通过 create_map_key("mcp.servers", "<name>") 创建条目时，会从提供的 map_key 填充；#[serde(default)] 让宏在名称注入之前先从 {} 默认构造。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.name 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.name 字段。

zeroclaw config

zeroclaw config set mcp.servers.name <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__name=

pinned_resources string[] · default []

在代理启动时读取一次并注入到系统提示中的资源 URI，作为不可信的、来自服务器的上下文。每个 URI 都通过此服务器上的 resources/read 读取；如果某个 pin 位于不支持声明资源的服务器上，或者该代理的工具策略拒绝了该服务器，则会跳过并给出警告。每次运行只读取一次（不会刷新；也没有订阅）。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.pinned_resources 字段。

zerocode

在 Config 面板中，设置 mcp.servers.pinned_resources 字段。

zeroclaw config

zeroclaw config set mcp.servers.pinned_resources <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__pinned_resources=

tls_ca_cert_path string? · default —

用于此服务器 HTTP/SSE 传输的 PEM 编码 CA 证书或证书包的绝对路径，除默认根证书外还将信任该证书或证书包。证书和主机名验证仍处于启用状态。该路径必须指向大小不超过 1 MiB 的普通文件；文件缺失、无法读取、为空、过大、不是普通文件或无效时，将直接导致连接错误，而不会回退到默认信任存储。设置后，配置的 URL 和任何公布的 SSE 消息端点都必须使用 HTTPS；明文 URL 和降级重定向会被拒绝。stdio 不使用此设置。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.tls_ca_cert_path 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.tls_ca_cert_path 字段。

zeroclaw config

zeroclaw config set mcp.servers.tls_ca_cert_path <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__tls_ca_cert_path=

tool_timeout_secs integer? · default null

每次调用的可选超时时间（以秒为单位，在校验时设有硬性上限）。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.tool_timeout_secs 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.tool_timeout_secs 字段。

zeroclaw config

zeroclaw config set mcp.servers.tool_timeout_secs <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__tool_timeout_secs=

transport McpTransport · default "stdio"

传输类型（默认：stdio）。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.transport 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.transport 字段。

zeroclaw config

zeroclaw config set mcp.servers.transport <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__transport=

url string? · default null

HTTP/SSE 传输的 URL。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp.servers 并设置 mcp.servers.url 字段。

zerocode

在 Config 窗格中，设置 mcp.servers.url 字段。

zeroclaw config

zeroclaw config set mcp.servers.url <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers__url=

tool_timeout_secs 是一个可选的单次调用超时时间；它必须大于 0，且上限为 600 秒。

自定义 CA 信任

对于证书由私有 CA 签发的 HTTP 或 SSE 服务器，请将 tls_ca_cert_path 设置为包含一个或多个 PEM 编码 CA 证书的绝对路径。配置的证书会添加到默认信任存储；证书链、过期时间和主机名验证仍保持启用状态。

相对路径、缺失、不可读、为空、过大、非普通文件或无效的 CA 文件，对于该服务器而言都是不可恢复的连接错误。该路径解析后必须指向不超过 1 MiB 的普通文件。系统会跟随符号链接，因此证书轮换以及通过符号链接发布证书包的挂载 secret 布局都能按配置工作；解析后的文件会在打开后进行验证，解析到目录、设备或 FIFO 的符号链接会被拒绝。设置此字段后，ZeroClaw 绝不会禁用验证或静默回退。配置的服务器 URL 以及 SSE 服务器公布的任何消息端点都必须使用 https://；在发送请求标头或内容之前，明文 URL 和降级重定向都会被拒绝。此值会在 MCP 会话启动时应用；更改后请重启受影响的会话。删除该字段并重启会话即可恢复使用默认信任存储。Stdio 服务器会忽略此设置。

顶级字段

deferred_loading bool · default false

通过 tool_search 按需加载 MCP 工具 schema，而非急切地将其包含在 LLM 上下文窗口中。启用后，系统提示中仅列出工具名称；LLM 必须先调用 tool_search 获取完整 schema，然后才能调用延迟加载的工具。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp 并设置 mcp.deferred_loading 字段。

zerocode

在 Config 窗格中，设置 mcp.deferred_loading 字段。

zeroclaw config

zeroclaw config set mcp.deferred_loading <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__deferred_loading=

servers McpServerConfig[] · default []

已配置的 MCP 服务器。#[nested] 注解使宏在 map_key_sections() 中将其暴露为一个 List 部分，因此控制面板的 + Add MCP server 操作和 POST /api/config/map-key?path=mcp.servers&key=<name> 端点会自动识别它（网关侧无需手动维护表）。#[natural_key = "name"] 使该 Vec 启用按元素属性路由（参见 route_vec_path 和 Configurable derive 的 #[natural_key] 分支）。有了它，set_prop("mcp.servers.<name>.url", ...) 和 get_prop("mcp.servers.<name>.transport") 会解析到对应元素自身的 set_prop / get_prop，并且从控制面板 / TUI 的视角来看，mcp.servers 部分的行为就像一个 HashMap<String, McpServerConfig>。name 本身通过 set_prop 变为只读；重命名经由 rename_map_key 处理，它会就地修改 name 字段。

将它放置在任何表面上：

网关仪表板

打开 /config/mcp 并设置 mcp.servers 字段。

zerocode

在 Config 窗格中，设置 mcp.servers 字段。

zeroclaw config

zeroclaw config set mcp.servers <value>

环境变量

导出此覆盖配置（POSIX shell；可放入 ~/.bashrc、~/.zshrc、.env 或 Dockerfile 中）。将 <alias> 替换为实际的别名：

export ZEROCLAW_mcp__servers=

延迟加载

mcp.deferred_loading 默认为 false，因此已配置的 MCP 工具会被预先加载到模型上下文中。将其设置为 true 可仅将 MCP 工具的名称放入系统提示词中；LLM 会在调用工具前先调用内置的 tool_search 工具来获取该工具的完整 schema。当服务器暴露大量工具时，这能保持初始上下文窗口较小。

安全与批准

MCP 工具调用与其他所有工具一样，都需要经过相同的审批关卡，并受代理的风险配置文件（risk_profiles.<alias>）约束。tool_search 发现步骤会被自动批准，以便延迟加载的 MCP 能在非交互式会话中正常工作，但从 MCP 服务器发现的工具仍然遵循正常的审批策略：

在自治 level = full 时，不显示工具调用提示（包括 MCP 工具）。
否则，MCP 工具调用会提示确认，除非其带前缀的名称（<server>__<tool>）在配置文件的 auto_approve 列表中。auto_approve = ["*"] 会批准所有内容；像 auto_approve = ["filesystem__read_file"] 这样的精确条目则只批准该工具。
always_ask 则相反：在其中列出的名称（或 "*"）将始终提示确认，覆盖 auto_approve。

授权：`allowed_tools` / `excluded_tools`

审批门控决定何时工具调用需要人工批准。授权门控决定代理是否可以调用工具。这两者相互独立。

将三个 MCP 工具控件保持在各自独立的维度上：

控制	范围	用于
`tool_filter_groups`	提示/上下文泄露	决定模型在某一轮对话中可见哪些 MCP 工具模式。
`auto_approve` / `always_ask`	审批策略	判断所选 MCP 工具调用是否需要操作员批准。
`allowed_tools` / `excluded_tools`	能力策略	决定该风险配置文件可使用哪些带前缀的工具名称。

对于运行时发现的 MCP 工具，能力契约有一个 MCP 特定的例外：

如果风险配置文件的 allowed_tools 为空或被省略，则不适用任何授权约束；所有发现的工具（MCP 或内置）都可访问。TOML 配置不会区分省略字段与 allowed_tools = []；两者在反序列化后都会在风险配置文件级别变成相同的“无授权约束”状态。如果你需要一个显式的全拒绝门控，请在调用方提供的每次运行的 allowed_tools 上进行设置（cron 作业和其他收窄器会直接传入该列表），或者通过 excluded_tools 覆盖你想要阻止的具体工具。
如果 allowed_tools 非空，则任何名称包含 __（<server>__<tool> 约定）的 MCP 工具都会自动纳入生效的允许列表，而无需单独列出。非 MCP 内置工具仍然需要精确列出条目。
excluded_tools 始终会进行排除，包括从自动接纳的 MCP 集合中排除。要阻止单个 MCP 工具，例如 filesystem__write_file，同时保持 filesystem 服务器的其余部分可访问，请将其放入 excluded_tools。

原因在于：在这个例外之前，任何将 allowed_tools 列表固定下来以锁定其内置能力范围的 agent，都会无声地丢失所有 MCP 工具，即使是操作员显式配置的工具也不例外。代价是，在一个固定了 allow-list 的配置文件下，deny-list 现在成了操作员阻止破坏性 MCP 能力的主要手段。

如果你想要此更改之前的严格模式，即只允许你显式列出的 MCP 工具，而不自动放行 __，请将一个显式的 allowed_tools 条目与每个需要阻止的破坏性同级工具对应的 excluded_tools 条目组合起来：

[risk_profiles.assistant]
allowed_tools = [
  "file_read",
  "filesystem__read_file",
]
# 阻止原本会通过上面的 `__` 例外自动加入的破坏性同类工具。
excluded_tools = [
  "filesystem__write_file",
]
auto_approve = [
  "filesystem__read_file",
]

MCP __ 自动放行例外仅限于风险配置的 allowed_tools。调用方在每次运行时提供的允许列表，比如 cron 作业的 allowed_tools，或任何其他将显式列表传入运行时的受限调用，仍然按严格的显式列表交集处理，不会再叠加 __ 自动放行。将自身限制为 allowed_tools = ["cron_add"] 的 cron 作业，即使代理的风险配置原本会通过 __ 约定自动放行 filesystem__write_file，也不会把 filesystem__write_file 暴露给模型；无论配置了多少 MCP 服务器，每次运行时的收窄范围仍然是可靠的能力边界。

auto_approve 本身并不会向模型隐藏工具；它只是在模型选择该工具后自动回答审批询问。使用 tool_filter_groups 来减少提示噪声，使用 allowed_tools / excluded_tools 来强制实施能力边界。

有关每个配置文件的完整字段范围，请参阅 Autonomy levels；有关每个 MCP 字段及其默认值，请参阅 Config reference。

MCP 资源和提示词

除了 MCP tools，ZeroClaw 还会从已连接的服务器公开 MCP resources 和 prompts。

工具

有两个内置工具可用（受你的代理工具访问策略限制）：

mcp_resources: action: "list"（可选 server、cursor）列出资源；带 uri（前缀为 <server>__<uri>）的 action: "read" 返回内容。
mcp_prompts: action: "list" 列出提示；action: "get" 携带 name（前缀为 <server>__<name>）和可选的 arguments 时，返回渲染后的提示消息。

不通告 resource/prompt 能力的服务器会被跳过，对它们的调用会返回明确的“does not support”错误。

将资源固定到上下文中

每个 MCP 服务器条目都接受一个可选的 pinned_resources 字段：这是一个资源 URI 列表，会在启动时读取一次并注入到系统提示中。通过与定义服务器相同的配置入口（网关、zerocode，或 zeroclaw config set，如 Configure MCP 中所示）进行设置，指定你希望代理始终可用的资源。该字段默认为空，因此未设置它的服务器不受影响。

固定内容每次运行只读取一次（不实时刷新），并标记为 trust="untrusted-external"，因此模型将其视为数据，而不是指令。

工具结果中嵌入的资源 Blob

当 MCP tools/call 结果包含一个形如 type: "resource" 且嵌套有 blob（base64）的内容项时，ZeroClaw 不会将该 base64 转储到模型上下文中。相反，它会将这些字节写入会话工作区的 uploads/ 目录（使用与 ACP 入站 resource.blob 相同的共享辅助程序和 10 MB 限制），并将面向模型的工具输出替换为非 blob 来源信息文本，以及 [Document: …] 或 [IMAGE:…] 标记。这一行为由内容结构而非工具名称控制。写入文件不会自动将文件交付给 ACP 客户端；需要出站交付时，代理仍会调用 deliver_file。请参阅 ACP session/prompt blob 接收。

由于结果来自不受信任的服务器，因此在解码、哈希处理或写入任何 blob 之前，会强制执行两个单次调用上限：每个 tools/call 结果最多包含 64 个资源 blob，且所有资源 blob 解码后估算的总大小最多为 10 MiB。超过任一上限的结果会将每个资源 blob 都降级为 [attachment unavailable: …] 标记，并且不会向磁盘写入任何内容，因此包含大量空 blob 或微小 blob 的数组无法强制执行逐项处理。每个单独的 blob 仍受相同的单文件 10 MB 限制约束。

除这些 解码后 的预算外，每个 HTTP/SSE MCP 服务器还具有传输层响应正文上限 max_response_bytes，该上限会在解析正文之前针对原始 编码后的 网络字节强制执行，因此服务器无法强制进行无界读取。它不是上面的 10 MiB 解码后限制：默认值为 16,078,168 bytes，这是 10 MiB 解码后聚合大小加上 JSON-RPC 封装预留空间后的 base64 扩展大小，因此接近上限的有效 blob 仍可完成物化。在服务器上设置 max_response_bytes 可覆盖此限制；设置为 0 或不设置则使用该默认值。

安全

资源和提示内容源自已配置的 MCP 服务器，并被视为不可信：在进入上下文之前，它会经过来源封装、秘密清理和长度限制。对 mcp_resources / mcp_prompts 以及特定服务器的访问由你代理的工具访问策略（风险配置）控制，并且在委派给子代理时会正确收紧。

Keyboard shortcuts

ZeroClaw Docs