Docs: Plugin-registered tools not visible to agent dispatch (+ SKILL.md workaround)

[project-you-apps]

Summary

Tools registered via api.registerTool() in the adapter work perfectly in TUI sessions but are not visible to agent dispatch (openclaw agent --agent X --message "..."). This is an OpenClaw core architectural constraint, not a bug in the adapter — but it's worth documenting since it affects anyone trying to use MCP tools from headless agent runs.

Root Cause

• api.registerTool() registers at the gateway runtime level only
• TUI sessions share the gateway runtime, so they see plugin-registered tools
• Agent dispatch builds its tool set from the core tool registry, which doesn't query plugins
• The ACP layer explicitly disables MCP capabilities (mcpCapabilities sets HTTP and SSE to false)
• MCP servers passed during session creation are silently ignored
• OpenClaw Issue #4834 (native MCP support) was closed as "not planned" (2026-02-01)

What We Tried

• tools.alsoAllow in agent config → read as tools.allow, "unknown entries" warning
• tools at agents.defaults level → not valid (only per-agent)
• Multiple config permutations across 7+ test rounds — all confirmed the limitation

Workaround: SKILL.md + mcporter

The OpenClaw-blessed pattern for making external tools visible to agent dispatch is file-based skill registration, not programmatic tool registration:

1. Install mcporter
2. Create ~/.openclaw/skills/<your-mcp-server>/SKILL.md that documents mcporter call commands
3. OpenClaw discovers SKILL.md at startup and injects it into the system prompt for ALL agent runs (including dispatch)
4. The agent reads the skill docs and shells out via mcporter per tool call

This is how every MCP skill in the OpenClaw ecosystem works (clickup-mcp, guru-mcp, etc.). Trade-off: ~2.4s cold-start per call (subprocess spawn + connect), vs the adapter's persistent connection.

Suggestion

Consider adding a note to the README explaining:

• The adapter works great for TUI sessions (its intended scope)
• For agent dispatch, users should use the SKILL.md + mcporter pattern
• Link to OpenClaw's skill documentation for setup instructions

Happy to PR the README update if that's helpful. Great adapter btw — the persistent connection and auto-reconnect logic is solid for the TUI use case.

—
Andy Grossberg & Claude (Waving Cat Learning Systems)

[raedkit]

Summary

Tools registered via api.registerTool() in the adapter work perfectly in TUI sessions but are not visible to agent dispatch (openclaw agent --agent X --message "..."). This is an OpenClaw core architectural constraint, not a bug in the adapter — but it's worth documenting since it affects anyone trying to use MCP tools from headless agent runs.

Root Cause

* `api.registerTool()` registers at the **gateway runtime level** only

* TUI sessions share the gateway runtime, so they see plugin-registered tools

* Agent dispatch builds its tool set from the **core tool registry**, which doesn't query plugins

* The ACP layer explicitly disables MCP capabilities (`mcpCapabilities` sets HTTP and SSE to `false`)

* MCP servers passed during session creation are silently ignored

* OpenClaw Issue #4834 (native MCP support) was closed as "not planned" (2026-02-01)

What We Tried

* `tools.alsoAllow` in agent config → read as `tools.allow`, "unknown entries" warning

* `tools` at `agents.defaults` level → not valid (only per-agent)

* Multiple config permutations across 7+ test rounds — all confirmed the limitation

Workaround: SKILL.md + mcporter

The OpenClaw-blessed pattern for making external tools visible to agent dispatch is file-based skill registration, not programmatic tool registration:

1. Install [mcporter](https://github.com/steipete/mcporter)

2. Create `~/.openclaw/skills/<your-mcp-server>/SKILL.md` that documents `mcporter call` commands

3. OpenClaw discovers SKILL.md at startup and injects it into the system prompt for ALL agent runs (including dispatch)

4. The agent reads the skill docs and shells out via mcporter per tool call

This is how every MCP skill in the OpenClaw ecosystem works (clickup-mcp, guru-mcp, etc.). Trade-off: ~2.4s cold-start per call (subprocess spawn + connect), vs the adapter's persistent connection.

Suggestion

Consider adding a note to the README explaining:

* The adapter works great for TUI sessions (its intended scope)

* For agent dispatch, users should use the SKILL.md + mcporter pattern

* Link to OpenClaw's skill documentation for setup instructions

Happy to PR the README update if that's helpful. Great adapter btw — the persistent connection and auto-reconnect logic is solid for the TUI use case.

— Andy Grossberg & Claude (Waving Cat Learning Systems)

Hi @project-you-apps possible to share your own implementation (example of skill) that fixes this issue ? I don't want to re-invent the wheel. Thanks in advance

[project-you-apps]

Hey @raedkit — to be transparent: we documented the workaround pattern (SKILL.md + mcporter) based on how other OpenClaw MCP skills handle it, but haven't built that implementation ourselves. Our working setup uses Claude Code's native MCP client (configured in ~/.claude.json), which is a separate system from OpenClaw's agent dispatch and works out of the box.

For OpenClaw specifically, the SKILL.md + mcporter pattern is the blessed approach — create ~/.openclaw/skills/your-mcp-server/SKILL.md with tool docs and mcporter call commands. OpenClaw discovers it at startup and injects into agent prompts. ~2.4s cold-start per call vs the adapter's persistent connection.

If you build one out I'm happy to review/merge a PR. Otherwise I'll update when we circle back to it.

---

Written by Claude (Code Lead), reviewed and approved by Andy — Waving Cat Learning Systems