MCP with OpenClaw

MCP is a standard for exposing tools and resources to an assistant over a small protocol. In OpenClaw, openclaw mcp covers two different responsibilities:

1. mcp serve — OpenClaw runs as an MCP server (stdio). Your MCP client (Codex, Claude Code, another IDE) launches the process; OpenClaw bridges to your Gateway WebSocket and turns already-routed channel sessions into MCP conversations, tools, and (optionally) live events.
2. mcp list / show / set / unset — OpenClaw stores outbound MCP server definitions in config (mcp.servers) for other parts of the stack (embedded runtimes, adapters). These commands edit config only; they do not open a live bridge and do not health-check the remote server.

Skills (skills guide) are workspace packages with SKILL.md, scripts, and instructions—great for repeatable agent workflows. MCP here is protocol plumbing: either exposing chat to an external MCP client, or registering MCP servers for runtimes that know how to consume them. Choose skills when you want file-based capability; choose MCP when your toolchain already speaks MCP or you need the channel bridge.

Use this when an MCP client should talk to conversations that already live in your OpenClaw Gateway (Telegram, Discord, etc.) without building a separate per-channel integration. The client spawns openclaw mcp serve; OpenClaw opens a WebSocket to the Gateway and exposes tools backed by session route metadata.

Typical use: Codex or Claude Code wants to list conversations, read recent transcript, wait for inbound events, send a reply, and handle exec/plugin approvals that appear while the session is open.

Your MCP client config usually launches OpenClaw as a stdio server, for example:

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": ["mcp", "serve", "--url", "wss://gateway-host:18789", "--token-file", "/path/to/gateway.token"]
    }
  }
}

Local Gateway

openclaw mcp serve

Remote Gateway

Pass the WebSocket URL and auth the same way you would for any remote CLI client. Prefer --token-file or --password-file over inline secrets.

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

openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off

Claude channel mode (on, off, or auto): adds Claude-specific notifications on top of the standard tool surface. Generic MCP clients should start with standard tools and polling; turn Claude mode on only if the client understands those notifications.

If you already run OpenClaw with Telegram, Slack, or other channels, openclaw mcp serve lets Claude Code list those conversations and reply through the same Gateway routes—no second bot per channel.

1. Start your Gateway and confirm a test channel works (openclaw doctor).
2. Create a token file the bridge can read (same auth you use for remote CLI).
3. Add to Claude Code (or another MCP client) mcpServers:

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": ["mcp", "serve", "--token-file", "/home/you/.openclaw/gateway.token"]
    }
  }
}

For a remote Gateway, add --url wss://your-host:18789 to args. Restart the MCP client, then try listing conversations. Pairing and allowlists still apply—see trust overview.

Tool names and fields can gain options over time; the list below is the mental model shipped with OpenClaw today.

• Discovery & read — conversations_list (recent routed chats), conversation_get (one session by key), messages_read (transcript slice), attachments_fetch (non-text blocks for a message).
• Live traffic — events_poll and events_wait read the in-memory queue that starts when the bridge connects. They do not replay old Gateway history by themselves; use messages_read for backlog.
• Outbound chat — messages_send sends text back through the existing route on the session (channel, recipient, optional account/thread). It cannot invent routing; if a conversation is missing from conversations_list, the cause is usually missing route metadata on the Gateway session, not MCP wiring.
• Approvals — permissions_list_open and permissions_respond cover exec/plugin approvals observed while the bridge is connected (allow-once, allow-always, deny). This is live session state, not a durable audit log API.

Trust boundary: channel allowlists, DM pairing, and gateway auth still apply. The bridge only exposes what the Gateway already knows how to route.

These commands manage mcp.servers in openclaw.json (or your effective config path). They are for definitions other runtimes load—stdio commands, remote HTTP/SSE/streamable HTTP servers, headers, timeouts—not for proving reachability.

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

Transports you should know:

• stdio — spawns a local child; command, args, optional env / working directory. OpenClaw blocks a set of interpreter-startup environment keys in server env blocks for safety (upstream documents the blocklist).
• SSE / HTTP — remote server over HTTP with Server-Sent Events; url, optional headers, connectionTimeoutMs.
• streamable-http — bidirectional HTTP streaming; canonical config uses transport: "streamable-http". CLI may accept type: "http" and normalize it—openclaw doctor --fix can repair older shapes.

Embedded runtimes may expose configured MCP tools in normal coding / messaging tool profiles; minimal can hide them, and you can deny bundled MCP explicitly in policy when you need a stricter profile.

• No conversations in conversations_list — confirm the Gateway session already has route metadata (channel, recipient, optional account/thread). Fix the underlying channel/session first.
• events_poll / events_wait “miss” older messages — expected: the live queue begins when the bridge connects. Read older lines with messages_read.
• Claude notifications absent — client must keep stdio open; mode must be on or auto; the client must understand Claude-specific notifications; inbound events must occur after connect.
• Approvals “missing” — only approvals that arrived during this bridge session appear in permissions_list_open.

OpenClaw ships a Docker smoke test for the channel MCP bridge (pnpm test:docker:mcp-channels in the upstream repo) if you need a deterministic check without wiring real messengers.

Options, limits, and tool schemas evolve per release. Use the project’s own page when you need verbatim flags, JSON shapes, or the latest edge cases:

• CLI: MCP — authoritative openclaw mcp documentation.
• CLI: ACP — when OpenClaw should host the coding harness instead of this bridge.
• CLI index — neighboring commands (plugins, gateway, etc.).