OpenClaw MCP Client: Connect Any Tool to Your Agents Fast

Agents that can only generate text have a ceiling. The MCP client removes it. Within 10 minutes of a correct configuration, your OpenClaw agent can search the web, read local files, query APIs, and execute code — all decided by the model, all routed through a single standardized layer.

What Is the MCP Client?

The MCP client is the component inside OpenClaw that manages your connections to external tool servers. It's not a separate application — it's built into the OpenClaw runtime. When your agent decides to call a tool, the MCP client intercepts that call, finds the right server, sends the request, and returns the result.

You never interact with the MCP client directly during conversations. Your job is to configure it correctly once. After that, it runs invisibly between the model and the external world.

Here's what we've seen consistently: teams that struggle with MCP almost always have a config issue, not a conceptual one. The protocol itself is well-designed. The errors are almost always path problems, missing environment variables, or wrong transport types.

Configuring the Client

The MCP client is configured through the mcp: block in your config.yaml. The structure is straightforward: a top-level enabled flag and a list of server entries.

# Minimal MCP client configuration
mcp:
  enabled: true
  timeout_ms: 30000       # global default, override per server
  servers: []             # server entries go here

Two global settings matter most. timeout_ms controls how long the client waits for a tool call response before declaring failure. Thirty seconds works for most tools. If you're connecting to a slow database or an AI-powered tool, increase this per server. enabled: false disables the entire MCP layer without removing your config — useful for debugging when you want to isolate whether an issue is MCP-related.

Connecting MCP Servers

Each server in your servers: list follows the same structure regardless of transport type. Here's a complete example showing both a local stdio server and a remote SSE server:

mcp:
  enabled: true
  servers:
    # Local subprocess server (stdio transport)
    - name: filesystem
      transport: stdio
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/home/user/workspace"
      timeout_ms: 15000
      auto_approve: false
      restart_on_crash: true

    # Remote HTTP server (sse transport)
    - name: company-api
      transport: sse
      url: "https://api.internal.com/mcp/sse"
      headers:
        Authorization: "Bearer ${INTERNAL_API_TOKEN}"
        X-Team-ID: "${TEAM_ID}"
      timeout_ms: 45000
      auto_approve: false

How Tool Discovery Works

When OpenClaw starts, the MCP client connects to each configured server and requests its tool manifest. This manifest lists every tool the server exposes: its name, description, and parameter schema. The client caches this list and makes it available to the language model as callable functions.

The model never calls tools directly. It generates a structured tool call, which OpenClaw intercepts, validates against the tool schema, routes to the right server, executes, and returns results as additional context. The model then continues its response with that context available.

Tool discovery happens automatically at startup. If a server is unavailable at startup, its tools are simply absent from the model's available list. The agent continues without them — no crash, no error for the user. Re-connect is attempted on the next restart.

Authentication Options

Different MCP servers use different authentication mechanisms. The OpenClaw MCP client supports all common patterns:

• Environment variables — reference with ${VAR_NAME} in any config value. The client substitutes the actual value at startup. Never hardcode credentials
• Header injection — for SSE servers, add any required headers to the headers: map. Supports Authorization, API key headers, and custom headers
• OAuth — for servers requiring OAuth flows, set auth_type: oauth and provide client credentials. OpenClaw handles token refresh automatically
• mTLS — for enterprise setups requiring mutual TLS, provide cert_file and key_file paths in the server config

Testing Your Connection

After editing your config, restart OpenClaw and run these commands to verify everything is working before involving agents:

# List all connected MCP servers and their tools
openclaw mcp list

# Expected output:
# ✓ filesystem (stdio) — 6 tools: read_file, write_file, list_directory, ...
# ✓ brave-search (stdio) — 1 tool: brave_web_search
# ✗ company-api (sse) — CONNECTION FAILED: timeout after 30s

# Test a specific tool call directly
openclaw mcp call brave-search brave_web_search '{"query": "OpenClaw MCP"}'

The direct tool call test bypasses the language model entirely. If the tool call succeeds here but fails in an agent conversation, the issue is in how the model is selecting or parameterizing the tool — not in your MCP client config.

Common Mistakes

The mistake most people make is not testing the MCP server command independently before adding it to config. Run the exact command OpenClaw would run — including all args — directly in your terminal. If it fails there, it'll fail inside OpenClaw for the same reason.

• npx not in PATH — if your MCP server uses npx, ensure npx is available in the environment OpenClaw runs in, not just your interactive shell. Use the absolute path to npx if needed
• Wrong working directory for stdio servers — stdio servers inherit OpenClaw's working directory, which may not be what the server expects. Use absolute paths in server args wherever paths appear
• Forgetting restart_on_crash — stdio servers can crash. Without restart_on_crash: true, a single crash silently removes that server's tools for the rest of the session
• SSE server not returning proper Content-Type — SSE endpoints must return Content-Type: text/event-stream. If your remote server returns JSON, it's not an SSE endpoint and you need a different approach

Frequently Asked Questions

What is the OpenClaw MCP client?

The MCP client is the component inside OpenClaw that manages connections to MCP servers. It handles server startup, tool discovery, call routing, and result processing — configured via the mcp: block in config.yaml. It runs invisibly between the model and external tools.

How do I connect a custom MCP server to OpenClaw?

Add a server entry under mcp.servers in config.yaml with the transport type, command or URL, and any environment variables. Restart OpenClaw and run openclaw mcp list to verify the server connected and its tools are visible.

Can the MCP client connect to remote servers?

Yes. Use the sse transport type and provide the remote server's URL. Add required Authorization headers in the headers: config block. The remote server must expose a valid MCP SSE endpoint returning Content-Type: text/event-stream.

How does OpenClaw discover tools from MCP servers?

At startup, the MCP client queries each configured server for its tool list. The model receives this as available functions automatically — no manual registration required. If a server is unavailable at startup, its tools simply don't appear in the model's tool list.

What happens when an MCP client call times out?

OpenClaw returns a timeout error to the model, which treats it as a tool failure. Set timeout_ms per server to control the threshold. Default is 30 seconds. Long-running tools like database queries or AI-powered APIs need a higher timeout to avoid false failures.

Can I restrict which tools an agent can access?

Yes. Use the allowed_tools list per MCP server entry to whitelist specific tools. Agents only see tools on their whitelist. This lets you share one MCP server config across agents with different permission levels without running separate server instances.

How do I test an MCP client connection?

Run openclaw mcp list to see all connected servers and available tools. Run openclaw mcp call <server> <tool> <args> to test a specific tool call directly. This bypasses the language model and tests the MCP client connection in isolation.