docs/cli/mcp.md
openclaw mcp has two jobs:
openclaw mcp servelist, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, and unsetIn other words:
serve is OpenClaw acting as an MCP serverUse openclaw acp when OpenClaw should host a coding harness session itself and route that runtime through ACP.
OpenClaw has several MCP surfaces. Pick the one that matches who owns the agent runtime and who owns the tools.
| 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 /mcp | 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. |
This is the openclaw mcp serve path.
serveUse openclaw mcp serve when:
Use openclaw acp instead when OpenClaw should host the coding runtime itself and keep the agent session inside OpenClaw.
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.
Use the same bridge in two different ways:
<Tabs> <Tab title="Generic MCP clients"> Standard MCP tools only. Use `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send`, and the approval tools. </Tab> <Tab title="Claude Code"> Standard MCP tools plus the Claude-specific channel adapter. Enable `--claude-channel-mode on` or leave the default `auto`. </Tab> </Tabs> <Note> Today, `auto` behaves the same as `on`. There is no client capability detection yet. </Note>serve exposesThe 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:
channelaccountIdthreadIdThis gives MCP clients one place to:
The current bridge exposes these MCP tools:
<AccordionGroup> <Accordion title="conversations_list"> Lists recent session-backed conversations that already have route metadata in Gateway session state.Useful filters:
- `limit`
- `search`
- `channel`
- `includeDerivedTitles`
- `includeLastMessage`
Use this when a generic MCP client needs near-real-time delivery without a Claude-specific push protocol.
Current behavior:
- requires an existing conversation route
- uses the session's channel, recipient, account id, and thread id
- sends text only
- `allow-once`
- `allow-always`
- `deny`
The bridge keeps an in-memory event queue while it is connected.
Current event types:
messageexec_approval_requestedexec_approval_resolvedplugin_approval_requestedplugin_approval_resolvedclaude_permission_requestThe 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.
<Tabs> <Tab title="off"> `--claude-channel-mode off`: standard MCP tools only. </Tab> <Tab title="on"> `--claude-channel-mode on`: enable Claude channel notifications. </Tab> <Tab title="auto (default)"> `--claude-channel-mode auto`: current default; same bridge behavior as `on`. </Tab> </Tabs>When Claude channel mode is enabled, the server advertises Claude experimental capabilities and can emit:
notifications/claude/channelnotifications/claude/channel/permissionCurrent bridge behavior:
user transcript messages are forwarded as notifications/claude/channelyes abcde or no abcde, the bridge converts that to notifications/claude/channel/permissionThis is intentionally client-specific. Generic MCP clients should rely on the standard polling tools.
Example stdio client config:
{
"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.
openclaw mcp serve supports:
The bridge does not invent routing. It only exposes conversations that Gateway already knows how to route.
That means:
messages_send can only reply through an existing stored routeIf a conversation is missing from conversations_list, the usual cause is not MCP configuration. It is missing or incomplete route metadata in the underlying Gateway session.
OpenClaw ships a deterministic Docker smoke for this bridge:
pnpm test:docker:mcp-channels
That smoke:
openclaw mcp serveThis 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.
- the client kept the stdio MCP session open
- `--claude-channel-mode` is `on` or `auto`
- the client actually understands the Claude-specific notification methods
- the inbound message happened after the bridge connected
This is the openclaw mcp list, show, status, doctor, probe, add, set,
configure, tools, login, logout, reload, and unset path.
These commands do not expose OpenClaw over MCP. They manage OpenClaw-owned MCP server definitions under mcp.servers in OpenClaw config.
Those saved definitions are for runtimes that OpenClaw launches or configures later, such as embedded OpenClaw and other runtime adapters. OpenClaw stores the definitions centrally so those runtimes do not need to keep their own duplicate MCP server lists.
<AccordionGroup> <Accordion title="Important behavior"> - these commands only read or write OpenClaw config - `status`, `list`, `show`, `doctor` without `--probe`, `set`, `configure`, `tools`, `logout`, `reload`, and `unset` do not connect to the target MCP server - `login` performs the MCP OAuth network flow for the configured HTTP server and saves the resulting local credentials - `status --verbose` prints resolved transport, auth, timeout, filter, and parallel-tool-call hints without connecting - `doctor` checks saved definitions for local setup problems such as missing stdio commands, invalid working directories, missing TLS files, disabled servers, literal sensitive header/env values, and incomplete OAuth authorization - `doctor --probe` adds the same live connection proof as `probe` after static checks pass - `probe` connects to the selected server or all configured servers, lists tools, and reports capabilities/diagnostics - `add` builds a definition from flags and probes before saving unless `--no-probe` is set or OAuth authorization is needed first - runtime adapters decide which transport shapes they actually support at execution time - `enabled: false` keeps a server saved but excludes it from embedded runtime discovery - `timeout` and `connectTimeout` set per-server request and connection timeouts in seconds - `supportsParallelToolCalls: true` marks servers that adapters can call concurrently - HTTP servers can use static headers, OAuth login, TLS verification control, and mTLS certificate/key paths - embedded OpenClaw exposes configured MCP tools in normal `coding` and `messaging` tool profiles; `minimal` still hides them, and `tools.deny: ["bundle-mcp"]` disables them explicitly - per-server `toolFilter.include` and `toolFilter.exclude` filter discovered MCP tools before they become OpenClaw tools - servers that advertise resources or prompts also expose utility tools for listing/reading resources and listing/fetching prompts; those generated utility names (`resources_list`, `resources_read`, `prompts_list`, `prompts_get`) use the same include/exclude filter - dynamic MCP tool-list changes invalidate the cached catalog for that session; the next discovery/use refreshes from the server - repeated MCP tool request/protocol failures pause that server briefly so one broken server does not consume the whole turn - session-scoped bundled MCP runtimes are reaped after `mcp.sessionIdleTtlMs` milliseconds of idle time (default 10 minutes; set `0` to disable) and one-shot embedded runs clean them up at run end </Accordion> </AccordionGroup>Runtime adapters may normalize this shared registry into the shape their downstream client expects. For example, embedded OpenClaw consumes OpenClaw transport values directly, while Claude Code and Gemini receive CLI-native type values such as http, sse, or stdio.
Codex app-server also honors an optional codex block on each server. This is
OpenClaw projection metadata for Codex app-server threads only; it does not
change ACP sessions, generic Codex harness config, or other runtime adapters.
Use non-empty codex.agents to project a server only into specific OpenClaw
agent ids. Empty, blank, or invalid agent lists are rejected by config
validation and omitted by the runtime projection path instead of becoming
global. Use codex.defaultToolsApprovalMode (auto, prompt, or approve)
to emit Codex's native default_tools_approval_mode for a trusted server.
OpenClaw strips the codex metadata before handing the native mcp_servers
config to Codex.
OpenClaw also stores a lightweight MCP server registry in config for surfaces that want OpenClaw-managed MCP definitions.
Commands:
openclaw mcp listopenclaw mcp show [name]openclaw mcp status [--verbose]openclaw mcp doctor [name] [--probe]openclaw mcp probe [name]openclaw mcp add <name> [flags]openclaw mcp set <name> <json>openclaw mcp configure <name> [flags]openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]openclaw mcp login <name> [--code code]openclaw mcp logout <name>openclaw mcp reloadopenclaw mcp unset <name>Notes:
list sorts server names.show without a name prints the full configured MCP server object.status classifies configured transports without connecting. --verbose includes resolved launch, timeout, OAuth, filter, and parallel-call details.doctor performs static checks without connecting. Add --probe when the command should also verify that enabled servers connect.probe connects and reports tool counts, resources/prompts support, list-change support, and diagnostics.add accepts stdio flags such as --command, --arg, --env, and --cwd, or HTTP flags such as --url, --transport, --header, --auth oauth, TLS, timeout, and tool-selection flags.set expects one JSON object value on the command line.configure updates enablement, tool filters, timeouts, OAuth, TLS, and parallel-tool-call hints without replacing the whole server definition.tools updates per-server tool filters. Include/exclude entries are MCP tool names and simple * globs.login runs the OAuth flow for HTTP servers configured with auth: "oauth". The first run prints an authorization URL; rerun with --code after approval.logout clears stored OAuth credentials for the named server without removing the saved server definition.reload disposes cached in-process MCP runtimes. Gateway or agent processes in another process still need their own reload or restart path.transport: "streamable-http" for Streamable HTTP MCP servers. openclaw mcp set also normalizes CLI-native type: "http" to the same canonical config shape for compatibility.unset fails if the named server does not exist.Examples:
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'
openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'
openclaw mcp login docs
openclaw mcp logout docs
openclaw mcp unset context7
These examples save server definitions only. Run openclaw mcp doctor --probe afterward to prove that the server starts and exposes tools.
Scope filesystem servers to the smallest directory tree that the agent should read or edit.
Use a tool filter if the server exposes write tools that should not be available to normal agents.
`doctor` checks that `cwd` exists and that the command resolves from the configured environment.
Use OAuth when the remote server supports it. If the server requires static headers, avoid committing literal bearer tokens.
Direct desktop-control servers inherit the permissions of the process they launch. Use narrow tool filters and OS-level permission prompts.
Use --json for scripts and dashboards. Field sets can grow over time, so consumers should ignore unknown keys.
`doctor --json` exits nonzero when any enabled checked server has an error. Warnings are reported but do not make the command fail by themselves.
`probe` opens a live MCP client session. Use it for reachability and capability proof, not for static config audits.
Example config shape:
{
"mcp": {
"servers": {
"context7": {
"command": "uvx",
"args": ["context7-mcp"]
},
"docs": {
"url": "https://mcp.example.com",
"transport": "streamable-http",
"timeout": 20,
"connectTimeout": 5,
"supportsParallelToolCalls": true,
"auth": "oauth",
"oauth": {
"scope": "docs.read"
},
"sslVerify": true,
"clientCert": "/path/to/client.crt",
"clientKey": "/path/to/client.key",
"toolFilter": {
"include": ["search_*"],
"exclude": ["admin_*"]
}
}
}
}
}
Launches a local child process and communicates over stdin/stdout.
| Field | Description |
|---|---|
command | Executable to spawn (required) |
args | Array of command-line arguments |
env | Extra environment variables |
cwd / workingDirectory | Working directory for the process |
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 env block. Blocked keys include NODE_OPTIONS, NODE_REDIRECT_WARNINGS, NODE_REPL_EXTERNAL_MODULE, NODE_REPL_HISTORY, NODE_V8_COVERAGE, PYTHONSTARTUP, PYTHONPATH, PERL5OPT, RUBYOPT, SHELLOPTS, PS4, and similar runtime-control variables. Startup rejects these with a configuration error so they cannot inject an implicit prelude, swap the interpreter, enable a debugger, or redirect runtime output against the stdio process. Ordinary credential, proxy, and server-specific env vars (GITHUB_TOKEN, HTTP_PROXY, custom *_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 env.
</Warning>
Connects to a remote MCP server over HTTP Server-Sent Events.
| Field | Description |
|---|---|
url | HTTP or HTTPS URL of the remote server (required) |
headers | Optional key-value map of HTTP headers (for example auth tokens) |
connectionTimeoutMs | Per-server connection timeout in ms (optional) |
connectTimeout | Per-server connection timeout in seconds (optional) |
timeout / requestTimeoutMs | Per-server MCP request timeout in seconds or ms |
auth: "oauth" | Use MCP OAuth token storage and openclaw mcp login |
sslVerify | Set false only for explicitly trusted private HTTPS endpoints |
clientCert / clientKey | mTLS client certificate and key paths |
supportsParallelToolCalls | Hint that concurrent calls are safe for this server |
Example:
{
"mcp": {
"servers": {
"remote-tools": {
"url": "https://mcp.example.com",
"auth": "oauth",
"timeout": 20,
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
Sensitive values in url (userinfo) and headers are redacted in logs and status output. openclaw mcp doctor warns when sensitive-looking headers or env entries contain literal values, so operators can move those values out of committed config.
OAuth is for HTTP MCP servers that advertise the MCP OAuth flow. Static Authorization headers are ignored for a server while auth: "oauth" is enabled.
```bash
openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'
```
```bash
openclaw mcp login docs
```
OpenClaw prints the authorization URL and stores temporary OAuth verifier state under the OpenClaw state directory.
```bash
openclaw mcp login docs --code abc123
```
```bash
openclaw mcp status --verbose
openclaw mcp doctor docs --probe
```
```bash
openclaw mcp logout docs
```
If the provider rotates tokens or the authorization state gets stuck, run openclaw mcp logout <name>, then repeat login. logout can clear credentials for a saved HTTP server even after auth: "oauth" has been removed from config, as long as the server name and URL still identify the credential store entry.
streamable-http is an additional transport option alongside sse and stdio. It uses HTTP streaming for bidirectional communication with remote MCP servers.
| Field | Description |
|---|---|
url | HTTP or HTTPS URL of the remote server (required) |
transport | Set to "streamable-http" to select this transport; when omitted, OpenClaw uses sse |
headers | Optional key-value map of HTTP headers (for example auth tokens) |
connectionTimeoutMs | Per-server connection timeout in ms (optional) |
connectTimeout | Per-server connection timeout in seconds (optional) |
timeout / requestTimeoutMs | Per-server MCP request timeout in seconds or ms |
auth: "oauth" | Use MCP OAuth token storage and openclaw mcp login |
sslVerify | Set false only for explicitly trusted private HTTPS endpoints |
clientCert / clientKey | mTLS client certificate and key paths |
supportsParallelToolCalls | Hint that concurrent calls are safe for this server |
OpenClaw config uses transport: "streamable-http" as the canonical spelling. CLI-native MCP type: "http" values are accepted when saved through openclaw mcp set and repaired by openclaw doctor --fix in existing config, but transport is what embedded OpenClaw consumes directly.
Example:
{
"mcp": {
"servers": {
"streaming-tools": {
"url": "https://mcp.example.com/stream",
"transport": "streamable-http",
"connectTimeout": 10,
"timeout": 30,
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
The browser Control UI includes a dedicated MCP settings page at /mcp. It shows configured server counts, enabled/OAuth/filter summaries, per-server transport rows, enable/disable controls, common CLI commands, and a scoped editor for the mcp config section.
Use the page for operator edits and quick inventory. Use openclaw mcp doctor --probe or openclaw mcp probe when you need live server proof.
Operator workflow:
mcp config section for structural changes such as new servers, headers, TLS, OAuth metadata, or tool filters.openclaw mcp doctor --probe when you need live proof that the edited server starts and lists tools.Notes:
openclaw mcp reload, Gateway config publish, or process restart depending on which process owns the MCP clientsThis page documents the bridge as shipped today.
Current limits:
permissions_list_open only includes approvals observed while the bridge is connected