Skip to content

MCP Integration: A Bolt-on Toolbox for Claw ​

The browser from the previous lesson gave Claw hands to go online; this lesson equips it with a bolt-on toolbox. The official docs on MCP (Model Context Protocol) sum up its essence in one sentence: "an agent borrows tools from another program"—the agent borrows tools from another program. An MCP server exposes tools, resources, and prompts; once OpenClaw connects to it, those tools appear in your agent's tool catalog, ready to use on demand.

OpenClaw MCP integration has three faces: clicking around the Control UI, openclaw mcp command line, mcp.servers configuration file—different paths, same destination: they all write the same configuration. There is also a reverse direction: openclaw mcp serve exposes OpenClaw's channel conversations in reverse to MCP clients like Claude Code / Codex. All examples are based on OpenClaw v2026.10.9.

What you'll be able to do after this lesson ​

  • Attach MCP servers to OpenClaw in three ways (Control UI / openclaw mcp CLI / mcp.servers configuration file)
  • Verify with openclaw mcp doctor <name> --probe that a server is really online and really exposing tools
  • Use --include / toolFilter / openclaw mcp tools to expose only the tools your agent needs
  • Complete login for remote HTTP servers that require OAuth
  • Use openclaw mcp serve to expose OpenClaw channel conversations in reverse to Claude Code / Codex

Your current predicament ​

  • Claw can chat, run commands, and go online, but it's stuck the moment it touches internal systems or specific data sources—it has no matching tools
  • You found a ready-made MCP server but don't know how to hook it up to OpenClaw: where to write the configuration, what the format looks like, how to verify after connecting—it's all guesswork
  • You worry that bolt-on tools run wild: once you connect a third-party server, will its tools bypass the permissions you've set

When to use this technique ​

When you need to:

  • Give Claw capabilities that built-in tools don't have: reading and writing specific directories, external memory stores, internal APIs, desktop control, and more…
  • Reuse ready-made servers from the MCP ecosystem—npx one command to attach, no need to write your own plugins
  • Have multiple agents / multiple runtimes share the same tool definitions—OpenClaw stores them centrally in mcp.servers, so runtimes don't each maintain their own copy

And you don't want to:

  • Modify the OpenClaw core or write a plugin for every new capability
  • Cram tool usage into prompts—MCP tools come with their own schema, and agents discover them automatically

🎒 Prerequisites ​

Core Idea ​

Get your bearings first. MCP has two directions—don't mix them up:

