OpenClaw MCP: Add a Server, Then Prove It Answers

OpenClaw connects to MCP servers as a client: each server exposes tools, and OpenClaw hands those tools to your agents. You add one from Settings, from the chat composer, or from the command line. Connecting a server does not bypass your tool policy, and saving a definition proves nothing about reachability. Only a probe does.

Commands and documentation below were checked on September 22, 2026.

First, decide which direction you mean

Two different jobs share this name. Connecting a third-party server to OpenClaw is the one almost everyone wants: the agent borrows tools from another program. The reverse, exposing your OpenClaw channel conversations to another MCP client such as Claude.ai, is a separate command, openclaw mcp serve, with its own flags for a URL, a token and a password file in the MCP CLI reference.

The connect guide flags the difference in its opening note, so check which side a listing or a tutorial describes before following it. Everything below is the first direction.

Step 1: Add the server, and know where it runs

Stdio and HTTP are different deployments, not two syntaxes for the same thing. A stdio server is a command OpenClaw launches, so the process runs on the Gateway host and inherits its environment. An HTTP server is a URL, so it runs wherever its owner put it.

A local stdio server:

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

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_*'

The connect guide asks you to keep credentials out of config literals and to store sensitive headers and environment values through the supported secret mechanisms. The exact server name __proto__ is reserved.

Adding from Settings writes the same entry through the Gateway, from a page inside the Control UI, the admin surface whose token and reach are worth settling first with OpenClaw's built-in board or a third-party dashboard. There is also a third placement: node-hosted servers are configured on the node machine rather than the Gateway, and the node starts them, which keeps a tool's execution next to the files it touches. That path does not support OAuth servers. Which machine ends up holding the credential is the question behind what stays on your machine when you self-host an agent.

Step 2: Probe it, because saved is not connected

openclaw mcp doctor docs --probe

Doctor validates the saved definition first, then opens a live connection and reports the tools the server advertises. Expect the server name, its transport, and the tool names your filter kept. An error at that second stage means the saved definition passed validation and the live connection did not.

Two failures have specific causes. A server that shows up in Settings but exposes no tools is usually filtered rather than broken, so check toolFilter.include and toolFilter.exclude. A stdio server that never starts usually has a command that does not resolve in the Gateway process environment, or a cwd that does not exist; its stderr diagnostics are logged behind a bundle-mcp:<name>: prefix.

OAuth adds one more trap. After openclaw mcp login <name>, "Authentication saved" means the credentials were stored on the Gateway selected when sign-in started. The docs are explicit that this alone does not establish that the server answers or that its tools work. Probe again.

“

The tool filter decides what OpenClaw discovers; tool policy decides what the agent may actually call.

”

Step 3: Cut the tool list at discovery

toolFilter decides which of the server's tools become OpenClaw tools at all. Entries are exact tool names or simple * globs:

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

You can also set it after the fact with openclaw mcp tools docs --include 'search,read_*', and enabled: false keeps a definition without connecting it. The reason to filter is context: a server advertising forty tools spends tokens on every turn and gives the model forty ways to pick wrong.

What the filter is not is a permission boundary. It decides what OpenClaw discovers, not what the agent may call.

Step 4: Let tool policy decide what may run

Configured MCP servers arrive as plugin-owned tools under the bundle-mcp plugin id, so the ordinary tool policy layers apply. tools.profile sets a base allowlist, then tools.allow and tools.deny are evaluated on top, and deny wins. The coding and messaging profiles implicitly allow bundle-mcp, while local onboarding sets tools.profile: "full" when no profile is configured, which filters nothing.

If sandbox mode is "all" or "non-main", tools.sandbox.tools is an additional gate: MCP tools stay invisible to sandboxed sessions unless the allowlist includes bundle-mcp, group:plugins, or a specific server glob. Where those tools execute is the same boundary question as in Hermes versus OpenClaw.

One detail costs an afternoon when missed. Server globs use the provider-safe prefix, not the raw mcp.servers key. Characters outside [A-Za-z0-9_-] become -, a name that does not start with a letter gets an mcp- prefix, and long or duplicate prefixes may be truncated or suffixed. So mcp.servers["Outlook Graph"] is matched by outlook-graph__*, and a deny written against the raw config name does not match it.

Step 5: Choose the approval mode instead of inheriting it

For Codex runs, MCP tool approvals follow the session permission posture, and the default full-permission posture does not prompt. Stricter postures check tools that carry no safety annotation: workspace can review automatically, while guarded and read-only can prompt the operator. Override it per server:

openclaw mcp configure docs --approval prompt

An explicit mode takes precedence over the posture-derived default, and an explicit prompt keeps asking even when a durable grant was saved by Allow Always. Set it on the servers whose tools write something you would have to undo; deciding which writes deserve a gate is the same exercise as connecting an agent to your apps.

Step 6: Reload the runtime that actually serves your agent

openclaw mcp reload refreshes the runtimes owned by the current CLI process. A Gateway or an agent running elsewhere needs its own reload, config publish or restart. With Gateway hot reload enabled, changed and removed servers retire immediately and the next turn's discovery uses the new definition, while unchanged servers keep their connections and cached tools, including for runs already in progress.

This is the step skipped just before someone concludes the filter did not work.

The four checks that tell you it works

On the docs server above, in this order:

openclaw mcp status --verbose    # what is saved, without starting any server
openclaw mcp doctor docs --probe # live connection, plus the tools it advertises
openclaw mcp show docs           # the saved definition, filter included
openclaw mcp reload              # then ask the agent for one search call

Read the failures by which check breaks. Status showing the server while the probe fails is reachability or authorization. A probe listing tools the agent still cannot call is tool policy or the sandbox gate, not the filter. A write tool running without asking is the approval mode.

Adding the second server is a copy of these four checks, not a copy of the config block: the prefix rule and the sandbox gate are per server, and that is where the second one breaks.