openclaw - 💡(How to fix) Fix [Bug]: MCP tools not injected into subagent (sessions_spawn) sessions — `bundle-mcp` + per-tool subagent allowlist + per-agent allowlist all ignored, subagent system prompt and tool schema receive only built-ins

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

MCP tool schemas registered via mcp.servers are not injected into sessions spawned by sessions_spawn, regardless of how the documented exposure mechanism is configured.

The documented mechanism (tools.subagents.tools.allow containing bundle-mcp plus per-tool MCP entries, combined with the target agent's tools.allow listing the relevant <server>__<tool> names, all under tools.profile: "full") does not result in those MCP tools appearing in the subagent's injected tool schema or in the system prompt's tool listing. The subagent receives only the built-in tools.

This is parallel to (but distinct from) #68875 [Bug]: mcp.servers tools not available in Pi runtime (isolated, cron, main sessions). That issue covers cron / isolated / main sessions; this one covers subagent sessions spawned via sessions_spawn.

Direct sessions on the same agents DO receive MCP schemas correctly (verified by token-count jump on first MCP-using turn). The failure is specific to the subagent session lane.

Steps to reproduce

1. Configure an MCP server in mcp.servers (any streamable-http or stdio server with at least one tool):

   "mcp": { "servers": { "myserver": { "url": "https://example.com/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer ${MY_TOKEN}" } } } }

2. Set top-level tools.profile: "full".

3. Configure tools.subagents.tools.allow to expose the MCP tools to subagent contexts per docs/gateway/config-tools.md ("MCP and plugin tools inside sandbox tool policy" — same bundle-mcp mechanism documented for sandbox, applied to subagent layer):

   "tools": { "subagents": { "tools": { "allow": [ "bundle-mcp", "read", "write", "exec", "message", "web_search", "web_fetch", "sessions_yield", "myserver__some_tool" ] } } }

4. Define two agents: a delegator (caller) with sessions_spawn in its tools.allow, and a worker (target) with myserver__some_tool in its own tools.allow.

5. From the delegator, spawn the worker via sessions_spawn with a task that requires the MCP tool.

6. After the worker completes (or fails), export its trajectory: openclaw sessions export-trajectory --agent <worker> --session-key '<subagent session key>' --output bug-evidence

7. Inspect bug-evidence/tools.json and bug-evidence/system-prompt.txt.

Expected behavior

The subagent's injected tool schema (tools.json) should include the MCP tool entries that satisfy the intersection of:

• top-level tools.subagents.tools.allow (gating which tools may reach any subagent)
• target agent's per-agent tools.allow (gating which tools that specific agent uses)
• plugin-exposure (bundle-mcp) at the subagent policy layer

The subagent's system prompt should enumerate those MCP tools alongside the built-ins, matching the behavior in direct sessions.

Per docs/gateway/config-tools.md and the security advisory GHSA-qrp5-gfw2-gxv4 ("OpenClaw now applies a final effective tool policy pass to bundled MCP/LSP tools before merging them into the tool set used by normal runs and compaction. The pass covers profile policy, provider profile policy, global/agent/group policies, owner-only filtering, sandbox tool policy, and subagent tool policy."), the subagent tool policy layer IS expected to expose bundled MCP tools when configured to do so.

Actual behavior

The subagent's tools.json contains only the four built-in tools: exec, message, read, sessions_yield. No MCP tools are present, regardless of the layered configuration above.

The subagent's system prompt explicitly lists only those four built-ins under "## Tooling" and provides no indication that any MCP server is registered.

Verified across multiple test runs:

• 5 independent subagent commissions of the same worker over a 90-minute window
• 2 different worker agents (one with 2 MCP tools in its allow, one with 5)
• 2 different model providers (google/gemini-3.5-flash and google/gemini-3.1-pro-preview as fallback) — model-agnostic
• bundle-mcp present in tools.subagents.tools.allow throughout

The subagent, lacking schemas, falls back to hand-rolling HTTPS requests against the MCP server's HTTP endpoint using the env-injected ${MCP_KEY_OC} bearer token. This is a defensive workaround that bypasses MCP entirely.

Tested and FAILED to inject MCP schemas into subagent context:

• bundle-mcp at tools.subagents.tools.allow (documented mechanism)
• per-tool gst-mcp__* entries at tools.subagents.tools.allow
• gst-mcp__* entries on target agent's tools.allow
• gst-mcp__* entries on caller (delegator) agent's tools.allow
• All combinations of the above
• tools.profile: "full" at top level (no profile filtering interference)

OpenClaw version

OpenClaw 2026.5.18 (50a2481)

Operating system

macOS 26.4.1 (arm64)

Install method

npm global (Homebrew node@22)

Model

google/gemini-3.5-flash (primary), google/gemini-3.1-pro-preview (fallback) Note: model-agnostic. The bug is at the gateway tool-injection layer, before the model is invoked. Same failure observed across both models.

Provider / routing chain

openrouter -> google/gemini-3.5-flash (subagent target) Local vllm-brain / vllm-fast (rapid-mlx) used for other agents in the same fleet; not relevant to this bug.

Additional provider/model setup details

