liuyu/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-06 05:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: expand MCP operator guide

Browse Source
This commit is contained in:
Peter Steinberger
2026-05-31 10:12:34 +01:00
parent ef7854abbc
commit 7606e1dd3d
2 changed files with 262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
docs/cli/mcp.md
View File

@@ -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.<name>.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. |
<Tip>
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.
</Tip>
## 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.
<Tabs>
<Tab title="Filesystem">
```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.
</Tab>
<Tab title="Memory">
```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.
</Tab>
<Tab title="Local script">
```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.
</Tab>
<Tab title="Remote HTTP">
```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.
</Tab>
<Tab title="Desktop/CUA">
```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.
</Tab>
</Tabs>
### JSON output shapes
Use `--json` for scripts and dashboards. Field sets can grow over time, so consumers should ignore unknown keys.
<AccordionGroup>
<Accordion title="status --json">
```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
}
]
}
```
</Accordion>
<Accordion title="doctor --json">
```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.
</Accordion>
<Accordion title="probe --json">
```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.
</Accordion>
</AccordionGroup>
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.
<Steps>
<Step title="Save the server">
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"}}'
```
</Step>
<Step title="Start login">
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.
</Step>
<Step title="Finish with the code">
After approving in the browser, pass the returned code back to OpenClaw.
```bash
openclaw mcp login docs --code abc123
```
</Step>
<Step title="Check authorization">
Use status or doctor to confirm that tokens are present.
```bash
openclaw mcp status --verbose
openclaw mcp doctor docs --probe
```
</Step>
<Step title="Clear credentials">
Logout removes stored OAuth credentials but keeps the saved server definition.
```bash
openclaw mcp logout docs
```
</Step>
</Steps>
If the provider rotates tokens or the authorization state gets stuck, run `openclaw mcp logout <name>`, 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.

16
docs/web/control-ui.md
View File

@@ -154,6 +154,22 @@ Imported themes are stored only in the current browser profile. They are not wri
</Accordion>
</AccordionGroup>
## 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.