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 mcpCLI /mcp.serversconfiguration file) - Verify with
openclaw mcp doctor <name> --probethat a server is really online and really exposing tools - Use
--include/toolFilter/openclaw mcp toolsto expose only the tools your agent needs - Complete login for remote HTTP servers that require OAuth
- Use
openclaw mcp serveto 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—
npxone 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
- You've read this stage's overview Efficient Workflows: Automation, Browsers, and MCP
- OpenClaw is installed and onboarded (if not, see Get OpenClaw Running in 5 Minutes first)
- You have the server info you want to attach on hand: the launch command for a local stdio server, or the URL of a remote HTTP server
- You can open the Control UI (needed for method B)
Core Idea
Get your bearings first. MCP has two directions—don't mix them up:
| Direction | Who is the MCP server | What it does | Entry point |
|---|---|---|---|
| Integration (this lesson's focus) | A third-party program | OpenClaw connects to it and lends its tools to your own agent | Settings → MCP / openclaw mcp add / mcp.servers |
| Reverse exposure (advanced) | OpenClaw itself | Other MCP clients read / send OpenClaw's channel conversations | openclaw mcp serve |
Three bottom lines stated explicitly in the official docs:
- Server definitions are stored uniformly under
mcp.serversin the configuration; the three integration faces write the same thing; - MCP tools go through the same tool-profile / tool-policy controls—"connecting a server does not bypass your policy": integration does not mean approval;
- 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:
| Transport | Best for | What to fill in |
|---|---|---|
| Stdio | Servers launched by a local command | command + args (optional cwd / env) |
| Streamable HTTP | Remote servers | http(s):// URL |
| SSE | Legacy remote servers | http(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 surface | Best for whom | Characteristics |
|---|---|---|
| Control UI (Settings → MCP) | Those who don't want to touch the terminal | Can 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 scripting | Write-type commands require exclusive state; stop the Gateway first (see pitfall 1) |
Configuration file (mcp.servers) | Those who need version control and bulk initialization | Most 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.
openclaw mcp status --verboseYou 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.
openclaw gateway stop
openclaw mcp add memory \
--command npx \
--arg -y \
--arg @modelcontextprotocol/server-memory
openclaw gateway restartYou 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 listshowsmemory
Method B: Add directly at runtime via Control UI
- Open the Control UI and go to Settings → MCP (typing
/settings/mcpdirectly in the browser address bar, or the alias/mcp, also works). - Under Configured servers, select Add server.
- Give it a unique name and choose a transport: Streamable HTTP / SSE / Stdio.
- For HTTP-family transports, fill in the server's
http://orhttps://URL; for stdio, fill in the launch command and arguments. - Select Add server—the definition is written into
mcp.serversvia 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):
{
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:
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:
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 restartYou 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):
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:
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 restartWhy 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 --verbosecan list the servers you saved along with their transport typesopenclaw mcp doctor <name> --probeconnected 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:
openclaw mcp doctor <name> --probe- Connected but fewer tools than expected → check whether
toolFilter.include/toolFilter.excludeare filtering too aggressively - Servers with
enabled: falsekeep 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 reloadonly 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:
commandcan'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
cwddirectory doesn't exist - Arguments placed in the wrong position: arguments belong to
args, don't concatenate them intocommand; an explicittransport: "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 requiredoauthmetadata 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.
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:
openclaw mcp add memory \
--command npx \
--arg -y \
--arg @modelcontextprotocol/server-memory \
--approval approveThree 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 field | Recommended value | Description |
|---|---|---|
mcp.servers.<name>.transport | streamable-http / sse / stdio | Use the HTTP family for remote servers and stdio for local commands |
command + args vs url | Pick one of the two | Fill in the command and arguments for stdio, the URL for HTTP; filling in both will be rejected by validation |
toolFilter.include / exclude | Keep only the tools you need (* wildcards supported) | Filtering happens before tools enter the catalog |
enabled | true / false | false keep the definition but don't connect |
connectionTimeoutMs / requestTimeoutMs | 5000 / 20000 | Per-server connection / request timeout (milliseconds) |
auth | "oauth" | OAuth for HTTP servers, pair with openclaw mcp login to use |
codex.defaultToolsApprovalMode | approve / prompt / auto | Codex 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
- Browser Control: Let Claw Browse and Operate the Web for You—built-in web capability, complementing MCP plug-ins
- Scheduled Tasks Automations: cron, reminders, and Webhook triggers—MCP tools + scheduled triggers = unattended pipelines
- Getting Started with Skills: Installation, Usage, and Configuration—another way to extend; how to choose between skills and MCP tools