OpenClaw MCP: Model Context Protocol servers, tools, and integrations

MCP — Model Context Protocol — is how OpenClaw connects to external tool servers. Instead of bundling every integration, OpenClaw discovers tools at runtime from any MCP server you configure: a Chrome DevTools session, a SQLite database, a Notion workspace, your own internal API.

If you've installed a skill, you've used MCP indirectly. This page is for when you want to add your own MCP servers, scope them per-agent, or debug why their tools aren't showing up.

When to use MCP vs a skill

In practice most users start with skills, then graduate to MCP when they need something specific.

Adding an MCP server

Edit ~/.openclaw/openclaw.json and add an mcp.servers entry. Two forms:

Stdio (subprocess) servers

{
  "mcp": {
    "servers": {
      "sqlite": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
      }
    }
  }
}

OpenClaw launches the command on demand and speaks MCP over its stdin/stdout. Best for local-only tools.

HTTP / SSE servers

{
  "mcp": {
    "servers": {
      "internal-api": {
        "url": "https://mcp.internal.example.com/sse",
        "headers": {
          "Authorization": "Bearer ${INTERNAL_API_TOKEN}"
        }
      }
    }
  }
}

${INTERNAL_API_TOKEN} resolves through OpenClaw's SecretRef system at runtime — the raw template never reaches the wire.

Restart the Gateway after editing config:

openclaw gateway restart

Then verify:

openclaw mcp list                # Shows configured MCP servers
openclaw tools list --detailed   # Shows every tool the agent can now call

Per-agent scoping

You typically don't want every agent to see every MCP server. A coding agent might need Chrome DevTools; a briefing agent shouldn't.

The current options (v2026.5.19):

{
  "tools": {
    "deny": ["browser_*", "sqlite_*"]
  }
}

tools.deny works against MCP-surfaced tools, so you can block whole servers by tool-name prefix. Per-agent MCP server allowlists (agents.[name].mcp) are tracked as an open feature — for now use deny lists per-agent.

OAuth-backed MCP servers

Some MCP servers (Notion, Linear, GitHub-as-MCP) require OAuth rather than a static bearer token. OpenClaw's bundle-mcp supports static bearer headers today. OAuth 2.1 client_credentials for remote MCP servers is tracked as an open feature request — for now, mint a long-lived token outside OpenClaw and use the static header form above.

Common errors

For any other MCP failure, openclaw logs --filter mcp --tail 100 shows the full handshake — server launch, capability negotiation, tool list. If you see "tools/list error" the server is responding but malformed; if you see "spawn ENOENT" the command can't be found in PATH.

Browsing MCP servers

There's no single canonical registry yet. The MCP community maintains lists at github.com/modelcontextprotocol/servers — official reference servers (SQLite, filesystem, Git, GitHub, GitLab, Postgres, Puppeteer, etc.) and a community-maintained index.

For OpenClaw-specific bundled MCP integrations, run:

openclaw mcp list                # Currently only shows mcp.servers entries

Note: openclaw mcp list only shows servers defined in your config under mcp.servers — it doesn't surface mcporter or skill-provided MCP servers. This is tracked as a UX issue.

→ MCP specification · Reference servers · CLI Cheatsheet · Skills & Tools