How to Use OpenClaw as an MCP Server

openclaw mcp serve turns OpenClaw into an MCP server over stdio. The client owns that process, while the bridge connects to a local or remote OpenClaw Gateway over WebSocket and exposes routed channel conversations. This is useful when Codex, Claude Code, or another MCP client should read and respond through OpenClaw-backed channels.

Use the right bridge

The MCP docs draw an important line. serve is OpenClaw acting as an MCP server. The list, show, set, and unset subcommands manage OpenClaw-owned outbound MCP server definitions. Use openclaw acp instead when OpenClaw should host a coding harness session and route that runtime through ACP.

openclaw mcp serve
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
openclaw mcp serve --verbose

What conversations appear

The bridge uses existing Gateway session route metadata. A conversation appears when OpenClaw already has session state with a known route: channel, recipient or destination metadata, optional account id, and optional thread id. That gives MCP clients one place to list recent routed conversations, read transcript history, wait for inbound events, send replies through the same route, and see approval requests observed while connected.

Bridge tools

The docs list tools such as conversations_list, conversation_get, messages_read, attachments_fetch, events_poll, events_wait, messages_send, and approval tools. The important operational detail is that messages_send requires an existing conversation route; it sends text back through the route already recorded on the session.

Limits to remember

• Live queue state starts when the bridge connects; older history comes from transcript reads.
• When the MCP client disconnects, the bridge exits and live queue state is gone.
• Claude push notifications only exist while the MCP session is alive.
• One-shot agent entry points retire bundled MCP runtimes when the reply completes.
• Deleting or resetting a session disposes related MCP clients through cleanup.

Those constraints are not bugs. They are how the bridge avoids orphaned stdio processes and stale live queues. Design MCP client workflows around explicit reads and waits, not around assuming the bridge is a durable message broker.

My safe setup advice

Start local, verify the Gateway route exists, read a known conversation, then send a low-risk reply. Only after that should you wire a remote gateway URL or an editor integration. If a client needs to do sensitive writes, keep OpenClaw approvals and channel permissions in the loop.

If you are turning MCP-connected OpenClaw workflows into real operations instead of a demo, The OpenClaw Playbook is the shortcut I wish every operator had: identity files, memory rules, safety boundaries, channel discipline, and production habits in one field-tested guide.

Conversation route prerequisite

The bridge is most reliable when the route already exists. Have OpenClaw receive or send through the target channel once so session metadata includes the channel, destination, account, and thread details. Then let the MCP client read or reply through that known conversation. Starting with an empty or ambiguous route invites messages to land in the wrong place.

Approval and attachment discipline

MCP clients can feel like local tools, but replies still go to real people. Keep OpenClaw approvals active for sensitive actions, fetch attachments deliberately, and avoid giving a generic coding client broad permission to message customers or teammates without context. The bridge is a connector, not a judgment layer.

Runbook detail

For How to Use OpenClaw as an MCP Server, the important operator move is to record the exact documented surface you used and the condition that proves it worked. That might be a status command, a gateway event, a task record, a pairing approval, or a visible channel response. OpenClaw features are much easier to trust when the runbook says how to verify the feature, not just how to start it.

Operator checkpoint

Keep the first rollout narrow: one owner, one environment, one reversible test, and one written rollback note. Once the behavior matches the docs in that small setting, widen it deliberately. That habit prevents a useful OpenClaw feature from becoming another invisible system nobody knows how to debug. If the verification step is unclear, stop and tighten the runbook before you hand it to an autonomous agent.