5.5 KiB
summary, title, read_when
| summary | title | read_when | |||
|---|---|---|---|---|---|
| Connect MCP servers to OpenClaw from the Control UI, CLI, or config | Connect MCP servers |
|
The Model Context Protocol (MCP) is how an agent borrows tools from another program: an MCP server exposes tools, resources, and prompts, and OpenClaw connects to it and makes those tools available to your agents. Server definitions live under mcp.servers in config, and the tools they expose go through the same tool-profile and tool-policy controls as everything else — connecting a server does not bypass your policy.
Add a server from Settings
- Open the Control UI and go to Settings → MCP.
- Under Configured servers, select Add server.
- Give it a unique name and pick a transport: Streamable HTTP, SSE, or Stdio.
- For the HTTP transports, enter the server's
http://orhttps://URL. For stdio, enter the command followed by its arguments. - Select Add server.
That writes the new mcp.servers entry through the Gateway. For anything beyond the basics — headers, environment values, OAuth metadata, TLS settings, timeouts, parallel-tool-call hints, tool filters — use the scoped config editor further down the page. The server rows also let you enable, disable, or remove a definition.
Once the server is saved, verify it actually answers:
openclaw mcp doctor <name> --probe
Saving a definition proves nothing about reachability — the probe does. Note that already-running Gateway or agent processes may need a restart or runtime reload before they pick up the new definition.
Add a server from the composer
In a Control UI chat, select + → Connectors → Add MCP server…. The dialog uses the same server fields as Settings and requires administrator access.
Choose This session for session-only enablement or Everywhere for global enablement. Either scope saves a global server definition; session policy is the per-session layer. See Composer capability menu for the complete scope and tool-access behavior.
From an active conversation, open + → Connectors → Tool access to inspect or deny 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. Session server and tool denials are enforced by either runtime 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; choose a different name. Setting enabled: false keeps the definition around without connecting it. Keep credentials out of config literals — 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 and rerun with --code when prompted.
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.