Use this file to discover all available pages before exploring further.

MCP

text

openclaw mcp

has two jobs:

run OpenClaw as an MCP server with
text
openclaw mcp serve
manage OpenClaw-owned outbound MCP server definitions with
text
list
,
text
show
,
text
set
, and
text
unset

In other words:

text
serve
is OpenClaw acting as an MCP server
text
list
/
text
show
/
text
set
/
text
unset
is OpenClaw acting as an MCP client-side registry for other MCP servers its runtimes may consume later

Use

text

openclaw acp

when OpenClaw should host a coding harness session itself and route that runtime through ACP.

OpenClaw as an MCP server

This is the

text

openclaw mcp serve

path.

When to use
text
`serve`

Use

text

openclaw mcp serve

when:

Codex, Claude Code, or another MCP client should talk directly to OpenClaw-backed channel conversations
you already have a local or remote OpenClaw Gateway with routed sessions
you want one MCP server that works across OpenClaw's channel backends instead of running separate per-channel bridges

Use

text

openclaw acp

instead when OpenClaw should host the coding runtime itself and keep the agent session inside OpenClaw.

How it works

text

openclaw mcp serve

starts a stdio MCP server. The MCP client owns that process. While the client keeps the stdio session open, the bridge connects to a local or remote OpenClaw Gateway over WebSocket and exposes routed channel conversations over MCP.

Client spawns the bridge

The MCP client spawns `openclaw mcp serve`.

Bridge connects to Gateway

The bridge connects to the OpenClaw Gateway over WebSocket.

Sessions become MCP conversations

Routed sessions become MCP conversations and transcript/history tools.

Live events queue

Live events are queued in memory while the bridge is connected.

Optional Claude push

If Claude channel mode is enabled, the same session can also receive Claude-specific push notifications.

Choose a client mode

Use the same bridge in two different ways:

Standard MCP tools only. Use `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send`, and the approval tools. Standard MCP tools plus the Claude-specific channel adapter. Enable `--claude-channel-mode on` or leave the default `auto`.

note

Today, `auto` behaves the same as `on`. There is no client capability detection yet.

What
text
`serve`
exposes

The bridge uses existing Gateway session route metadata to expose channel-backed conversations. A conversation appears when OpenClaw already has session state with a known route such as:

text
channel
recipient or destination metadata
optional
text
accountId
optional
text
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} openclaw mcp serve ``` ```bash} openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ```bash} openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password ``` ```bash} openclaw mcp serve --verbose openclaw mcp serve --claude-channel-mode off ```

Bridge tools

The current bridge exposes these MCP tools:

Event model

The bridge keeps an in-memory event queue while it is connected.

Current event types:

text
message
text
exec_approval_requested
text
exec_approval_resolved
text
plugin_approval_requested
text
plugin_approval_resolved
text
claude_permission_request

warning

- 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. This is the OpenClaw equivalent of a Claude Code channel adapter: standard MCP tools remain available, but live inbound messages can also arrive as Claude-specific MCP notifications.

