OpenClaw MCP: Connect External Tools Without Bloated Prompts

There are two bad ways to connect an AI agent to more tools. The first is to paste every workflow, credential hint, and tool manual into the prompt until the agent is buried before it starts. The second is to bolt on a one-off bridge for every client and channel, then hope routing still works when the conversation moves.

OpenClaw's MCP support is designed to avoid both mistakes. It gives external MCP clients a route into OpenClaw-backed channel conversations, and it gives OpenClaw a central place to store outbound MCP server definitions for runtimes that may consume them later. That sounds like plumbing because it is. Good agent ops is mostly plumbing that keeps the model from carrying infrastructure in prose.

This post is the operator map: when to use openclaw mcp serve, when to use the saved MCP server registry, where plugins fit, and what not to assume about routing, live events, approvals, or tool reachability.

MCP does two different jobs in OpenClaw

The OpenClaw docs are explicit that openclaw mcp has two jobs:

• Serve mode: run OpenClaw as an MCP server with openclaw mcp serve.
• Registry mode: manage OpenClaw-owned outbound MCP server definitions with list, show, set, and unset.

That distinction matters. serve means an external MCP client, for example Codex, Claude Code, or another compatible client, talks to OpenClaw. The registry commands mean OpenClaw stores definitions for other MCP servers under its own config so runtimes launched or configured by OpenClaw can consume them later.

If you mix those up, you will debug the wrong layer. openclaw mcp serve does not save your outbound tool server list. openclaw mcp set does not open a live channel bridge. They solve adjacent but separate problems.

Use serve mode when another client needs OpenClaw conversations

openclaw mcp serve starts a stdio MCP server. The MCP client owns that process. While the stdio session is open, the bridge connects to a local or remote OpenClaw Gateway over WebSocket and exposes routed channel conversations as MCP conversations and tools.

The documented lifecycle is straightforward:

1. The MCP client spawns openclaw mcp serve.
2. The bridge connects to the OpenClaw Gateway.
3. Routed sessions become MCP conversations and transcript/history tools.
4. Live events are queued in memory while the bridge is connected.
5. Claude-specific push notifications can be enabled for Claude channel mode.

The practical use case is clean: you already have OpenClaw channel sessions, and you want a compatible external client to read, wait, reply, or handle approvals through OpenClaw's existing routing instead of building a Slack bridge, a Discord bridge, and a Telegram bridge one by one.

# Local Gateway
openclaw mcp serve

# Remote Gateway with token file
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Remote Gateway with password file
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# Verbose logs, or disable Claude-specific notifications
openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off

For remote bridges, prefer --token-file or --password-file over inline secrets. The docs list inline token and password flags too, but file-based auth is the sane operational default because credentials do not end up sitting in shell history as easily.

What the bridge exposes

The bridge does not invent conversations. It uses existing Gateway session route metadata. A conversation appears when OpenClaw already has session state with a known route such as a channel, recipient or destination metadata, and optional account or thread identifiers.

The current MCP bridge exposes these tools:

• conversations_list for recent routed conversations.
• conversation_get for one conversation by session_key.
• messages_read for transcript history.
• attachments_fetch for non-text transcript content metadata.
• events_poll and events_wait for live events.
• messages_send for text replies through the stored route.
• permissions_list_open and permissions_respond for observed approval requests.

That is a useful surface, but it has boundaries. messages_send requires an existing conversation route and sends text only. events_poll and events_wait are live-queue tools; they do not replay older Gateway history by themselves. If the client needs backlog, read the transcript with messages_read.

If you are wiring AI tools into real channels, the hard part is not another clever prompt. It is routing, memory, approvals, and recovery. Get ClawKit and use the full operator playbook instead of rediscovering every edge case live.

Live events are not durable history

This is the edge case I would write on a sticky note. The bridge keeps an in-memory event queue while it is connected. Current event types include messages, exec approval requests and resolutions, plugin approval requests and resolutions, and Claude permission requests.

Because the queue is live-only, the bridge starts seeing queued events when it connects. If something happened before the MCP session existed, the live queue is not the historical source of truth. Use messages_read for durable transcript backlog.

Approvals have the same shape. permissions_list_open only shows approval requests the bridge observed during the current bridge session. It is not a permanent approval-history API. That is not a bug; it is a trust boundary. The MCP bridge is a live adapter, not a second database for all operational state.

Claude mode is optional client-specific behavior

The same bridge can run for generic MCP clients or for Claude Code-style channel behavior. Generic clients should use the standard tool surface: list conversations, read messages, poll or wait for events, send messages, and resolve approvals.

Claude mode adds Claude-specific channel notifications. The flags are --claude-channel-mode off, on, or auto. The docs say auto currently behaves the same as on, and there is no client capability detection yet.

