OpenClaw MCP Guide: Connect Tools Using MCP Servers

OpenClaw becomes much more useful when it can reach the systems where your work already lives: databases, documentation, project trackers, design files, and internal services. The Model Context Protocol provides a standard way to make those connections without building a one-off integration for every model and tool.

OpenClaw MCP support lets OpenClaw borrow tools, resources, and prompts from compatible MCP servers. It can also work in the opposite direction, exposing routed OpenClaw conversations to external MCP clients. The important part is choosing the right direction, transport, and access policy before you connect anything powerful.

This guide covers the current first-party workflow: adding an MCP server from the Control UI or CLI, verifying the live connection, limiting exposed tools, handling OAuth safely, and understanding when to use openclaw mcp serve.

If your Gateway is not running yet, begin with the OpenClaw getting started guide before adding external capabilities.

What MCP Means in OpenClaw

The Model Context Protocol is an open standard for connecting AI applications to external systems. An MCP server can offer three broad capability types:

• Tools perform actions or calculations, such as searching a knowledge base or creating an issue.
• Resources expose readable data, such as files, records, or documentation.
• Prompts provide reusable workflows or structured instructions.

In the most common OpenClaw setup, OpenClaw is the MCP client. It connects to a third-party server and projects eligible capabilities into an agent's tool catalog. Current OpenClaw-managed definitions live under mcp.servers in Gateway configuration.

The reverse is also possible: OpenClaw can act as an MCP server. The openclaw mcp serve command starts a stdio bridge so another compatible client can work with routed OpenClaw channel conversations. These are different jobs, even though both use MCP.

Choose the Right MCP Direction

Use this rule before touching configuration:

OpenClaw as an MCP client

Choose this direction when an OpenClaw agent needs tools from somewhere else. Examples include searching a company documentation server, querying a read-only database gateway, or calling an approved workflow service.

You manage these connections with Settings → MCP or commands such as openclaw mcp add, status, doctor, probe, login, and reload.

OpenClaw as an MCP server

Choose openclaw mcp serve when Codex, Claude Code, or another MCP client needs access to existing OpenClaw-backed conversations. The bridge can expose conversation discovery, recent transcript history, live events, replies through stored routes, and approval requests observed while it is connected.

Do not use mcp serve merely to give an OpenClaw agent a database tool. That is the client-side registry job.

Choose an MCP Transport

OpenClaw supports three practical transport choices for outbound connections:

• Streamable HTTP: The preferred choice for a modern remote MCP endpoint. It works over HTTP or HTTPS and fits centrally hosted services.
• SSE: A remote HTTP transport retained for servers that expose Server-Sent Events rather than Streamable HTTP.
• Stdio: OpenClaw starts a local process and communicates over its standard input and output. This is useful for a trusted server installed on the Gateway host.

Use HTTPS for remote production services. Use stdio only when you trust the executable, its package source, its working directory, and what it can access as the Gateway's operating-system user. An MCP server is executable software, not a harmless prompt bundle.

Add an MCP Server from the Control UI

The Control UI is the easiest path for a first connection:

1. Open Settings → MCP.
2. Under Configured servers, select Add server.
3. Enter a unique name.
4. Select Streamable HTTP, SSE, or Stdio.
5. Enter the remote URL or the local command and arguments.
6. Save the definition.
7. Prove the connection with a live probe.

You can also open the composer menu and choose + → Connectors → Add MCP server…. Session-only enablement and global enablement both save a server definition; the session layer determines whether that conversation may use it.

Saving the row is not proof that the server works. Run:

openclaw mcp doctor docs --probe

Replace docs with your server name. According to the official connection guide, the probe validates the saved definition and opens a live connection to report advertised capabilities.

Add an MCP Server from the CLI

For a remote Streamable HTTP server, a minimal command looks like this:

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

The include filter matters. It prevents every advertised tool from automatically entering the eligible catalog. Follow the add with an explicit check:

openclaw mcp doctor docs --probe

For a local stdio server:

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

Then probe it the same way. Before using stdio in production, pin and review the server package rather than allowing an unattended process to download an arbitrary latest version at startup.

Useful diagnostic commands have distinct purposes:

• openclaw mcp status --verbose summarizes saved configuration without connecting.
• openclaw mcp doctor <name> catches local definition problems.
• openclaw mcp doctor <name> --probe adds a live connection test.
• openclaw mcp probe <name> connects and lists capabilities.
• openclaw mcp reload refreshes runtimes owned by the current CLI process.

That distinction makes troubleshooting faster: first confirm what is saved, then confirm that it is valid, then prove that the endpoint responds.

Configure an MCP Server Directly

For advanced options, the same remote connection can be represented under mcp.servers:

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

A URL is required for HTTP transports. A non-empty command is required for stdio. Setting enabled: false preserves the definition without connecting it.

Direct configuration is powerful, but configuration mistakes can prevent clean startup or expose more tools than intended. Review the OpenClaw configuration guide before making larger changes, and validate the effective setup instead of assuming syntactically valid JSON is operationally correct.

Verify Tools and Limit Access

MCP does not bypass OpenClaw security policy. The OpenClaw MCP documentation states that exposed tools pass through the same tool profiles and policy controls as built-in tools.

