mcp.md

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
sidebarTitle	MCP

openclaw mcp has two jobs:

• run OpenClaw as an MCP server with openclaw mcp serve
• manage OpenClaw-managed outbound MCP server definitions with list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, and unset

serve is OpenClaw acting as an MCP server. The other subcommands are OpenClaw acting as an MCP client-side registry for servers its own runtimes may consume later.

`list`, `show`, `set`, and `unset` only read and write OpenClaw-managed `mcp.servers` entries in OpenClaw config. They do not include mcporter servers from `config/mcporter.json`; use `mcporter list` for that registry.

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

Choose the right MCP path

Goal	Use	Why
Let an external MCP client read/send OpenClaw channel conversations	openclaw mcp serve	OpenClaw is the MCP server and exposes Gateway-backed conversations over stdio.
Save third-party MCP servers for OpenClaw-managed agent runs	openclaw mcp add, set, configure, tools, login	OpenClaw is the MCP client-side registry and later projects those servers into eligible runtimes.
Check a saved server without running an agent turn	openclaw mcp status, doctor, probe	status and doctor inspect config; probe opens a live MCP connection and lists capabilities.
Edit MCP config from a browser	Control UI /settings/mcp (/mcp alias)	The page shows inventory, enablement, OAuth/filter summaries, command hints, and a scoped mcp editor.
Give Codex app-server a scoped native MCP server	mcp.servers.<name>.codex	The codex block only affects Codex app-server thread projection and is stripped before native config handoff.
Run ACP-hosted harness sessions	openclaw acp and ACP Agents	ACP bridge mode does not accept per-session MCP server injection; configure gateway/plugin bridges instead.

If you are not sure which path you need, start with `openclaw mcp status --verbose`. It shows what OpenClaw has saved without starting any MCP servers.

MCP pages

This page is an index. openclaw mcp has six pages, one per reader job. Open the page that matches your task.

Page	Read it when
Run OpenClaw as an MCP server	An MCP client should read or send OpenClaw channel conversations through openclaw mcp serve.
Manage saved MCP servers	You are saving, inspecting, or approving third-party MCP servers for OpenClaw-managed runs.
JSON output shapes	You are scripting against status --json, doctor --json, or probe --json.
Transports and OAuth	You need a transport config field, or you are running the MCP OAuth login flow.
MCP in the Control UI	You want to edit or inspect MCP config from a browser.
MCP Apps	You are enabling or securing the MCP Apps host bridge.

Where each section moved

Every anchor from the previous single-page version still resolves here, so an existing link such as /cli/mcp#bridge-tools keeps working. Each entry points at the page that now holds the content.

• OpenClaw as an MCP server
• When to use serve
• How it works
• Client spawns the bridge
• Bridge connects to Gateway
• Sessions become MCP conversations
• Live events queue
• Optional Claude push
• Important behavior
• Choose a client mode
• Generic MCP clients
• Claude Code
• What serve exposes
• Usage
• Local Gateway
• Remote Gateway (token)
• Remote Gateway (password)
• Verbose / Claude off
• Bridge tools
• conversations_list
• conversation_get
• messages_read
• attachments_fetch
• events_poll
• events_wait
• messages_send
• permissions_list_open
• permissions_respond
• Event model
• Claude channel notifications
• off
• on
• auto (default)
• MCP client config
• Options
• --url
• --token
• --token-file
• --password
• --password-file
• --claude-channel-mode
• -v, --verbose
• Security and trust boundary
• Testing
• Troubleshooting
• No conversations returned
• events_poll or events_wait misses older messages
• Claude notifications do not show up
• Approvals are missing
• OpenClaw as an MCP client registry
• Important behavior
• Codex tool approvals
• Saved MCP server definitions
• Common server recipes
• Filesystem
• Memory
• Local script
• Remote HTTP
• Desktop/CUA
• JSON output shapes
• status --json
• doctor --json
• probe --json
• Stdio transport
• SSE / HTTP transport
• SSE / HTTP transport
• OAuth workflow
• Save the server
• Start login
• Use the manual fallback when needed
• Check authorization
• Clear credentials
• Streamable HTTP transport
• Control UI
• MCP Apps
• Current limits

Related

• Connect MCP servers
• CLI reference
• Plugins
• openclaw attach — launch Claude Code with a temporary session-scoped Gateway MCP grant