I would leave Claude mode alone unless your client actually understands those notification methods. Extra live notification behavior is useful when the client supports it, but generic MCP clients do not need to pretend they are Claude.

Use the MCP registry when OpenClaw needs saved server definitions

The other half of openclaw mcp is not a bridge at all. It is a saved registry for outbound MCP server definitions under mcp.servers in OpenClaw config.

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"}'
openclaw mcp unset context7

The example config shape is simple:

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com"
      }
    }
  }
}

Typical fields include command, args, env, cwd or workingDirectory, and url. The important limitation is documented: these commands manage saved config only. They do not connect to the target MCP server, do not validate that the command or URL is reachable, and do not decide which runtime adapter supports which transport shape at execution time.

That is exactly why the registry helps with prompt bloat. You store the server definition as config. You do not paste a mini operations manual into AGENTS.md every time a runtime might need the same external tool server later.

Where plugins fit

MCP is not the only extension path in OpenClaw. Plugins are the native way to add capabilities such as channels, model providers, tools, skills, speech, image generation, web search, HTTP routes, CLI commands, services, and context engines.

The practical split I use is this:

• Use MCP server definitions when you want OpenClaw-managed runtimes to know about an external MCP server.
• Use openclaw mcp serve when an external MCP client needs access to routed OpenClaw conversations.
• Use a native plugin when the capability should belong inside OpenClaw itself, with manifest validation, runtime registration, and first-class configuration.

OpenClaw recognizes native plugins and compatible bundle layouts. Native plugins use openclaw.plugin.json plus runtime code. Bundle layouts such as Codex, Claude, and Cursor-compatible plugins are mapped into OpenClaw features when their layout matches what the runtime expects.

The plugin manifest is deliberately not runtime code. The docs say every native plugin must ship an openclaw.plugin.json file in the plugin root, and OpenClaw uses it to validate config without executing plugin code. Use the manifest for identity, config schema, auth/onboarding metadata, UI hints, and static capability snapshots. Put runtime behavior in plugin code and package metadata in package.json.

Minimal native plugin metadata

If a tool becomes permanent enough to deserve native ownership, the manifest starts small:

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

The manifest docs are strict for a reason. Unknown plugin ids in config are errors. A broken or missing manifest is treated as a plugin error and blocks config validation. Unknown channel keys are errors unless a plugin declares that channel id. If a plugin config exists but the plugin is disabled, OpenClaw preserves the config and surfaces a warning.

That gives operators a cleaner failure mode than “the prompt mentioned a tool, so maybe it exists.” Either the plugin is discoverable, configured, and valid, or Doctor and plugin inspection can explain the problem.

The install-and-verify loop

The plugin docs give a simple operator loop:

openclaw plugins list
openclaw plugins install npm:@acme/openclaw-plugin
openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json

Use --runtime when you need to prove registered tools, services, gateway methods, hooks, or plugin-owned CLI commands. A plain inspect can be a cold manifest and registry check that avoids importing plugin runtime. That distinction is useful: sometimes you want cheap validation; sometimes you need proof that the runtime surface actually registered.

If config is invalid, the docs say install normally fails closed and points to openclaw doctor --fix. Gateway startup can isolate invalid config for one plugin, skip that plugin during load, and keep other plugins and channels online. That is the kind of behavior you want in production: one bad extension should not take the whole agent offline when it can be safely isolated.

MCP versus ACP

The MCP docs explicitly point operators to openclaw acp when OpenClaw should host a coding harness session itself and route that runtime through ACP. Use MCP serve when another MCP client should talk to OpenClaw-backed conversations. Use ACP when the coding runtime should be hosted inside the OpenClaw session model.

This is not just naming. It decides who owns the session lifecycle. With MCP serve, the external MCP client owns the stdio process and OpenClaw exposes routed conversations. With ACP, OpenClaw hosts the coding harness session. If you choose the wrong one, you may get a connection that technically works but has the wrong operational owner.

If you are already using ACP for coding workspaces, keep that path for hosted coding sessions. Reach for MCP when you need the more general external-client bridge or saved MCP server definitions.

The operator takeaway

OpenClaw MCP is not a magic “add every tool” button. It is a routing and registry layer. openclaw mcp serve lets external MCP clients reach OpenClaw-backed channel conversations through existing Gateway route metadata. The saved registry under mcp.servers keeps outbound MCP server definitions in config instead of in prompt sludge. Native plugins cover capabilities that should live inside OpenClaw with manifests, validation, and runtime registration.

The pattern is the same one that keeps serious agents useful: put durable infrastructure in config and code, not in a swollen prompt. Let the model reason over the current task. Let Gateway own routing. Let the MCP bridge expose live conversation tools. Let plugins own first-class capabilities. Then inspect and verify the layer you actually changed instead of hoping the agent inferred it from a paragraph of instructions.

Want the complete guide? Get ClawKit — $9.99