DirectionWho is the MCP serverWhat it doesEntry point
Integration (this lesson's focus)A third-party programOpenClaw connects to it and lends its tools to your own agentSettings → MCP / openclaw mcp add / mcp.servers
Reverse exposure (advanced)OpenClaw itselfOther MCP clients read / send OpenClaw's channel conversationsopenclaw mcp serve

Three bottom lines stated explicitly in the official docs:

  1. Server definitions are stored uniformly under mcp.servers in the configuration; the three integration faces write the same thing;
  2. MCP tools go through the same tool-profile / tool-policy controls—"connecting a server does not bypass your policy": integration does not mean approval;
  3. Don't put credentials in configuration literals—store sensitive headers and environment variables using supported secret mechanisms.

Three transports, choose based on where the server lives:

TransportBest forWhat to fill in
StdioServers launched by a local commandcommand + args (optional cwd / env)
Streamable HTTPRemote servershttp(s):// URL
SSELegacy remote servershttp(s):// URL

The rule in one sentence: choose either command (stdio) or a URL (HTTP-family), not both—configuring both will be rejected by configuration validation; enabled: false keeps the definition but doesn't connect; the server name __proto__ is a reserved word, so pick a different name.

Three access surfaces, choose based on your preference:

Access surfaceBest for whomCharacteristics
Control UI (Settings → MCP)Those who don't want to touch the terminalCan also be modified while the Gateway is running; OAuth is just a click in the browser
CLI (openclaw mcp)Those who want copy-paste and scriptingWrite-type commands require exclusive state; stop the Gateway first (see pitfall 1)
Configuration file (mcp.servers)Those who need version control and bulk initializationMost complete set of fields, edit directly

Follow Along ​

Step 1: Get a picture of OpenClaw MCP's current state (openclaw mcp status --verbose) ​

Why: Before acting, see what you already have. status only reads the configuration and doesn't connect to any server, so it can run even while the Gateway is running.

bash
openclaw mcp status --verbose

You should see: A list of saved server definitions—each server's transport type, launch arguments, timeouts, OAuth status, and tool filters. On a fresh install the list is empty, which is exactly where you start from zero.

💡 When unsure, run it first

The official advice is the same: if you're not sure which path to take, run openclaw mcp status --verbose first—it tells you what OpenClaw has stored, without starting any MCP servers.

Step 2: Add your first MCP server (choose any of three methods) ​

Why: Use the memory server from the official recipes as your first one—npx gets it running with a single command, zero configuration. All three methods write to the same mcp.servers, so just pick whichever feels comfortable.

Method A (recommended): CLI, done in one downtime window ​

Why it's wrapped in stop / restart: Write-type commands like add require exclusive access to the state directory; if the Gateway is running and holding it, the write will be rejected with a prompt to stop first and retry—this is by design, not a malfunction.

bash
openclaw gateway stop
openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory
openclaw gateway restart

You should see: add performs a check before saving the definition (a check is included by default, unless --no-probe is used or OAuth must be completed first); after saving, restart brings the Gateway back up with the new definition.

  • Quick check: openclaw mcp list shows memory

Method B: Add directly at runtime via Control UI ​

  1. Open the Control UI and go to Settings → MCP (typing /settings/mcp directly in the browser address bar, or the alias /mcp, also works).
  2. Under Configured servers, select Add server.
  3. Give it a unique name and choose a transport: Streamable HTTP / SSE / Stdio.
  4. For HTTP-family transports, fill in the server's http:// or https:// URL; for stdio, fill in the launch command and arguments.
  5. Select Add server—the definition is written into mcp.servers via the Gateway.

You should see: The server appears in the list, and each row can be enabled, disabled, or deleted; advanced options like headers, environment variables, OAuth, TLS, and timeouts are in the sectioned configuration editor further down the page.

You can also add from the chat window: + → Plugins → Add MCP server… (requires administrator privileges); choose the scope This session (this session only) or Everywhere (global).

Method C: Write the configuration file directly ​

The same memory server, written into mcp.servers, looks like this (JSON5):

json5
{
  mcp: {
    servers: {
      memory: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-memory"],
        enabled: true,
      },
    },
  },
}

You should see: After saving, on installations with Gateway hot reload enabled the change takes effect immediately—modified or deleted servers are retired at once, and the next turn's tool discovery uses the new definitions; untouched servers keep their connections and caches.

Step 3: Health check—doctor --probe proves the server is actually online ​

Why: The official wording is "Saving a definition proves nothing about reachability"—saving a definition proves nothing; being able to connect is what counts. The troubleshooting ladder, from lightest to heaviest:

bash
openclaw mcp status --verbose      # 只读配置,随时能跑
openclaw mcp doctor memory         # 静态检查,随时能跑
openclaw mcp doctor memory --probe # 真实连接,要独占状态(Gateway 在跑会拒绝)
openclaw mcp probe memory          # 只做真实连接、列工具(同样要独占状态)

You should see: doctor first checks local configuration problems—missing stdio command, nonexistent cwd, missing TLS files, disabled servers, plaintext sensitive values, incomplete OAuth authorization; --probe then opens a real connection and reports the tools and other capabilities the server exposes.

If a server is temporarily unreachable, don't rush to troubleshoot: OpenClaw's built-in client will reconnect with exponential backoff—starting at 30 seconds, doubling each time, up to a maximum of 10 minutes; recovery runs in the background, tools become available at the next turn boundary, without blocking the current conversation.

  • Quick check: the tool list appears in the output of doctor --probe

Step 4: Filter tools, expose only what's needed ​

Why: A server may come with a pile of tools; exposing all of them is both noisy and insecure. The filesystem server is the official canonical example—keep only read and search, no write:

