OpenClaw MCP Guide for Private AI Agent Tool Access

OpenClaw can use the Model Context Protocol, or MCP, to connect private AI agents to external tools, data sources, and services without hard-coding every integration into one agent. The safe setup is not simply "add an MCP server." It is to choose the correct OpenClaw MCP mode, expose only the tools the workflow needs, prove the connection before an agent uses it, and keep sensitive actions behind explicit approval gates.

This guide explains the practical architecture, setup sequence, security boundaries, and production checks for teams connecting MCP servers to OpenClaw.

What MCP adds to OpenClaw

MCP is a standard interface for giving AI applications access to capabilities. The protocol separates three useful building blocks:

Resources provide context or data.
Prompts provide reusable interaction templates.
Tools let a model request an action.

That separation matters because reading a document is not the same risk as sending an email, changing a record, or running code. A private AI agent should not receive one undifferentiated bucket called "access."

OpenClaw adds an operating layer around those capabilities. It can keep MCP server definitions in central configuration, project selected servers into eligible agent runtimes, filter individual tools, handle supported OAuth flows, and test connections before they enter normal work.

The result is useful when an agent needs controlled access to a file tree, documentation service, CRM, issue tracker, database, internal API, or another MCP-enabled system.

Choose the correct OpenClaw MCP direction

The first decision is direction. OpenClaw can act as an MCP server or manage outbound MCP servers as a client-side registry. These are different jobs.

OpenClaw as an MCP server

Use openclaw mcp serve when an external MCP client needs to work with OpenClaw-backed conversations. An approved client such as a coding harness can then list conversations, read messages, wait for events, send replies through known channel routes, and handle approval requests exposed by the bridge.

This pattern is appropriate when OpenClaw already owns the messaging and session routing, while another client needs a standard interface into those conversations.

OpenClaw as an MCP client registry

Use commands such as openclaw mcp add, set, status, doctor, probe, tools, login, and reload when OpenClaw-managed agent runs need third-party MCP servers.

This is the common direction for tool access. OpenClaw stores the server definition and later makes approved capabilities available to eligible runtimes.

The official OpenClaw MCP CLI reference documents both modes and is the primary source for current command behavior.

Start with inventory, not installation

Before adding a server, inspect what is already configured:

openclaw mcp status --verbose

This is a low-risk first step because it shows saved definitions, transport, authentication, timeouts, filters, and parallel-call hints without requiring a live connection to every target.

Record four things before making a change:

The business workflow that needs the server
The exact tools or resources required
Whether access is read-only, write-capable, or externally consequential
The runtime or agent that should receive the capability

If those answers are unclear, the server is not ready to add. A broad integration installed for possible future use usually becomes permanent ambient access. Ambient access has a habit of becoming relevant during the least convenient incident.

Add the narrowest useful server

For a local stdio server, define the executable, arguments, working directory when required, and an explicit tool filter.

A filesystem example might look like this:

openclaw mcp add project-files \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg /srv/approved-project \
  --include 'read_file,list_directory,search_files'

The important part is not the package name. It is the scope:

The server sees one approved project tree, not an entire home directory.
The filter exposes read and search operations, not every available tool.
The server name describes its purpose.

For an HTTP server, configure the exact endpoint, transport, and authentication mode. Keep credentials in an approved secret provider rather than embedding them in chat, source files, or copied command history.

OpenClaw's current MCP configuration also supports include and exclude filters for tool names. Use them. If an integration exposes search, read, update, delete, send, and admin operations, a research agent may need only search and read.

Treat tool filters as a security boundary

The MCP specification warns clients to treat tool annotations as untrusted unless they come from trusted servers. A friendly description is not proof that a tool is safe.

Review the actual tool inventory:

openclaw mcp tools project-files

Classify each tool before exposure:

Read-only: search, list, inspect, fetch
Local write: create or update files inside an approved workspace
External write: send, publish, submit, comment, or change a remote record
Destructive: delete, revoke, overwrite, reset, or remove
Privileged: billing, authentication, admin, DNS, deployment, or production configuration

Default access should stop at the lowest class that completes the workflow. A support-research agent does not need delete_ticket. A documentation agent does not need send_mail. A monitoring agent does not need deployment access because it noticed a 500 response.

Prove the server before an agent turn

A saved definition is not a working integration. OpenClaw provides separate checks so operators can validate configuration and live behavior.

Use a doctor or probe command after setup:

openclaw mcp doctor project-files --probe

or:

openclaw mcp probe project-files --json

The production acceptance check should confirm:

The command or endpoint resolves
Authentication succeeds
The expected transport is used
The server starts within its connection timeout
Only approved tools appear
A harmless read operation works
A prohibited write or admin capability is absent
The process or connection closes cleanly

Save the proof in a dated artifact. If the agent later behaves differently, the team needs a known-good baseline rather than a recollection that setup "seemed fine."

Handle OAuth deliberately

Remote MCP servers may use OAuth. OpenClaw can save supported server definitions, start the login flow, and store resulting local authorization state.

The security model still belongs to the operator. The current MCP authorization specification uses OAuth-based discovery and requires tokens to be bound to their intended resource. It also prohibits casual token passthrough between services.