• Delegator agent (Armitage): runs on rapid-mlx local Qwen3.5-9B via vllm-fast for some tests, OpenRouter cloud for others — bug reproduces regardless.
• Worker agent (Neuromancer): runs on OpenRouter gemini-3.5-flash.
• MCP server: gst-mcp at https://mcp.globalstrategic.tech/mcp, transport: streamable-http, bearer auth.
• MCP server health verified independently: direct sessions on the same gateway DO receive gst-mcp tool schemas successfully (confirmed via /context list and trajectory exports showing 11+ MCP tools injected). The failure is isolated to subagent contexts.

Logs, screenshots, and evidence

Attached files:

1. config.txt — output of:
   - tools.profile
   - mcp.servers entry (Authorization redacted to "Bearer ${MCP_KEY_OC}")
   - tools.subagents block (shows bundle-mcp + per-tool MCP entries present)
   - per-agent tools blocks for delegator + 3 target agents (shows per-agent gst entries on targets)

2. subagent-tools-neuromancer.json — the subagent's injected tool schema, ground-truth from
   `openclaw sessions export-trajectory`. Contains exactly 4 entries: exec, message, read, sessions_yield.
   No MCP entries, no bundle-mcp, no gst-mcp__* names.

3. subagent-system-prompt-neuromancer.txt — the subagent's system prompt as injected.
   Explicitly enumerates only the 4 built-ins under "## Tooling". No mention of any MCP server.

4. neuromancer-session-trajectory.jsonl (head excerpt) — the subagent's reasoning trace, showing
   the model's first thought is to filesystem-hunt for tool shims because it has no MCP schemas.
   First thinking block (verbatim): "I'm unsure if they are directly callable or accessible via exec.
   First tool calls: `ls -la`, `read mcp_query.js` (a leftover from a prior session), then `node mcp_query.js`
   to hand-roll HTTPS against the MCP server.

[config.txt](https://github.com/user-attachments/files/28112707/config.txt)
[subagent-system-prompt-neuromancer.txt](https://github.com/user-attachments/files/28112705/subagent-system-prompt-neuromancer.txt)
[subagent-tools-neuromancer.json](https://github.com/user-attachments/files/28112706/subagent-tools-neuromancer.json)
[version.txt](https://github.com/user-attachments/files/28112708/version.txt)

Impact and severity

Affected: any user configuring an MCP server and expecting subagents (spawned via sessions_spawn) to be able to invoke MCP tools as part of their delegated workflow.

Severity: High. This is the documented multi-agent pattern for offloading specialist work (orchestrator delegates to domain-specific worker which invokes external tools via MCP). The bug forces all MCP-using work to direct sessions only, defeating the orchestration model.

Frequency: 100% reproducible across 5 test commissions, 2 worker agents, 2 model providers.

Consequence: Workarounds require either: (a) the subagent hand-rolling raw HTTPS to the MCP server using env-injected credentials, which bypasses the gateway's MCP client entirely and loses retries, telemetry, and policy enforcement; or (b) reorganizing workflows so MCP-tool-using work happens in direct sessions only, eliminating the orchestrator/worker separation.

Neither workaround scales.

Additional information

Not a duplicate of:

• #68875 [Bug]: mcp.servers tools not available in Pi runtime (isolated, cron, main sessions) — CLOSEST adjacent issue. Same class of bug (MCP schemas absent from a non-direct session type), but #68875 specifically scopes to cron / isolated / main sessions in the Pi runtime. This issue covers subagent sessions spawned via sessions_spawn. The two may share a root cause (no code path loading mcpServers into runtimes other than the direct ACP client per #68246), but the trigger conditions and the session-key shape differ. Should likely be fixed together; filing separately so maintainers can scope each.

• #63399 (MCP tools bypass per-agent tools.allow / tools.deny filter) — INVERSE problem. #63399 reports MCP tools leaking through restrictive per-agent allow filters in direct sessions (agent sees too many MCP tools). This issue reports MCP tools being missing despite permissive subagent policy (agent sees zero MCP tools). Likely separate code paths.

• GHSA-qrp5-gfw2-gxv4 (Bundled MCP/LSP tools could bypass configured tool policy) — RELATED fix, possibly REGRESSION SOURCE. The advisory states OpenClaw now applies a "final effective tool policy pass to bundled MCP/LSP tools" covering "sandbox tool policy, and subagent tool policy." If that pass is correctly applied, the subagent tool policy in our reproducer should ALLOW the MCP tools (we have bundle-mcp and the per-tool entries in tools.subagents.tools.allow). It does not. This suggests either (a) the policy pass is rejecting these tools when it should allow them, or (b) the policy pass runs AFTER the schema-injection phase, so even tools that "pass" don't reach the injected schema.

Reference: the source-level note in #68875 ("Per #68246, mcpServers is consumed only under src/acp/client.ts — no code path exists to load them into the Pi runtime.") may apply here too. Subagent sessions are not direct ACP client sessions; if the mcp-loading code path is gated on the direct ACP client, subagent contexts would never receive MCP schemas regardless of policy configuration.

If maintainers want a live reproducer environment, I can provide a minimal config + a stubbed MCP server. Happy to test patches against the reproducer.