feat: add openclaw channel mcp bridge

2026-03-29 10:50:58 +00:00 · 2026-03-28 02:41:06 +00:00
parent a65d603b31
commit 71f37a59ca
11 changed files with 1839 additions and 3 deletions
--- a/docs/cli/acp.md
+++ b/docs/cli/acp.md
@@ -17,6 +17,10 @@ over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
 runtime. It focuses on session routing, prompt delivery, and basic streaming
 updates.

+If you want an external MCP client to talk directly to OpenClaw channel
+conversations instead of hosting an ACP harness session, use
+[`openclaw mcp serve`](/cli/mcp) instead.
+
 ## Compatibility Matrix

 | ACP area                                                              | Status      | Notes                                                                                                                                                                                                                                            |
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -27,6 +27,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - [`agent`](/cli/agent)
 - [`agents`](/cli/agents)
 - [`acp`](/cli/acp)
+- [`mcp`](/cli/mcp)
 - [`status`](/cli/status)
 - [`health`](/cli/health)
 - [`sessions`](/cli/sessions)
@@ -155,6 +156,7 @@ openclaw [--dev] [--profile <name>] <command>
    add
    delete
  acp
+  mcp
  status
  health
  sessions
--- a/docs/cli/mcp.md
+++ b/docs/cli/mcp.md
@@ -0,0 +1,251 @@
+---
+summary: "Expose OpenClaw channel conversations over MCP and manage saved MCP server definitions"
+read_when:
+  - Connecting Codex, Claude Code, or another MCP client to OpenClaw-backed channels
+  - Running `openclaw mcp serve`
+  - Managing OpenClaw-saved MCP server definitions
+title: "mcp"
+---
+
+# mcp
+
+`openclaw mcp` has two jobs:
+
+- run a Gateway-backed MCP bridge with `openclaw mcp serve`
+- manage OpenClaw-saved MCP server definitions with `list`, `show`, `set`, and `unset`
+
+Use `openclaw mcp serve` when an external MCP client should talk directly to
+OpenClaw channel conversations.
+
+Use [`openclaw acp`](/cli/acp) when OpenClaw should host a coding harness
+session itself and route that runtime through ACP.
+
+## What `serve` does
+
+`openclaw mcp serve` starts a stdio MCP server that connects to a local or
+remote OpenClaw Gateway over WebSocket.
+
+The bridge uses existing Gateway session route metadata to expose channel-backed
+conversations. In practice, that means a conversation appears when OpenClaw has
+session state with a known channel route such as:
+
+- `channel`
+- `to`
+- optional `accountId`
+- optional `threadId`
+
+This gives MCP clients one place to:
+
+- list recent routed conversations
+- read recent transcript history
+- wait for new inbound events
+- send a reply back through the same route
+- see approval requests that arrive while the bridge is connected
+
+## Usage
+
+```bash
+# Local Gateway
+openclaw mcp serve
+
+# Remote Gateway
+openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
+
+# Remote Gateway with password auth
+openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
+
+# Enable verbose bridge logs
+openclaw mcp serve --verbose
+
+# Disable Claude-specific push notifications
+openclaw mcp serve --claude-channel-mode off
+```
+
+## Bridge tools
+
+The current bridge exposes these MCP tools:
+
+- `conversations_list`
+- `conversation_get`
+- `messages_read`
+- `attachments_fetch`
+- `events_poll`
+- `events_wait`
+- `messages_send`
+- `permissions_list_open`
+- `permissions_respond`
+
+### `conversations_list`
+
+Lists recent session-backed conversations that already have route metadata in
+Gateway session state.
+
+Useful filters:
+
+- `limit`
+- `search`
+- `channel`
+- `includeDerivedTitles`
+- `includeLastMessage`
+
+### `conversation_get`
+
+Returns one conversation by `session_key`.
+
+### `messages_read`
+
+Reads recent transcript messages for one session-backed conversation.
+
+### `attachments_fetch`
+
+Extracts non-text message content blocks from one transcript message. This is a
+metadata view over transcript content, not a standalone durable attachment blob
+store.
+
+### `events_poll`
+
+Reads queued live events since a numeric cursor.
+
+### `events_wait`
+
+Long-polls until the next matching queued event arrives or a timeout expires.
+
+### `messages_send`
+
+Sends text back through the same route already recorded on the session.
+
+Current behavior:
+
+- requires an existing conversation route
+- uses the session's channel, recipient, account id, and thread id
+- sends text only
+
+### `permissions_list_open`
+
+Lists pending exec/plugin approval requests the bridge has observed since it
+connected to the Gateway.
+
+### `permissions_respond`
+
+Resolves one pending exec/plugin approval request with:
+
+- `allow-once`
+- `allow-always`
+- `deny`
+
+## Event model
+
+The bridge keeps an in-memory event queue while it is connected.
+
+Current event types:
+
+- `message`
+- `exec_approval_requested`
+- `exec_approval_resolved`
+- `plugin_approval_requested`
+- `plugin_approval_resolved`
+- `claude_permission_request`
+
+Important limits:
+
+- the queue is live-only; it starts when the MCP bridge starts
+- `events_poll` and `events_wait` do not replay older Gateway history by
+  themselves
+- durable backlog should be read with `messages_read`
+
+## Claude channel notifications
+
+The bridge can also expose Claude-specific channel notifications.
+
+Flags:
+
+- `--claude-channel-mode off`: standard MCP tools only
+- `--claude-channel-mode on`: enable Claude channel notifications
+- `--claude-channel-mode auto`: current default; same bridge behavior as `on`
+
+When Claude channel mode is enabled, the server advertises Claude experimental
+capabilities and can emit:
+
+- `notifications/claude/channel`
+- `notifications/claude/channel/permission`
+
+Current bridge behavior:
+
+- inbound `user` transcript messages are forwarded as
+  `notifications/claude/channel`
+- Claude permission requests received over MCP are tracked in-memory
+- if the linked conversation later sends `yes abcde` or `no abcde`, the bridge
+  converts that to `notifications/claude/channel/permission`
+
+This is intentionally client-specific. Generic MCP clients should rely on the
+standard polling tools.
+
+## MCP client config
+
+Example stdio client config:
+
+```json
+{
+  "mcpServers": {
+    "openclaw": {
+      "command": "openclaw",
+      "args": [
+        "mcp",
+        "serve",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token-file",
+        "/path/to/gateway.token"
+      ]
+    }
+  }
+}
+```
+
+## Options
+
+`openclaw mcp serve` supports:
+
+- `--url <url>`: Gateway WebSocket URL
+- `--token <token>`: Gateway token
+- `--token-file <path>`: read token from file
+- `--password <password>`: Gateway password
+- `--password-file <path>`: read password from file
+- `--claude-channel-mode <auto|on|off>`: Claude notification mode
+- `-v`, `--verbose`: verbose logs on stderr
+
+## Saved MCP server definitions
+
+OpenClaw also stores a lightweight MCP server registry in config for surfaces
+that want OpenClaw-managed MCP definitions.
+
+Commands:
+
+- `openclaw mcp list`
+- `openclaw mcp show [name]`
+- `openclaw mcp set <name> <json>`
+- `openclaw mcp unset <name>`
+
+Examples:
+
+```bash
+openclaw mcp list
+openclaw mcp show context7 --json
+openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
+openclaw mcp unset context7
+```
+
+These commands manage saved config only. They do not start the channel bridge.
+
+## Current limits
+
+This page documents the bridge as shipped today.
+
+Current limits:
+
+- conversation discovery depends on existing Gateway session route metadata
+- no generic push protocol beyond the Claude-specific adapter
+- no message edit or react tools yet
+- no dedicated HTTP MCP transport yet
+- `permissions_list_open` only includes approvals observed while the bridge is
+  connected