Practical rules are straightforward:

Request the smallest scopes the workflow needs.
Keep authorization links private to the intended user.
Do not paste bearer tokens into chat or documentation.
Revoke unused connections.
Re-run the probe after a scope or credential change.
Keep separate service tokens separate, even if one MCP server calls another API.

OAuth proves who authorized access. It does not prove that every exposed tool should be available to every agent.

Add human approval gates for consequential tools

MCP makes capabilities portable. It does not remove the need for judgment.

A useful OpenClaw policy separates normal autonomous work from actions that require approval:

Allowed without approval:

Read approved resources
Search a bounded dataset
Save local evidence
Draft a proposed message or patch
Run a documented health check

Approval-gated:

Send external messages
Publish or deploy
Change production records
Modify tracking or authentication
Spend money or start a subscription
Delete or overwrite material data
Expand access beyond the approved scope

The agent should prepare the exact proposed action, target, expected effect, and rollback path before asking. "Can I use the tool?" is not a useful approval request. "Can I update these three records from state A to state B, with this validation and rollback?" is.

For a fuller permission model, pair this setup with the private AI agent security model guide.

Isolate servers by workflow and agent

One giant MCP server with every company tool may look efficient. It creates a large blast radius and a poor audit trail.

Prefer smaller capability bundles:

Documentation research server with search and read
CRM review server with read-only account and pipeline fields
Publishing server available only to the publishing agent
Incident server with logs and ticket creation, but no infrastructure mutation
Filesystem server rooted at one approved project

OpenClaw can then project the appropriate capability into the runtime that needs it. This supports least privilege and makes failures easier to understand.

Isolation also reduces prompt-injection risk. A browser research agent that encounters hostile page text should not simultaneously hold billing, email, deployment, and database tools.

The same isolation principle is applied step by step in the self-hosted browser research workflow.

Monitor configuration drift

MCP servers evolve. A package update may add tools, rename operations, change authentication, or alter schemas. An HTTP service may change its advertised capabilities. Treat that as configuration drift.

A sensible recurring check can:

Run openclaw mcp status --verbose.
Probe approved servers.
Compare the tool inventory with the saved baseline.
Flag new write, send, delete, or admin capabilities.
Confirm expected OAuth state and timeouts.
Stay silent when nothing meaningful changed.

Do not automatically approve a new tool because it appeared after an update. New capability is a review event.

If drift causes a production incident, use a documented self-hosted AI agent incident response runbook rather than improvising recovery from the same agent context.

Common OpenClaw MCP mistakes

The first mistake is confusing openclaw mcp serve with outbound MCP configuration. Decide whether OpenClaw is exposing conversations or consuming a third-party server.

The second is adding an entire home directory to a filesystem server. Scope the smallest useful path.

The third is exposing every advertised tool. Inventory and filter first.

The fourth is skipping the live probe. Saved configuration is not operational proof.

The fifth is treating OAuth as complete authorization design. Scopes, tool filters, runtime boundaries, and approval gates still matter.

The sixth is connecting production write tools to an agent whose job is research or monitoring.

The seventh is leaving stale servers enabled because removing access feels less urgent than adding it. Old integrations are patient.

Frequently asked questions

Does OpenClaw support MCP servers?

Yes. OpenClaw can manage outbound MCP server definitions for eligible agent runtimes, and it can also run openclaw mcp serve so an external MCP client can work with OpenClaw-backed conversations. The correct mode depends on which system is providing the capability.

What is the difference between `openclaw mcp serve` and `openclaw mcp add`?

openclaw mcp serve makes OpenClaw act as an MCP server. openclaw mcp add saves a third-party MCP server definition for OpenClaw-managed runtimes to consume later. One exposes OpenClaw; the other registers an external capability.

How do I test an OpenClaw MCP server?

Start with openclaw mcp status --verbose to inspect saved configuration without connecting. Then use openclaw mcp doctor <name> --probe or openclaw mcp probe <name> --json for a live connection and capability check.

Can OpenClaw restrict individual MCP tools?

Yes. Use include and exclude filters so the runtime receives only the approved tool names or patterns. Verify the resulting inventory with the tools and probe commands before normal agent use.

Is OAuth enough to secure an MCP integration?

No. OAuth handles authorization and token flow, but operators still need narrow scopes, tool filters, runtime isolation, approval gates, evidence logging, and a clean revocation path.

Production checklist

Before an MCP-backed OpenClaw workflow becomes active, verify:

The MCP direction is correct
The server has one documented business purpose
Filesystem and data scopes are narrow
Only required tools are exposed
Credentials use an approved secret or OAuth flow
doctor --probe or probe succeeds
Read behavior is proven with a harmless test
Consequential actions require approval
Proof is stored in a dated artifact
Tool inventory drift has an owner and review cadence
The server can be disabled or revoked cleanly

MCP is valuable because it gives OpenClaw a standard way to reach more systems. The durable advantage comes from connecting fewer capabilities more deliberately. A private AI agent should have enough access to finish its job, and no interesting access left over.