`--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:

text
notifications/claude/channel
text
notifications/claude/channel/permission

Current bridge behavior:

inbound
text
user
transcript messages are forwarded as
text
notifications/claude/channel
Claude permission requests received over MCP are tracked in-memory
if the linked conversation later sends
text
yes abcde
or
text
no abcde
, the bridge converts that to
text
notifications/claude/channel/permission
these notifications are live-session only; if the MCP client disconnects, there is no push target

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"
      ]
    }
  }
}

For most generic MCP clients, start with the standard tool surface and ignore Claude mode. Turn Claude mode on only for clients that actually understand the Claude-specific notification methods.

Options

text

openclaw mcp serve

supports:

Gateway WebSocket URL. Gateway token. Read token from file. Gateway password. Read password from file. Claude notification mode. Verbose logs on stderr.

tip

Prefer `--token-file` or `--password-file` over inline secrets when possible.

Security and trust boundary

The bridge does not invent routing. It only exposes conversations that Gateway already knows how to route.

That means:

sender allowlists, pairing, and channel-level trust still belong to the underlying OpenClaw channel configuration
text
messages_send
can only reply through an existing stored route
approval state is live/in-memory only for the current bridge session
bridge auth should use the same Gateway token or password controls you would trust for any other remote Gateway client

If a conversation is missing from

text

conversations_list

, the usual cause is not MCP configuration. It is missing or incomplete route metadata in the underlying Gateway session.

Testing

OpenClaw ships a deterministic Docker smoke for this bridge:


bash
pnpm test:docker:mcp-channels

That smoke:

starts a seeded Gateway container
starts a second container that spawns
text
openclaw mcp serve
verifies conversation discovery, transcript reads, attachment metadata reads, live event queue behavior, and outbound send routing
validates Claude-style channel and permission notifications over the real stdio MCP bridge

This is the fastest way to prove the bridge works without wiring a real Telegram, Discord, or iMessage account into the test run.

For broader testing context, see Testing.

Troubleshooting

OpenClaw as an MCP client registry

This is the

text

openclaw mcp list

text

show

text

set

, and

text

unset

path.

These commands do not expose OpenClaw over MCP. They manage OpenClaw-owned MCP server definitions under

text

mcp.servers

in OpenClaw config.

Those saved definitions are for runtimes that OpenClaw launches or configures later, such as embedded Pi and other runtime adapters. OpenClaw stores the definitions centrally so those runtimes do not need to keep their own duplicate MCP server lists.

Runtime adapters may normalize this shared registry into the shape their downstream client expects. For example, embedded Pi consumes OpenClaw

text

transport

values directly, while Claude Code and Gemini receive CLI-native

text

type

values such as

text

http

text

sse

, or

text

stdio

Saved MCP server definitions

OpenClaw also stores a lightweight MCP server registry in config for surfaces that want OpenClaw-managed MCP definitions.

Commands:

text
openclaw mcp list
text
openclaw mcp show [name]
text
openclaw mcp set <name> <json>
text
openclaw mcp unset <name>

Notes:

text
list
sorts server names.
text
show
without a name prints the full configured MCP server object.
text
set
expects one JSON object value on the command line.
Use
text
transport: "streamable-http"
for Streamable HTTP MCP servers.
text
openclaw mcp set
also normalizes CLI-native
text
type: "http"
to the same canonical config shape for compatibility.
text
unset
fails if the named server does not exist.

Examples:


bash
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp unset context7

Example config shape:


json
{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http"
      }
    }
  }
}

Stdio transport

Launches a local child process and communicates over stdin/stdout.

Field	Description
text `command`	Executable to spawn (required)
text `args`	Array of command-line arguments
text `env`	Extra environment variables
text `cwd` / text `workingDirectory`	Working directory for the process

warning

**Stdio env safety filter**

OpenClaw rejects interpreter-startup env keys that can alter how a stdio MCP server starts up before the first RPC, even if they appear in a server's

text

env

block. Blocked keys include

text

NODE_OPTIONS

text

PYTHONSTARTUP

text

PYTHONPATH

text

PERL5OPT

text

RUBYOPT

text

SHELLOPTS

text

PS4

, and similar runtime-control variables. Startup rejects these with a configuration error so they cannot inject an implicit prelude, swap the interpreter, or enable a debugger against the stdio process. Ordinary credential, proxy, and server-specific env vars (

text

GITHUB_TOKEN

text

HTTP_PROXY

, custom

text

*_API_KEY

, etc.) are unaffected.

If your MCP server genuinely needs one of the blocked variables, set it on the gateway host process instead of under the stdio server's

text

env

SSE / HTTP transport

Connects to a remote MCP server over HTTP Server-Sent Events.

Field	Description
text `url`	HTTP or HTTPS URL of the remote server (required)
text `headers`	Optional key-value map of HTTP headers (for example auth tokens)
text `connectionTimeoutMs`	Per-server connection timeout in ms (optional)

Example:


json
{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Sensitive values in

text

url

(userinfo) and

text

headers

are redacted in logs and status output.

Streamable HTTP transport

text

streamable-http

is an additional transport option alongside

text

sse

and

text

stdio

. It uses HTTP streaming for bidirectional communication with remote MCP servers.

Field	Description
text `url`	HTTP or HTTPS URL of the remote server (required)
text `transport`	Set to text `"streamable-http"` to select this transport; when omitted, OpenClaw uses text `sse`
text `headers`	Optional key-value map of HTTP headers (for example auth tokens)
text `connectionTimeoutMs`	Per-server connection timeout in ms (optional)

OpenClaw config uses

text

transport: "streamable-http"

as the canonical spelling. CLI-native MCP

text

type: "http"

values are accepted when saved through

text

openclaw mcp set

and repaired by

text

openclaw doctor --fix

in existing config, but

text

transport

is what embedded Pi consumes directly.

Example:


json
{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

note

These commands manage saved config only. They do not start the channel bridge, open a live MCP client session, or prove the target server is reachable.

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
HTTP/SSE/streamable-http transport connects to a single remote server; no multiplexed upstream yet
text
permissions_list_open
only includes approvals observed while the bridge is connected

OpenClaw Docs

MCP

OpenClaw as an MCP server

When to use
text
`serve`

How it works

Client spawns the bridge

Bridge connects to Gateway

Sessions become MCP conversations

Live events queue

Optional Claude push

Choose a client mode

note

What
text
`serve`
exposes

Usage

Bridge tools

Event model

warning

Claude channel notifications

MCP client config

Options

tip

Security and trust boundary

Testing

Troubleshooting

OpenClaw as an MCP client registry

Saved MCP server definitions

Stdio transport

warning

SSE / HTTP transport

Streamable HTTP transport

note

Current limits

Related

OpenClaw Docs

MCP

OpenClaw as an MCP server

When to use textCopyserve

How it works

Client spawns the bridge

Bridge connects to Gateway

Sessions become MCP conversations

Live events queue

Optional Claude push

Choose a client mode

note

What textCopyserve exposes

Usage

Bridge tools

Event model

warning

Claude channel notifications

MCP client config

Options

tip

Security and trust boundary

Testing

Troubleshooting

OpenClaw as an MCP client registry

Saved MCP server definitions

Stdio transport

warning

SSE / HTTP transport

Streamable HTTP transport

note

Current limits

Related

When to use
text
`serve`

What
text
`serve`
exposes