Apply least privilege in layers:

1. Limit the server itself. Configure only the upstream accounts and scopes the server needs.
2. Filter discovery. Use toolFilter.include and toolFilter.exclude to keep unrelated or destructive capabilities out.
3. Apply OpenClaw tool policy. Deny tools that should not exist for the agent or session.
4. Use sandboxing where appropriate. Stdio process placement and filesystem access are separate from tool-name filtering; the OpenClaw sandboxing guide explains that boundary.
5. Test with a harmless call. Read a known document or list a small collection before allowing writes.

A tool filter matches names, not every possible side effect. A tool called update_record may still be destructive even if it does not contain the word “delete.” Read each tool description and test it against a non-production target.

Configure OAuth Safely

Some HTTP MCP servers use OAuth instead of a static bearer token. Configure the server for OAuth, then start the login flow:

openclaw mcp login docs

Follow the printed authorization URL. OpenClaw normally captures a loopback callback and saves the resulting credentials. For a remote or headless operator, use the documented manual code path when the browser cannot reach the callback listener.

Never paste tokens directly into article snippets, shared shell history, source control, or public configuration. Sensitive headers and environment values should use supported secret mechanisms. The OpenClaw secrets management guide covers protected storage and host-bound egress in detail.

After login, run the probe again. If authorization is incomplete, doctor should report that state rather than leaving you to guess whether the failure is network, configuration, or identity related.

Use OpenClaw as an MCP Server

The reverse path starts a local stdio MCP server:

openclaw mcp serve

An external MCP client owns that process. The bridge connects to the OpenClaw Gateway and exposes conversations that already contain usable route metadata. It does not invent routes or replace channel admission controls.

For a remote Gateway, prefer file-based credential options supported by the CLI rather than placing credentials directly in arguments. The external client can then list routed conversations, read history, wait for live events, and send text through an existing route.

Two operational details matter:

• The live event queue begins when the bridge connects and disappears when it disconnects.
• Durable transcript backlog comes from history reads, not from the live queue.

If a client misses older events, read durable messages first, then resume from the available live cursor. The full behavior and bridge tool list are documented in the OpenClaw MCP CLI reference.

Troubleshoot Common OpenClaw MCP Problems

The server is saved but no tools appear

Run openclaw mcp doctor <name> --probe. If the connection succeeds, inspect include and exclude filters. Also check the active session's tool-access settings and tool profile.

A stdio server will not start

Confirm that the command resolves in the Gateway process environment, the working directory exists, and arguments are in the correct field. Inspect server stderr diagnostics, but never log secrets to make debugging easier.

An HTTP server returns unauthorized

Confirm that the server expects OAuth, complete openclaw mcp login <name>, and probe again. If it expects static authentication, move the value into an approved secret mechanism instead of a literal config field.

Configuration changed but the agent sees the old catalog

Reload the runtime that owns the session. openclaw mcp reload affects runtimes owned by that CLI process; a Gateway running elsewhere may need its own config publish, reload, or carefully managed restart.

mcp serve returns no conversations

The underlying sessions probably lack stored route metadata. Confirm that OpenClaw already knows the channel, destination, and any relevant account or thread identifier. MCP cannot reconstruct a route that the Gateway never recorded.

Production Safety Checklist

Before letting an MCP connection touch real data:

• Use a maintained server from a source you have reviewed.
• Prefer HTTPS for remote endpoints.
• Give the upstream account the smallest possible scope.
• Store credentials through protected secret mechanisms.
• Filter the exposed tool catalog.
• Keep destructive tools out of unattended sessions.
• Probe the server after every configuration or authorization change.
• Test reads before writes and writes before deletes.
• Review logs for connection loops, timeouts, and unexpected tool calls.
• Run the broader checks in the OpenClaw security setup guide.

MCP standardizes the connection, not the trust decision. You still decide which server runs, what it can reach, which agent can call it, and whether a human must approve consequential actions.

Frequently Asked Questions

Does OpenClaw support MCP?

Yes. OpenClaw can connect to third-party MCP servers as a client, and openclaw mcp serve can expose routed OpenClaw conversations to external MCP clients.

Where are OpenClaw MCP servers configured?

Current OpenClaw-managed outbound definitions live under mcp.servers. You can manage them from Settings → MCP or with the openclaw mcp CLI.

Which MCP transport should I use?

Use Streamable HTTP for a modern remote endpoint, SSE for a server that specifically requires it, and stdio for a trusted local process. Prefer HTTPS for production remote connections.

How do I know an MCP server is really connected?

Run openclaw mcp doctor <name> --probe. A saved configuration only proves that a definition exists; the probe proves a live connection and reports advertised capabilities.

Can an MCP server bypass OpenClaw tool policy?

No. MCP capabilities are still subject to OpenClaw tool profiles, session controls, and tool policy. You should also narrow the server's own account permissions and apply per-server tool filters.

Final Takeaway

A reliable OpenClaw MCP setup follows a simple sequence: choose the correct direction, select the transport, save the smallest useful definition, prove it with a live probe, and restrict the resulting tools before real use. That turns MCP from a pile of exciting integrations into an auditable extension of your OpenClaw security model.