From 7606e1dd3d3fa9b311b6afc0bd92d03de00292bb Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 31 May 2026 10:12:34 +0100 Subject: [PATCH] docs: expand MCP operator guide --- docs/cli/mcp.md | 246 +++++++++++++++++++++++++++++++++++++++++ docs/web/control-ui.md | 16 +++ 2 files changed, 262 insertions(+) diff --git a/docs/cli/mcp.md b/docs/cli/mcp.md index 6253aef71778..840604105600 100644 --- a/docs/cli/mcp.md +++ b/docs/cli/mcp.md @@ -20,6 +20,23 @@ In other words: Use [`openclaw acp`](/cli/acp) when OpenClaw should host a coding harness session itself and route that runtime through ACP. +## Choose the right MCP path + +OpenClaw has several MCP surfaces. Pick the one that matches who owns the agent runtime and who owns the tools. + +| Goal | Use | Why | +| ------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| Let an external MCP client read/send OpenClaw channel conversations | `openclaw mcp serve` | OpenClaw is the MCP server and exposes Gateway-backed conversations over stdio. | +| Save third-party MCP servers for OpenClaw-managed agent runs | `openclaw mcp add`, `set`, `configure`, `tools`, `login` | OpenClaw is the MCP client-side registry and later projects those servers into eligible runtimes. | +| Check a saved server without running an agent turn | `openclaw mcp status`, `doctor`, `probe` | `status` and `doctor` inspect config; `probe` opens a live MCP connection and lists capabilities. | +| Edit MCP config from a browser | Control UI `/mcp` | The page shows inventory, enablement, OAuth/filter summaries, command hints, and a scoped `mcp` editor. | +| Give Codex app-server a scoped native MCP server | `mcp.servers..codex` | The `codex` block only affects Codex app-server thread projection and is stripped before native config handoff. | +| Run ACP-hosted harness sessions | [`openclaw acp`](/cli/acp) and [ACP Agents](/tools/acp-agents-setup) | ACP bridge mode does not accept per-session MCP server injection; configure gateway/plugin bridges instead. | + + +If you are not sure which path you need, start with `openclaw mcp status --verbose`. It shows what OpenClaw has saved without starting any MCP servers. + + ## OpenClaw as an MCP server This is the `openclaw mcp serve` path. @@ -449,6 +466,166 @@ openclaw mcp logout docs openclaw mcp unset context7 ``` +### Common server recipes + +These examples save server definitions only. Run `openclaw mcp doctor --probe` afterward to prove that the server starts and exposes tools. + + + + ```bash + openclaw mcp add files \ + --command npx \ + --arg -y \ + --arg @modelcontextprotocol/server-filesystem \ + --arg "$HOME/Documents" \ + --include 'read_file,list_directory,search_files' + openclaw mcp doctor files --probe + ``` + + Scope filesystem servers to the smallest directory tree that the agent should read or edit. + + + + ```bash + openclaw mcp add memory \ + --command npx \ + --arg -y \ + --arg @modelcontextprotocol/server-memory + openclaw mcp probe memory --json + ``` + + Use a tool filter if the server exposes write tools that should not be available to normal agents. + + + + ```bash + openclaw mcp add local-tools \ + --command node \ + --arg ./dist/mcp-server.js \ + --cwd /srv/openclaw-tools \ + --env API_BASE=https://internal.example + openclaw mcp status --verbose + ``` + + `doctor` checks that `cwd` exists and that the command resolves from the configured environment. + + + + ```bash + openclaw mcp add docs \ + --url https://mcp.example.com/mcp \ + --transport streamable-http \ + --auth oauth \ + --oauth-scope docs.read \ + --timeout 20 \ + --connect-timeout 5 \ + --include 'search,read_*' + openclaw mcp doctor docs --probe + ``` + + Use OAuth when the remote server supports it. If the server requires static headers, avoid committing literal bearer tokens. + + + + ```bash + openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}' + openclaw mcp tools cua-driver --include 'list_apps,observe,click,type' + openclaw mcp doctor cua-driver --probe + ``` + + Direct desktop-control servers inherit the permissions of the process they launch. Use narrow tool filters and OS-level permission prompts. + + + + +### JSON output shapes + +Use `--json` for scripts and dashboards. Field sets can grow over time, so consumers should ignore unknown keys. + + + + ```json + { + "path": "/home/user/.openclaw/openclaw.json", + "servers": [ + { + "name": "docs", + "configured": true, + "enabled": true, + "ok": true, + "transport": "streamable-http", + "launch": "streamable-http https://mcp.example.com/mcp", + "auth": "oauth", + "authStatus": { + "hasTokens": true, + "hasClientInformation": true, + "hasCodeVerifier": false, + "hasDiscoveryState": true, + "hasLastAuthorizationUrl": false + }, + "requestTimeoutMs": 20000, + "connectionTimeoutMs": 5000, + "toolFilter": { + "include": ["search", "read_*"], + "exclude": [] + }, + "supportsParallelToolCalls": true + } + ] + } + ``` + + + ```json + { + "ok": false, + "path": "/home/user/.openclaw/openclaw.json", + "servers": [ + { + "name": "docs", + "ok": false, + "issues": [ + { + "level": "error", + "message": "OAuth credentials are not authorized; run openclaw mcp login docs" + } + ] + } + ] + } + ``` + + `doctor --json` exits nonzero when any enabled checked server has an error. Warnings are reported but do not make the command fail by themselves. + + + + ```json + { + "path": "/home/user/.openclaw/openclaw.json", + "generatedAt": "2026-05-31T09:00:00.000Z", + "servers": { + "docs": { + "launch": "streamable-http https://mcp.example.com/mcp", + "tools": 2, + "resources": true, + "prompts": false, + "listChanged": { + "tools": true, + "resources": false, + "prompts": false + } + } + }, + "tools": ["docs__read_page", "docs__search"], + "diagnostics": [] + } + ``` + + `probe` opens a live MCP client session. Use it for reachability and capability proof, not for static config audits. + + + + Example config shape: ```json @@ -538,6 +715,58 @@ Example: Sensitive values in `url` (userinfo) and `headers` are redacted in logs and status output. `openclaw mcp doctor` warns when sensitive-looking `headers` or `env` entries contain literal values, so operators can move those values out of committed config. +### OAuth workflow + +OAuth is for HTTP MCP servers that advertise the MCP OAuth flow. Static `Authorization` headers are ignored for a server while `auth: "oauth"` is enabled. + + + + Add or update the server with `auth: "oauth"` and any optional OAuth metadata. + + ```bash + openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}' + ``` + + + + Run login to create the authorization request. + + ```bash + openclaw mcp login docs + ``` + + OpenClaw prints the authorization URL and stores temporary OAuth verifier state under the OpenClaw state directory. + + + + After approving in the browser, pass the returned code back to OpenClaw. + + ```bash + openclaw mcp login docs --code abc123 + ``` + + + + Use status or doctor to confirm that tokens are present. + + ```bash + openclaw mcp status --verbose + openclaw mcp doctor docs --probe + ``` + + + + Logout removes stored OAuth credentials but keeps the saved server definition. + + ```bash + openclaw mcp logout docs + ``` + + + + +If the provider rotates tokens or the authorization state gets stuck, run `openclaw mcp logout `, then repeat `login`. `logout` can clear credentials for a saved HTTP server even after `auth: "oauth"` has been removed from config, as long as the server name and URL still identify the credential store entry. + ### Streamable HTTP transport `streamable-http` is an additional transport option alongside `sse` and `stdio`. It uses HTTP streaming for bidirectional communication with remote MCP servers. @@ -587,6 +816,23 @@ The browser Control UI includes a dedicated MCP settings page at `/mcp`. It show Use the page for operator edits and quick inventory. Use `openclaw mcp doctor --probe` or `openclaw mcp probe` when you need live server proof. +Operator workflow: + +1. Open the Control UI and choose **MCP**. +2. Review the summary cards for total, enabled, OAuth, and filtered servers. +3. Use each server row for transport, auth, filter, timeout, and command hints. +4. Toggle enablement when you want to keep a definition but exclude it from runtime discovery. +5. Edit the scoped `mcp` config section for structural changes such as new servers, headers, TLS, OAuth metadata, or tool filters. +6. Choose **Save** to persist config only, or **Save & Publish** to apply through the Gateway config path. +7. Run `openclaw mcp doctor --probe` when you need live proof that the edited server starts and lists tools. + +Notes: + +- command snippets quote server names so unusual names remain copyable in a shell +- displayed URL-like values are redacted before rendering when they contain embedded credentials +- the page does not start MCP transports by itself +- active runtimes may need `openclaw mcp reload`, Gateway config publish, or process restart depending on which process owns the MCP clients + ## Current limits This page documents the bridge as shipped today. diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index a66b79738089..e84904ffdb05 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -154,6 +154,22 @@ Imported themes are stored only in the current browser profile. They are not wri +## MCP page + +The dedicated MCP page is an operator view for OpenClaw-managed MCP servers under `mcp.servers`. It does not start MCP transports by itself; use it to inspect and edit saved config, then use `openclaw mcp doctor --probe` when you need live server proof. + +Typical workflow: + +1. Open **MCP** from the sidebar. +2. Check the summary cards for total, enabled, OAuth, and filtered server counts. +3. Review each server row for transport, enablement, auth, filters, timeouts, and command hints. +4. Toggle enablement when a server should remain configured but stay out of runtime discovery. +5. Edit the scoped `mcp` config section for server definitions, headers, TLS/mTLS paths, OAuth metadata, tool filters, and Codex projection metadata. +6. Use **Save** for a config write, or **Save & Publish** when the running Gateway should apply the changed config. +7. Run `openclaw mcp status --verbose`, `openclaw mcp doctor --probe`, or `openclaw mcp reload` from a terminal when the edited process needs static diagnostics, live proof, or cached-runtime disposal. + +The page redacts credential-bearing URL-like values before rendering and quotes server names in command snippets so copied commands still work with spaces or shell metacharacters. The full CLI and config reference lives in [MCP](/cli/mcp). + ## Activity tab The Activity tab is an ephemeral browser-local observer for live tool activity. It is derived from the same Gateway `session.tool` / tool event stream that powers Chat tool cards; it does not add another Gateway event family, endpoint, durable activity store, metrics feed, or external observer stream.