bash
openclaw gateway stop
openclaw mcp add files \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg "$HOME/Documents" \
  --include 'read_file,list_directory,search_files'
openclaw mcp doctor files --probe
openclaw gateway restart

You should see: doctor files --probe connects to the server and reports the tools; --include filtering happens before tools enter the agent's catalog, so write-type tools won't appear. The official recommendation is to scope the filesystem server to the minimal directory tree the agent needs.

To adjust a saved server after the fact, use tools (which also requires a downtime window):

bash
openclaw mcp tools files --include 'read_file,list_directory,search_files'
openclaw mcp tools files --clear   # 清除过滤

In the config file these correspond to toolFilter.include / toolFilter.exclude, with * wildcard support. You can also fine-tune within a session: in the chat window + → Plugins → Tool access, where you can view or disable the session's tools one by one.

Step 5: Connect a remote server that requires OAuth login ​

Why: Remote HTTP servers commonly use OAuth authentication. Taking the official docs server recipe as an example, when using add you declare it directly:

bash
openclaw gateway stop
openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope docs.read \
  --timeout 20 \
  --connect-timeout 5 \
  --include 'search,read_*'
openclaw mcp login docs
openclaw gateway restart

Why shut down first: openclaw mcp login only runs offline (it needs exclusive access to the state directory to complete the OAuth callback).

What you should see: The terminal prints an authorization URL; after you complete authorization in the browser, OpenClaw usually captures the loopback redirect automatically and stores the credentials. When the browser cannot reach the callback listener (remote or headless environments), fall back to the printed --code command.

It's even easier in the Control UI: in Settings → MCP, an admin can simply select Sign in for an enabled OAuth server, approve access in the browser, and return to Settings.

Checkpoint ✅ ​

  • openclaw mcp status --verbose can list the servers you saved along with their transport types
  • openclaw mcp doctor <name> --probe connected to the server and listed its tools
  • In a conversation, you had Claw use a new tool once and it called it successfully
  • You tightened the tool exposure surface with openclaw mcp tools <name> --include …
  • You can explain why write-type CLI commands require stopping the Gateway first (or using the Control UI instead)

Pitfall reminders ​

❌ Gateway running, CLI write commands rejected ​

add / set / configure / tools / unset / login / logout / probe / doctor --probe all require exclusive access to the state directory. When the Gateway is running and holding it, the command will refuse to write and show a "stop first, then retry" hint.

The right approach: either openclaw gateway stop → operate → openclaw gateway restart, or just use the Control UI (Settings → MCP supports runtime modification and sign-in). list / show / status / doctor (without --probe) are unaffected and can run anytime while the Gateway is running.

❌ The server is in the list, but there are no tools in the conversation ​

Saved ≠ reachable. Troubleshooting order:

bash
openclaw mcp doctor <name> --probe
  • Connected but fewer tools than expected → check whether toolFilter.include / toolFilter.exclude are filtering too aggressively
  • Servers with enabled: false keep the definition but do not connect, so they never enter tool discovery
  • Everything checks out but it still doesn't work → the changes may not have reached the running agent: openclaw mcp reload only refreshes the runtime of the current CLI process; agents on the Gateway or elsewhere need their own reload / config publish / restart

❌ stdio server won't start ​

Three common causes, all of which doctor can detect:

  • command can't be resolved in the Gateway process environment—just because you can run it in your own shell doesn't mean it runs in the Gateway's environment
  • The cwd directory doesn't exist
  • Arguments placed in the wrong position: arguments belong to args, don't concatenate them into command; an explicit transport: "stdio" must have a non-empty command

❌ HTTP server returns 401 (authentication refused) ​

Startup logs and directory diagnostics will report authentication refused (401). This means the server requires authentication—it's not that OpenClaw is broken:

  • OAuth servers: confirm that auth: "oauth" and the required oauth metadata are configured, then follow the login flow from step 5
  • Static credentials: check the header / credential configuration for that server in mcp.servers—and don't write tokens in plaintext into the config, use the secret mechanism to store them

Advanced tips (optional) ​

