OpenClaw MCP: The Definitive Guide to Model Context Protocol

Agents that can only generate text have a ceiling. The moment your OpenClaw agent can call tools — search the web, read files, run code, query databases — the ceiling disappears. That's exactly what MCP delivers, and as of early 2025, it's the architecture that separates serious deployments from demos.

What Is MCP?

Model Context Protocol is OpenClaw's standardized interface for connecting external capabilities to your agent. Think of it as a universal adapter: any tool that implements the MCP spec can plug into OpenClaw without custom integration code.

Before MCP existed, connecting a tool meant writing provider-specific glue code for every integration. Now, one config block handles everything from web search to local file access to custom API calls. The agent's language model sees available tools as a list of callable functions. It decides which to call, calls it through OpenClaw's MCP layer, and receives structured results back.

Here's what that means practically: your agent can search the web mid-conversation, read a document you point it at, run a calculation, and write back to a system — all within a single turn. No custom code on your end beyond the config.

How MCP Works in OpenClaw

OpenClaw's MCP layer sits between the language model and the external world. When the model decides to call a tool, OpenClaw intercepts that call, routes it to the right MCP server, executes the tool, and returns the result to the model as context. The model never directly calls external systems.

This architecture matters for three reasons. Security: you control exactly what tools are available and whether they require approval. Reliability: if an MCP server goes down, the agent continues running — it just can't use that server's tools. Observability: every tool call is logged with its input and output, making debugging straightforward.

Setting Up MCP

MCP configuration lives in your config.yaml. Add an mcp: block with a servers: list. Each server entry needs a name, transport type, and either a command (for stdio) or URL (for sse).

# ~/.openclaw/config.yaml — MCP configuration
mcp:
  enabled: true
  servers:
    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
      auto_approve: false

    - name: brave-search
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-brave-search"]
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"
      auto_approve: true

    - name: remote-api
      transport: sse
      url: "https://your-mcp-server.com/sse"
      headers:
        Authorization: "Bearer ${API_TOKEN}"
      auto_approve: false

After editing config, restart OpenClaw with openclaw restart. Check the logs immediately — MCP server startup errors appear within the first few seconds and tell you exactly what's wrong.

Transport Types: Stdio vs SSE

Stdio runs the MCP server as a local subprocess. OpenClaw spawns the process, communicates over stdin/stdout, and manages its lifecycle. Use this for local tools: filesystem access, local code execution, tools that need to run on the same machine as OpenClaw.

SSE (Server-Sent Events) connects to a remote MCP server over HTTP. The server runs independently — on another machine, in the cloud, or as a managed service. Use this for shared team tools, hosted services like Brave Search or Tavily, or any tool you want to update independently of your OpenClaw instance.

Tool Approval Settings

Every MCP tool call can require explicit human approval before executing. This is critical for any tool that has side effects: writing files, sending messages, making API calls that cost money or mutate state.

Three approval levels available per server:

• auto_approve: false (default) — every tool call pauses and asks for confirmation. Use for production agents with write access
• auto_approve: true — all tools on this server execute without confirmation. Use only for read-only tools you fully trust
• approved_tools: [list] — whitelist specific tools for auto-approval while requiring confirmation for others

mcp:
  servers:
    - name: web-search
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-brave-search"]
      env:
        BRAVE_API_KEY: "${BRAVE_API_KEY}"
      auto_approve: true          # search is read-only, safe to auto-approve
      approved_tools: []          # empty = all tools auto-approved when true

    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      auto_approve: false         # file writes require confirmation
      approved_tools:             # but read operations are fine
        - read_file
        - list_directory

Running Multiple MCP Servers

Real-world agents almost always need multiple tool categories. You can run as many MCP servers as you need — OpenClaw handles the routing automatically based on tool names.

Here's what we've seen consistently: teams start with one or two MCP servers and end up running five or six within a month. Web search, filesystem access, database queries, code execution, and a custom internal API are a typical production stack. Each gets its own entry in the servers list, its own approval settings, and its own environment variables.

Tool name conflicts — where two servers expose a tool with the same name — are resolved by the order of servers in your config. The first matching tool wins. Name your tools explicitly in any custom MCP servers you build to avoid this.

Common Mistakes

The mistake most people make is treating MCP as a set-and-forget configuration. It's not. MCP servers can drift — npm packages update, API keys expire, remote servers go down. Build monitoring into your deployment from day one.

• Hardcoded credentials in config.yaml — always use environment variable references like ${VARIABLE_NAME}. Config files get committed to git; credentials don't belong there
• Auto-approving write-capable tools — a tool that can write files or send messages should never be auto-approved in an unattended agent. The blast radius of an unexpected tool call is too high
• Not testing MCP server startup independently — before adding a server to OpenClaw, run its command directly in your terminal. Catch path and dependency issues before they show up in agent sessions
• Ignoring tool descriptions — the language model decides which tool to call based on the tool's description. Vague descriptions lead to wrong tool selection. Custom MCP servers need clear, specific tool descriptions

Sound familiar? These are the patterns that appear in almost every MCP support thread. The fix is always the same: treat MCP server configuration with the same rigor you'd apply to production API integrations.

Frequently Asked Questions

What is MCP in OpenClaw?

MCP stands for Model Context Protocol — OpenClaw's standardized interface for connecting external tools, APIs, and data sources to your agent. It lets your model call functions, retrieve live data, and take actions beyond its training data, all through a single config-driven layer.

How do I enable MCP in OpenClaw?

Add an mcp: block to your config.yaml with at least one server entry. Each server needs a name, transport type (stdio or sse), and command or URL. Restart OpenClaw after changes and check the logs for a successful startup message.

Can I run multiple MCP servers at once?

Yes. OpenClaw supports multiple simultaneous MCP servers. List each under the mcp.servers array in config.yaml. The agent selects the appropriate tool from whichever server exposes it based on tool name matching and server order.

What MCP transport types does OpenClaw support?

OpenClaw supports stdio (local subprocess) and sse (HTTP Server-Sent Events for remote servers). Use stdio for local tools like filesystem access, and sse for remote MCP servers or hosted services.

Is MCP secure in OpenClaw?

MCP tool calls go through OpenClaw's approval layer by default. You can require explicit approval for each tool call, whitelist specific tools for auto-execution, or restrict which MCP servers agents can access per agent config. Never auto-approve write-capable tools in production.

What happens if an MCP server crashes?

OpenClaw logs the error and marks the MCP server as unavailable. The agent continues running but cannot use tools from that server. Enable auto_restart: true in the MCP server config to automatically restart crashed servers without requiring a full OpenClaw restart.

How do I debug MCP tool call failures?

Run openclaw logs --mcp to see all tool call attempts and responses. Enable debug: true on the specific MCP server in config for verbose output including request payloads — this reveals most tool call issues immediately without needing external debugging tools.