Connect MCP Servers to OpenClaw

The Model Context Protocol (MCP) lets an agent borrow tools from another program. An MCP server publishes tools, resources, and prompts, and OpenClaw links to it so those tools become available to your agents. Server definitions are stored under mcp.servers in config, and the tools they expose pass through the same tool-profile and tool-policy controls as any other tool. Connecting a server does not bypass your policy.

Note

This guide covers linking third-party MCP servers to OpenClaw. For the opposite direction, exposing OpenClaw channel conversations to another MCP client, see openclaw mcp serve.

Add a server from Settings

Launch the Control UI and navigate to Settings → MCP.
In the Configured servers area, click Add server.
Provide a distinct name and choose a transport: Streamable HTTP, SSE, or Stdio.
For the HTTP transports, supply the server's http:// or https:// URL. For stdio, give the command followed by its arguments.
Click Add server.

This action writes the new mcp.servers entry through the Gateway. For advanced settings, such as headers, environment values, OAuth metadata, TLS settings, timeouts, parallel-tool-call hints, and tool filters, use the scoped config editor located lower on the page. Each server row also supports enabling, disabling, or removing a definition.

After saving the server, confirm it actually responds:

openclaw mcp doctor <name> --probe

A saved definition does not guarantee reachability; the probe is what verifies it. Be aware that already-running Gateway or agent processes might need a restart or runtime reload before they detect the new definition.

Add a server from the composer

In a Control UI chat, pick + → Connectors → Add MCP server…. The dialog presents the same server fields as Settings and demands administrator access.

Select This session for session-only enablement or Everywhere for global enablement. Both scopes save a global server definition; session policy acts as the per-session layer. For full scope and tool-access behavior, see the Composer capability menu.

From an active conversation, open + → Connectors → Tool access to review or block individual tools for that session. The view follows the session's actual runtime owner: built-in OpenClaw sessions read the in-process MCP catalog, while native agent harnesses can contribute their thread-owned catalog. Either runtime enforces session server and tool denials before the next turn starts.

Add a server from the CLI

A local stdio server:

openclaw mcp add local-tools \
  --command node \
  --arg ./dist/mcp-server.js \
  --cwd /srv/openclaw-tools
openclaw mcp doctor local-tools --probe

A remote Streamable HTTP server, exposing only some of its tools:

openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --include 'search,read_*'
openclaw mcp doctor docs --probe

Useful companions: openclaw mcp status --verbose for a config-only summary, openclaw mcp probe <name> for live capabilities, and openclaw mcp login <name> when an HTTP server uses OAuth. The MCP CLI reference documents every command, flag, and output shape, plus the separate mcp serve bridge.

Configure a server directly

The same docs server, written straight into config:

{
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        enabled: true,
        connectionTimeoutMs: 5000,
        requestTimeoutMs: 20000,
        toolFilter: {
          include: ["search", "read_*"],
        },
      },
    },
  },
}

An enabled server needs either a command (stdio) or a URL (SSE or Streamable HTTP). The exact server name __proto__ is reserved; pick a different name. Setting enabled: false keeps the definition around without connecting it. Keep credentials out of config literals, and store sensitive headers and environment values through the supported secret mechanisms.

Troubleshooting

The server appears in Settings but exposes no tools

Run openclaw mcp doctor <name> --probe. Doctor validates the saved definition first, then opens a live connection and reports the tools and other capabilities the server advertises. If it connects but expected tools are missing, check toolFilter.include and toolFilter.exclude.

A stdio server does not start

Confirm the command resolves in the Gateway process environment and that cwd exists. Arguments belong in args, and an explicit transport: "stdio" requires a non-empty command.

An HTTP server needs authorization

Set auth: "oauth" plus any required oauth metadata, then:

openclaw mcp login <name>

Follow the printed authorization URL. OpenClaw normally captures the loopback redirect and saves the credentials automatically; use the printed --code command when the browser cannot reach the callback listener.

Changes do not reach an active agent

openclaw mcp reload refreshes runtimes owned by the current CLI process. A Gateway or agent running elsewhere needs its own reload, config publish, or restart.