mcp.md

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.

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

Choose the right MCP path

OpenClaw as an MCP server

This is the openclaw mcp serve path.

When to use serve

Use 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 openclaw acp instead when OpenClaw should host the coding runtime itself and keep the agent session inside OpenClaw.

How it works

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.

Choose a client mode

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

• channel
• recipient or destination metadata
• optional accountId
• optional 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

Bridge tools

Filters: `limit` (max 500), `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`

Event model

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

Current event types:

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

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.

When Claude channel mode is enabled, the server advertises Claude experimental capabilities and can emit:

• notifications/claude/channel
• notifications/claude/channel/permission

Current bridge behavior:

• inbound user transcript messages are forwarded as notifications/claude/channel
• Claude permission requests received over MCP are tracked in-memory
• if the command owner in the linked conversation later sends yes <id> or no <id> (<id> is the 5-letter request id, excluding l), the bridge converts that to 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:

{
  "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

openclaw mcp serve supports:

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

pnpm test:docker:mcp-channels

That smoke runs a single container: it seeds conversation state, starts the Gateway, then spawns openclaw mcp serve as a stdio child process and drives it as an MCP client. It verifies conversation discovery, transcript reads, attachment metadata reads, live event queue behavior, and Claude-style channel and permission notifications over the real stdio MCP bridge. Outbound send routing (messages_send reusing the stored conversation route) is covered separately by unit tests in src/mcp/channel-server.test.ts.

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

- 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

OpenClaw as an MCP client registry

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-managed MCP server definitions under mcp.servers in OpenClaw config. They do not read mcporter servers from config/mcporter.json.

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.

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.

Saved MCP server definitions

Commands:

• openclaw mcp list
• openclaw 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 reload
• openclaw 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, including when stored OAuth tokens require additional authorization.
• 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. Add --probe to verify the updated server before saving.
• 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 for the current CLI process only. Gateway or agent processes in another process still need their own reload or restart path.
• Use 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

Common server recipes

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.

JSON output shapes

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`-level issue. `warning` and `info` issues are reported but do not make the command fail by themselves.

`probe --json` opens a live MCP client session and prints its result directly; unlike `status`/`doctor`, the output has no top-level `path` field. `resources` and `prompts` keys are present only when the server actually advertises that capability (a server without prompts omits the `prompts` key rather than reporting `false`). Use `probe` 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_*"]
        }
      }
    }
  }
}

Stdio transport

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

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

```bash
openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'
```

For an auth-profile-backed bearer, save the profile binding:

```bash
openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'
```

```bash
openclaw mcp login docs
```

OpenClaw prints the authorization URL and stores temporary OAuth verifier state in shared SQLite.

```bash
openclaw mcp login docs --code abc123
```

```bash
openclaw mcp status --verbose
openclaw mcp doctor docs --probe
```

```bash
openclaw mcp logout docs
```

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectTimeout": 10,
        "timeout": 30,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

openclaw config set mcp.apps.enabled true --strict-json

{
  mcp: {
    apps: {
      enabled: true,
      sandboxOrigin: "https://mcp-apps.example.com",
      sandboxPort: 18790,
    },
  },
}

{
  mcp: {
    apps: { enabled: true },
    servers: {
      "basic-react": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],
      },
    },
  },
}