OpenClaw’s MCP Tool Bug Was Not Just Missing Tools. It Was Missing Diagnostics.

The easiest way to misdiagnose an MCP problem is to stop at “the server is healthy.” In agent systems, healthy is not the same as visible. A Model Context Protocol server can spawn correctly, answer tools/list, and expose dozens of useful actions, while the model still receives none of them because another policy gate quietly filtered the tools before the provider request was serialized.

That is the failure PR #84742 tries to make legible. The patch does not throw open the gates. It adds openclaw doctor warnings when configured MCP servers are loaded but hidden from sandboxed agents by the sandbox tool allow policy. That is exactly the kind of fix mature agent platforms need: preserve least privilege, but stop making operators debug invisible policy decisions by reading source and capturing wire payloads.

The missing tool was not missing. It was denied.

The replacement PR was created at 2026-05-21T00:28:59Z, after source PR #84699 was closed because ClawSweeper could not update the contributor branch directly. The replacement changes five files with 545 additions and 5 deletions, touching the changelog, gateway tool-policy docs, a sandbox/tool-policy/elevated explainer, and the new doctor warning implementation plus tests.

The diagnostic condition is narrow and useful: entries under mcp.servers can load successfully while the active sandbox tool allow gate filters bundled MCP tools before provider requests. The proposed warning tells operators to add bundle-mcp, group:plugins, or a matching sanitized server pattern such as outlook__* to tools.sandbox.tools.alsoAllow if those MCP tools should be visible. It also states that tools.sandbox.tools.allow: [] should be used only when the operator intentionally wants no sandbox allow gate.

That specificity is the whole value. A vague “MCP tool missing” warning would be another log line to ignore. A warning that names the exact closed gate and the exact allow entries that satisfy it is operationally useful. It lets an operator fix configuration without weakening defaults for everyone else.

The issue history is the actual incident report

The canonical user report is issue #80909. It says configured MCP tools never reached outbound provider tools[] across releases from 2026.4.26 through 2026.5.7, despite two stdio MCP servers being healthy and returning more than 50 tools directly. The reporter tested at least seven stable releases and showed specific examples where only built-in OpenClaw tools reached the OpenRouter chat-completions request body, with zero server__* entries.

The token evidence is especially telling. The reporter observed stable input token counts around 48k to 72k where adding MCP tool definitions would have added roughly 20k to 30k tokens. That is not a vibes-based bug report. That is a wire-level argument: if the tool schemas were present, the request size would change. They did not. The tools were not reaching the model.

The user also connected the new report to a previous cluster — #74387, #74726, and #74844 — that they say was closed and locked as resolved despite runtime evidence from multiple users. Whether or not every detail of that complaint holds up, the pattern is familiar. Agent platforms often prove a feature exists in code and then miss the execution path where a particular sender, sandbox, profile, provider, or channel strips it out.

ClawSweeper’s review caught a useful edge case in #84742 itself: exact server__tool allow entries like outlook__list_inbox were not recognized by the new probe-only matcher, even though the runtime supports them. That is precisely why diagnostics deserve tests. A warning system with false positives becomes a second bug, and operators learn to distrust it just as quickly as they distrust silence.

MCP security is capability governance, not adapter plumbing

The deeper lesson is that MCP failures are increasingly governance failures masquerading as integration bugs. MCP servers are not harmless decorations. They often bridge email, calendars, browsers, files, issue trackers, ticketing systems, internal APIs, and developer tools. Automatically exposing every configured MCP server inside a sandboxed session would be convenient, and also reckless.

OpenClaw is right not to auto-open the gate. If a sandboxed agent can suddenly see every MCP capability because the server spawned successfully, the sandbox is not really a capability boundary. Tool allowlists are not UX preferences; they are authority definitions. The right design is to keep configured tools hidden unless policy allows them, then make the denial obvious enough that a competent operator can fix it deliberately.

This is where many “AI agent tool permissions” discussions get too abstract. The real world version is not a dashboard with a green toggle. It is a chain of gates: MCP server configured, process spawned, tools/list returned, plugin loaded, agent profile allowed, sandbox tool policy allowed, provider serializer included the schema, model selected the tool, runtime executed it, approval policy permitted it, and the result made it back into context. Any one of those layers can say no. If the platform cannot explain which one did, operators will blame the model, the MCP server, or themselves — usually in that order.

What builders should change now

If you run MCP-backed agents in OpenClaw, the practical move is to test visibility where it matters: the provider request boundary. Do not stop at “the MCP server starts.” Do not stop at “tools/list returns 50 tools.” Inspect or capture a representative sandboxed turn and verify the expected server__tool schemas appear in the outbound tools[] array. Run doctor after upgrades. Test exact allow patterns such as outlook__list_inbox as well as globs such as outlook__*.

For maintainers, #84742 is a good patch shape because it does not confuse observability with permission. It makes the closed gate visible without silently changing the security posture. The next step should be end-to-end fixture coverage that exercises the full chain from MCP config to provider serialization under sandboxed profiles. Static presence of a tool-registration path is not proof that the model can see the tool.

The editorial take is simple: the MCP bug was never just “tools missing.” It was a missing explanation for a policy decision. Agent runtimes are allowed to deny capabilities. In fact, they should. But a secure denial that looks like a broken integration will still burn operator trust. OpenClaw is right to keep the gate closed; now it has to keep telling users which gate they are looking at.

Sources: OpenClaw PR #84742, source PR #84699, issue #80909, issue #74387, issue #74844