**The reverse: expose channel conversations to Claude Code / Codex. ** openclaw mcp serve lets OpenClaw act as an MCP server itself (stdio): an MCP client launches and holds this process, the bridge connects via WebSocket to a local or remote Gateway, turning already-routed channel sessions into MCP sessions.

bash
openclaw mcp serve                                                 # 本地 Gateway
openclaw mcp serve --url wss://gateway-host:18789 \
  --token-file ~/.openclaw/gateway.token                          # 远程 Gateway(token)

Tools exposed by the bridge: conversations_list, conversation_get, messages_read, attachments_fetch, events_poll, events_wait, messages_send, plus permissions_list_open / permissions_respond for handling exec and plugin approvals. Note that the event queue is real-time—once the bridge disconnects it's gone; use messages_read to read historical messages.

**Set an approval mode for trusted servers. ** Codex's MCP tool approval follows the session's permission posture by default; trusted servers can be explicitly relaxed:

bash
openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory \
  --approval approve

Three levels: approve (skip per-call approval, only for trusted servers) / prompt (ask every time) / auto (based on tool safety annotations). Saved servers can be changed individually with openclaw mcp configure <name> --approval ….

**Per-server timeouts and concurrency. ** connectionTimeoutMs / requestTimeoutMs set connection and request timeouts (in milliseconds); supportsParallelToolCalls: true marks servers that can be called concurrently by adapters.

Lesson summary ​

✅ MCP = the protocol by which an agent borrows tools from other programs. Once OpenClaw connects to an MCP server, the tools automatically enter the agent's tool catalog, and they go through the same tool-profile / tool-policy controls—integration doesn't bypass your policies.

✅ OpenClaw MCP integration is three sides of one whole: Control UI (Settings → MCP), CLI (openclaw mcp), and the config file (mcp.servers), all writing the same configuration.

✅ Verification chain: status --verbose (read-only config) → doctor (static check) → doctor --probe / probe (real connection, lists tools). Saving a definition proves nothing.

✅ Tighten the exposure surface: --include / toolFilter / openclaw mcp tools; scope filesystem servers to the smallest directory tree; within a session use + → Plugins → Tool access to disable tools one by one.

✅ Write-type CLI commands (add / set / configure / tools / unset / login / logout / probe / doctor --probe) need exclusive access to the state—if the Gateway is running, stop it first and retry, or use the Control UI instead.

✅ The other direction openclaw mcp serve: OpenClaw acts as an MCP server, lending channel conversations to Claude Code / Codex.

Key configuration fieldRecommended valueDescription
mcp.servers.<name>.transportstreamable-http / sse / stdioUse the HTTP family for remote servers and stdio for local commands
command + args vs urlPick one of the twoFill in the command and arguments for stdio, the URL for HTTP; filling in both will be rejected by validation
toolFilter.include / excludeKeep only the tools you need (* wildcards supported)Filtering happens before tools enter the catalog
enabledtrue / falsefalse keep the definition but don't connect
connectionTimeoutMs / requestTimeoutMs5000 / 20000Per-server connection / request timeout (milliseconds)
auth"oauth"OAuth for HTTP servers, pair with openclaw mcp login to use
codex.defaultToolsApprovalModeapprove / prompt / autoCodex tool approval mode, --approval write

CLI quick reference: openclaw mcp list / show / status / doctor / probe / add / set / configure / tools / login / logout / reload / unset. See CLI Commands and Configuration Quick Reference for the complete command table.

Next Lesson Preview ​

The workflow trio is complete: scheduled tasks handle when to act, the browser handles fetching things from the web, and MCP handles plug-in capabilities. In the next lesson, Scenario Practice: Choose Your Route, pick a route based on your role and combine the trio into real work.

You will learn:

  • Domestic IM integration matrix: how to connect WeCom, Feishu, WeChat / QQ / Yuanbao respectively
  • Combine scheduling + web browsing into Daily Morning Brief and Web Monitoring
  • Have Claw write code and watch PRs: Writing Code and GitHub On-Call
  • Server deployment: keep Claw online 7×24 on a VPS / Docker

Related Tutorials ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.