MCP

MCP 문서는 OpenClaw 공식 문서(cli/mcp)를 한국어로 정리한 가이드입니다. Expose OpenClaw channel conversations over MCP and manage saved MCP server definitions 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Expose OpenClaw channel conversations over MCP and manage saved MCP server definitions

한국어 가이드 범위: cli/mcp 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Choose the right MCP path
When to use serve
동작 방식
Choose a client mode
What serve exposes
사용법
Bridge tools
Event model
Claude channel notifications
MCP client config
옵션
Security and trust boundary
Testing
트러블슈팅
Saved MCP server definitions
Common server recipes
JSON output shapes
Stdio transport
SSE / HTTP transport
OAuth workflow
Streamable HTTP transport
Control UI
MCP Apps
Current limits
관련 문서

상세 내용

본문

serve is OpenClaw acting as an MCP server. The other subcommands are OpenClaw acting as an MCP client-side registry for servers its own runtimes may consume later.

주요 항목:

run OpenClaw as an MCP server with openclaw mcp serve
manage OpenClaw-managed outbound MCP server definitions with list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, and unset

Choose the right MCP path

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.

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 `/settings/mcp` (`/mcp` alias)	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` and ACP Agents	ACP bridge mode does not accept per-session MCP server injection; configure gateway/plugin bridges instead.

OpenClaw as an MCP server

This is the openclaw mcp serve path.

When to use serve

Use openclaw acp instead when OpenClaw should host the coding runtime itself and keep the agent session inside OpenClaw.

주요 항목:

Codex, Claude Code, or another MCP client should talk directly to OpenClaw-backed channel conversations
you already have a local or remote OpenClaw Gateway with routed sessions
you want one MCP server that works across OpenClaw's channel backends instead of running separate per-channel bridges

동작 방식

openclaw mcp serve starts a stdio MCP server. The MCP client owns that process. While the client keeps the stdio session open, the bridge connects to a local or remote OpenClaw Gateway over WebSocket and exposes routed channel conversations over MCP.

주요 항목:

live queue state starts when the bridge connects
older transcript history is read with messages_read
Claude push notifications only exist while the MCP session is alive
when the client disconnects, the bridge exits and the live queue is gone
one-shot agent entry points such as openclaw agent and openclaw infer model run retire any bundled MCP runtimes they open when the reply completes, so repeated scripted runs do not accumulate stdio MCP child processes
stdio MCP servers launched by OpenClaw (bundled or user-configured) are torn down as a process tree on shutdown, so child subprocesses started by the server do not survive after the parent stdio client exits
deleting or resetting a session disposes that session's MCP clients through the shared runtime cleanup path, so there are no lingering stdio connections tied to a removed session

Choose a client mode

Standard MCP tools only. Use conversations_list, messages_read, events_poll, events_wait, messages_send, and the approval tools.

What serve exposes

The bridge uses existing Gateway session route metadata to expose channel-backed conversations. A conversation appears when OpenClaw already has session state with a known route such as:

주요 항목:

channel
recipient or destination metadata
optional accountId
optional threadId
list recent routed conversations
read recent transcript history
wait for new inbound events
send a reply back through the same route
see approval requests that arrive while the bridge is connected

사용법

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
    openclaw mcp serve --claude-channel-mode off

Bridge tools

Lists recent session-backed conversations that already have route metadata in Gateway session state.

주요 항목:

requires an existing conversation route
uses the session's channel, recipient, account id, and thread id
sends text only
allow-once
allow-always
deny

Event model

The bridge keeps an in-memory event queue while it is connected.

주요 항목:

message
exec_approval_requested
exec_approval_resolved
plugin_approval_requested
plugin_approval_resolved
claude_permission_request
the queue is live-only; it starts when the MCP bridge starts
events_poll and events_wait do not replay older Gateway history by themselves
durable backlog should be read with messages_read

Claude channel notifications

The bridge can also expose Claude-specific channel notifications. This is the OpenClaw equivalent of a Claude Code channel adapter: standard MCP tools remain available, but live inbound messages can also arrive as Claude-specific MCP notifications.

주요 항목:

notifications/claude/channel
notifications/claude/channel/permission
inbound user transcript messages are forwarded as notifications/claude/channel
Claude permission requests received over MCP are tracked in-memory
if the command owner in the linked conversation later sends yes <id> or no <id> (<id> is the 5-letter request id, excluding l), the bridge converts that to notifications/claude/channel/permission
these notifications are live-session only; if the MCP client disconnects, there is no push target

MCP client config

For most generic MCP clients, start with the standard tool surface and ignore Claude mode. Turn Claude mode on only for clients that actually understand the Claude-specific notification methods.

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

옵션

Gateway WebSocket URL. Defaults to gateway.remote.url when configured.

Security and trust boundary

The bridge does not invent routing. It only exposes conversations that Gateway already knows how to route.

주요 항목:

sender allowlists, pairing, and channel-level trust still belong to the underlying OpenClaw channel configuration
messages_send can only reply through an existing stored route
approval state is live/in-memory only for the current bridge session
bridge auth should use the same Gateway token or password controls you would trust for any other remote Gateway client

Testing

OpenClaw ships a deterministic Docker smoke for this bridge:

pnpm test:docker:mcp-channels

트러블슈팅

Usually means the Gateway session is not already routable. Confirm that the underlying session has stored channel/provider, recipient, and optional account/thread route metadata.

주요 항목:

the client kept the stdio MCP session open
--claude-channel-mode is on or auto
the client actually understands the Claude-specific notification methods
the inbound message happened after the bridge connected

OpenClaw as an MCP client registry

This is the openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, and unset path.

주요 항목:

these commands only read or write OpenClaw config
status, list, show, doctor without --probe, set, configure, tools, logout, reload, and unset do not connect to the target MCP server
login performs the MCP OAuth network flow for the configured HTTP server and saves the resulting local credentials
status --verbose prints resolved transport, auth, timeout, filter, and parallel-tool-call hints without connecting
doctor checks saved definitions for local setup problems such as missing stdio commands, invalid working directories, missing TLS files, disabled servers, literal sensitive header/env values, and incomplete OAuth authorization
doctor --probe adds the same live connection proof as probe after static checks pass
probe connects to the selected server or all configured servers, lists tools, and reports capabilities/diagnostics
add builds a definition from flags and probes before saving unless --no-probe is set or OAuth authorization is needed first
runtime adapters decide which transport shapes they actually support at execution time
enabled: false keeps a server saved but excludes it from embedded runtime discovery
requestTimeoutMs and connectionTimeoutMs set per-server request and connection timeouts in milliseconds
supportsParallelToolCalls: true marks servers that adapters can call concurrently
HTTP servers can use static headers, OAuth login, TLS verification control, and mTLS certificate/key paths
embedded OpenClaw exposes configured MCP tools in normal coding and messaging tool profiles; minimal still hides them, and tools.deny: ["bundle-mcp"] disables them explicitly
per-server toolFilter.include and toolFilter.exclude filter discovered MCP tools before they become OpenClaw tools
servers that advertise resources or prompts also expose utility tools for listing/reading resources and listing/fetching prompts; those generated utility names (resources_list, resources_read, prompts_list, prompts_get) use the same include/exclude filter
dynamic MCP tool-list changes invalidate the cached catalog for that session; the next discovery/use refreshes from the server
repeated MCP tool request/protocol failures pause that server briefly so one broken server does not consume the whole turn
session-scoped bundled MCP runtimes are reaped after 10 minutes of idle time and one-shot embedded runs clean them up at run end

Saved MCP server definitions

주요 항목:

openclaw mcp list
openclaw mcp show [name]
openclaw mcp status [--verbose]
openclaw mcp doctor [name] [--probe]
openclaw mcp probe [name]
openclaw mcp add <name> [flags]
openclaw mcp set <name> <json>
openclaw mcp configure <name> [flags]
openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
openclaw mcp login <name> [--code code]
openclaw mcp logout <name>
openclaw mcp reload
openclaw mcp unset <name>
list sorts server names.
show without a name prints the full configured MCP server object.
status classifies configured transports without connecting. --verbose includes resolved launch, timeout, OAuth, filter, and parallel-call details, including when stored OAuth tokens require additional authorization. Credential-bearing stdio arguments are redacted in text and JSON output.
doctor performs static checks without connecting. Add --probe when the command should also verify that enabled servers connect.
probe connects and reports tool counts, resources/prompts support, list-change support, and diagnostics.
add accepts stdio flags such as --command, --arg, --env, and --cwd, or HTTP flags such as --url, --transport, --header, --auth oauth, TLS, timeout, and tool-selection flags.
set expects one JSON object value on the command line.
configure updates enablement, tool filters, timeouts, OAuth, TLS, and parallel-tool-call hints without replacing the whole server definition. Add --probe to verify the updated server before saving.
tools updates per-server tool filters. Include/exclude entries are MCP tool names and simple * globs.
login runs the OAuth flow for HTTP servers configured with auth: "oauth". The first run prints an authorization URL; rerun with --code after approval.
logout clears stored OAuth credentials for the named server without removing the saved server definition.
reload disposes cached in-process MCP runtimes for the current CLI process only. Gateway or agent processes in another process still need their own reload or restart path.

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'
openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'
openclaw mcp login docs
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.

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

openclaw mcp add memory \
      --command npx \
      --arg -y \
      --arg @modelcontextprotocol/server-memory
    openclaw mcp probe memory --json

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

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

JSON output shapes

Use --json for scripts and dashboards. Field sets can grow over time, so consumers should ignore unknown keys.

{
      "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,
            "requiresAuthorization": false,
            "hasClientInformation": true,
            "hasCodeVerifier": false,
            "hasDiscoveryState": true,
            "hasLastAuthorizationUrl": false
          },
          "requestTimeoutMs": 20000,
          "connectionTimeoutMs": 5000,
          "toolFilter": {
            "include": ["search", "read_*"],
            "exclude": []
          },
          "supportsParallelToolCalls": true
        }
      ]
    }

{
      "ok": true,
      "path": "/home/user/.openclaw/openclaw.json",
      "servers": [
        {
          "name": "docs",
          "ok": true,
          "issues": [
            {
              "level": "warning",
              "message": "OAuth credentials are not authorized; run openclaw mcp login docs"
            }
          ]
        }
      ]
    }

{
      "generatedAt": "2026-05-31T09:00:00.000Z",
      "servers": {
        "docs": {
          "launch": "streamable-http https://mcp.example.com/mcp",
          "tools": 2,
          "resources": true,
          "listChanged": {
            "tools": true,
            "resources": false,
            "prompts": false
          }
        }
      },
      "tools": ["docs__read_page", "docs__search"],
      "diagnostics": []
    }

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http",
        "requestTimeoutMs": 20000,
        "connectionTimeoutMs": 5000,
        "supportsParallelToolCalls": true,
        "auth": "oauth",
        "oauth": {
          "scope": "docs.read"
        },
        "sslVerify": true,
        "clientCert": "/path/to/client.crt",
        "clientKey": "/path/to/client.key",
        "toolFilter": {
          "include": ["search_*"],
          "exclude": ["admin_*"]
        }
      }
    }
  }
}

Stdio transport

Launches a local child process and communicates over stdin/stdout.

Field	Description
`command`	Executable to spawn (required)
`args`	Array of command-line arguments
`env`	Extra environment variables
`cwd` / `workingDirectory`	Working directory for the process

SSE / HTTP transport

Connects to a remote MCP server over HTTP Server-Sent Events.

Field	Description
`url`	HTTP or HTTPS URL of the remote server (required)
`headers`	Optional key-value map of HTTP headers (for example auth tokens)
`connectionTimeoutMs`	Per-server connection timeout in ms (optional)
`requestTimeoutMs`	Per-server MCP request timeout in milliseconds
`auth: "oauth"`	Use MCP OAuth credentials saved by `openclaw mcp login`
`sslVerify`	Set false only for explicitly trusted private HTTPS endpoints
`clientCert` / `clientKey`	mTLS client certificate and key paths
`supportsParallelToolCalls`	Hint that concurrent calls are safe for this server

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "auth": "oauth",
        "requestTimeoutMs": 20000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

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. Credentials saved by openclaw mcp login work with embedded MCP, CLI runners, and the local Codex app-server.

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

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.

Field	Description
`url`	HTTP or HTTPS URL of the remote server (required)
`transport`	Set to `"streamable-http"` to select this transport; when omitted, OpenClaw uses `sse`
`headers`	Optional key-value map of HTTP headers (for example auth tokens)
`connectionTimeoutMs`	Per-server connection timeout in ms (optional)
`requestTimeoutMs`	Per-server MCP request timeout in milliseconds
`auth: "oauth"`	Use MCP OAuth credentials saved by `openclaw mcp login`
`sslVerify`	Set false only for explicitly trusted private HTTPS endpoints
`clientCert` / `clientKey`	mTLS client certificate and key paths
`supportsParallelToolCalls`	Hint that concurrent calls are safe for this server

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 30000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Control UI

The browser Control UI includes a dedicated MCP settings page at /settings/mcp; the previous /mcp path remains an alias. The page shows configured server counts, enabled/OAuth/filter summaries, per-server transport rows, enable/disable controls, common CLI commands, and a scoped editor for the mcp config section.

주요 항목:

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

MCP Apps

OpenClaw can render tools that implement the stable MCP Apps extension. Apps are opt-in because their HTML comes from the configured MCP server and can request app-visible tools or resources from that same server.

주요 항목:

OpenClaw advertises the io.modelcontextprotocol/ui extension only when Apps are enabled.
Only ui:// resources with the exact text/html;profile=mcp-app MIME type render.
UI resources are capped at 2 MiB, placed behind a double-iframe proxy on a dedicated outer origin, loaded into an opaque inner App origin, and constrained by CSP derived from the resource metadata.
App-only tools (_meta.ui.visibility: ["app"]) stay out of model tool lists. Apps can call only app-visible tools on their owning server that also pass the effective OpenClaw tool policy for the run that created the view.
Origin-bound App permissions such as camera, microphone, and geolocation are not granted while inner App documents use opaque origins for cross-App isolation.
App HTML, complete tool arguments, and raw results live in a bounded ten-minute in-memory view lease and are not written to disk or copied into transcript preview metadata. The transcript stores only a bounded server/tool/resource descriptor tied to the original tool-call ID. After a Gateway restart, the Control UI can verify that descriptor against the authenticated session transcript and refetch the ui:// resource; reconstructed views are read-only until a fresh run establishes current tool permissions.
In channel conversations, the latest successful App view in a turn adds one Open App-style action to the final assistant reply. Telegram DMs use a native Mini App button; Slack and Discord render the same portable action as a link. Other channels keep the original reply text and append an understandable HTTPS link.
Channel launch links are available only when Gateway Tailscale exposure has prepared a published HTTPS origin. gateway.tailscale.mode: "serve" is reachable only from the tailnet; "funnel" is reachable from the public internet. An externally managed Funnel preserved by gateway.tailscale.preserveFunnel is also treated as internet-reachable. See Tailscale.
Launch tickets are opaque, minted only while materializing the final channel reply, and expire after at most two minutes or when the underlying view lease expires, whichever comes first. The URL does not contain Gateway bearer credentials, session keys, view metadata, App HTML, tool input, or tool results.
If no published origin or ticket capacity is available, the view or ticket has expired, or the transport cannot render native controls, the original assistant text remains available. The Control UI keeps its existing inline App canvas and does not receive a duplicate launch action.
openclaw security audit warns while the bridge is enabled. Disable it with openclaw config set mcp.apps.enabled false --strict-json when it is not needed.

openclaw config set mcp.apps.enabled true --strict-json

{
  mcp: {
    apps: {
      enabled: true,
      sandboxOrigin: "https://mcp-apps.example.com",
      sandboxPort: 18790,
    },
  },
}

{
  mcp: {
    apps: { enabled: true },
    servers: {
      "basic-react": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],
      },
    },
  },
}

Current limits

This page documents the bridge as shipped today.

주요 항목:

conversation discovery depends on existing Gateway session route metadata
no generic push protocol beyond the Claude-specific adapter
no message edit or react tools yet
HTTP/SSE/streamable-http transport connects to a single remote server; no multiplexed upstream yet
permissions_list_open only includes approvals observed while the bridge is connected

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/cli/mcp
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
    openclaw mcp serve --claude-channel-mode off

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

pnpm test:docker:mcp-channels

MCP

핵심 요약

Expose OpenClaw channel conversations over MCP and manage saved MCP server definitions

한국어 가이드 범위: cli/mcp 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Choose the right MCP path
When to use serve
동작 방식
Choose a client mode
What serve exposes
사용법
Bridge tools
Event model
Claude channel notifications
MCP client config
옵션
Security and trust boundary
Testing
트러블슈팅
Saved MCP server definitions
Common server recipes
JSON output shapes
Stdio transport
SSE / HTTP transport
OAuth workflow
Streamable HTTP transport
Control UI
MCP Apps
Current limits
관련 문서

상세 내용

본문

serve is OpenClaw acting as an MCP server. The other subcommands are OpenClaw acting as an MCP client-side registry for servers its own runtimes may consume later.

주요 항목:

run OpenClaw as an MCP server with openclaw mcp serve
manage OpenClaw-managed outbound MCP server definitions with list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, and unset

Choose the right MCP path

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.

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 `/settings/mcp` (`/mcp` alias)	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` and ACP Agents	ACP bridge mode does not accept per-session MCP server injection; configure gateway/plugin bridges instead.

OpenClaw as an MCP server

This is the openclaw mcp serve path.

When to use serve

Use openclaw acp instead when OpenClaw should host the coding runtime itself and keep the agent session inside OpenClaw.

주요 항목:

Codex, Claude Code, or another MCP client should talk directly to OpenClaw-backed channel conversations
you already have a local or remote OpenClaw Gateway with routed sessions
you want one MCP server that works across OpenClaw's channel backends instead of running separate per-channel bridges

동작 방식

주요 항목:

live queue state starts when the bridge connects
older transcript history is read with messages_read
Claude push notifications only exist while the MCP session is alive
when the client disconnects, the bridge exits and the live queue is gone
one-shot agent entry points such as openclaw agent and openclaw infer model run retire any bundled MCP runtimes they open when the reply completes, so repeated scripted runs do not accumulate stdio MCP child processes
stdio MCP servers launched by OpenClaw (bundled or user-configured) are torn down as a process tree on shutdown, so child subprocesses started by the server do not survive after the parent stdio client exits
deleting or resetting a session disposes that session's MCP clients through the shared runtime cleanup path, so there are no lingering stdio connections tied to a removed session

Choose a client mode

Standard MCP tools only. Use conversations_list, messages_read, events_poll, events_wait, messages_send, and the approval tools.

What serve exposes

The bridge uses existing Gateway session route metadata to expose channel-backed conversations. A conversation appears when OpenClaw already has session state with a known route such as:

주요 항목:

channel
recipient or destination metadata
optional accountId
optional threadId
list recent routed conversations
read recent transcript history
wait for new inbound events
send a reply back through the same route
see approval requests that arrive while the bridge is connected

사용법

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
    openclaw mcp serve --claude-channel-mode off

Bridge tools

Lists recent session-backed conversations that already have route metadata in Gateway session state.

주요 항목:

requires an existing conversation route
uses the session's channel, recipient, account id, and thread id
sends text only
allow-once
allow-always
deny

Event model

The bridge keeps an in-memory event queue while it is connected.

주요 항목:

message
exec_approval_requested
exec_approval_resolved
plugin_approval_requested
plugin_approval_resolved
claude_permission_request
the queue is live-only; it starts when the MCP bridge starts
events_poll and events_wait do not replay older Gateway history by themselves
durable backlog should be read with messages_read

Claude channel notifications

주요 항목:

notifications/claude/channel
notifications/claude/channel/permission
inbound user transcript messages are forwarded as notifications/claude/channel
Claude permission requests received over MCP are tracked in-memory
if the command owner in the linked conversation later sends yes <id> or no <id> (<id> is the 5-letter request id, excluding l), the bridge converts that to notifications/claude/channel/permission
these notifications are live-session only; if the MCP client disconnects, there is no push target

MCP client config

For most generic MCP clients, start with the standard tool surface and ignore Claude mode. Turn Claude mode on only for clients that actually understand the Claude-specific notification methods.

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

옵션

Gateway WebSocket URL. Defaults to gateway.remote.url when configured.

Security and trust boundary

The bridge does not invent routing. It only exposes conversations that Gateway already knows how to route.

주요 항목:

sender allowlists, pairing, and channel-level trust still belong to the underlying OpenClaw channel configuration
messages_send can only reply through an existing stored route
approval state is live/in-memory only for the current bridge session
bridge auth should use the same Gateway token or password controls you would trust for any other remote Gateway client

Testing

OpenClaw ships a deterministic Docker smoke for this bridge:

pnpm test:docker:mcp-channels

트러블슈팅

Usually means the Gateway session is not already routable. Confirm that the underlying session has stored channel/provider, recipient, and optional account/thread route metadata.

주요 항목:

the client kept the stdio MCP session open
--claude-channel-mode is on or auto
the client actually understands the Claude-specific notification methods
the inbound message happened after the bridge connected

OpenClaw as an MCP client registry

This is the openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload, and unset path.

주요 항목:

these commands only read or write OpenClaw config
status, list, show, doctor without --probe, set, configure, tools, logout, reload, and unset do not connect to the target MCP server
login performs the MCP OAuth network flow for the configured HTTP server and saves the resulting local credentials
status --verbose prints resolved transport, auth, timeout, filter, and parallel-tool-call hints without connecting
doctor checks saved definitions for local setup problems such as missing stdio commands, invalid working directories, missing TLS files, disabled servers, literal sensitive header/env values, and incomplete OAuth authorization
doctor --probe adds the same live connection proof as probe after static checks pass
probe connects to the selected server or all configured servers, lists tools, and reports capabilities/diagnostics
add builds a definition from flags and probes before saving unless --no-probe is set or OAuth authorization is needed first
runtime adapters decide which transport shapes they actually support at execution time
enabled: false keeps a server saved but excludes it from embedded runtime discovery
requestTimeoutMs and connectionTimeoutMs set per-server request and connection timeouts in milliseconds
supportsParallelToolCalls: true marks servers that adapters can call concurrently
HTTP servers can use static headers, OAuth login, TLS verification control, and mTLS certificate/key paths
embedded OpenClaw exposes configured MCP tools in normal coding and messaging tool profiles; minimal still hides them, and tools.deny: ["bundle-mcp"] disables them explicitly
per-server toolFilter.include and toolFilter.exclude filter discovered MCP tools before they become OpenClaw tools
servers that advertise resources or prompts also expose utility tools for listing/reading resources and listing/fetching prompts; those generated utility names (resources_list, resources_read, prompts_list, prompts_get) use the same include/exclude filter
dynamic MCP tool-list changes invalidate the cached catalog for that session; the next discovery/use refreshes from the server
repeated MCP tool request/protocol failures pause that server briefly so one broken server does not consume the whole turn
session-scoped bundled MCP runtimes are reaped after 10 minutes of idle time and one-shot embedded runs clean them up at run end

Saved MCP server definitions

주요 항목:

openclaw mcp list
openclaw mcp show [name]
openclaw mcp status [--verbose]
openclaw mcp doctor [name] [--probe]
openclaw mcp probe [name]
openclaw mcp add <name> [flags]
openclaw mcp set <name> <json>
openclaw mcp configure <name> [flags]
openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
openclaw mcp login <name> [--code code]
openclaw mcp logout <name>
openclaw mcp reload
openclaw mcp unset <name>
list sorts server names.
show without a name prints the full configured MCP server object.
status classifies configured transports without connecting. --verbose includes resolved launch, timeout, OAuth, filter, and parallel-call details, including when stored OAuth tokens require additional authorization. Credential-bearing stdio arguments are redacted in text and JSON output.
doctor performs static checks without connecting. Add --probe when the command should also verify that enabled servers connect.
probe connects and reports tool counts, resources/prompts support, list-change support, and diagnostics.
add accepts stdio flags such as --command, --arg, --env, and --cwd, or HTTP flags such as --url, --transport, --header, --auth oauth, TLS, timeout, and tool-selection flags.
set expects one JSON object value on the command line.
configure updates enablement, tool filters, timeouts, OAuth, TLS, and parallel-tool-call hints without replacing the whole server definition. Add --probe to verify the updated server before saving.
tools updates per-server tool filters. Include/exclude entries are MCP tool names and simple * globs.
login runs the OAuth flow for HTTP servers configured with auth: "oauth". The first run prints an authorization URL; rerun with --code after approval.
logout clears stored OAuth credentials for the named server without removing the saved server definition.
reload disposes cached in-process MCP runtimes for the current CLI process only. Gateway or agent processes in another process still need their own reload or restart path.

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'
openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'
openclaw mcp login docs
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.

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

openclaw mcp add memory \
      --command npx \
      --arg -y \
      --arg @modelcontextprotocol/server-memory
    openclaw mcp probe memory --json

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

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

JSON output shapes

Use --json for scripts and dashboards. Field sets can grow over time, so consumers should ignore unknown keys.

{
      "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,
            "requiresAuthorization": false,
            "hasClientInformation": true,
            "hasCodeVerifier": false,
            "hasDiscoveryState": true,
            "hasLastAuthorizationUrl": false
          },
          "requestTimeoutMs": 20000,
          "connectionTimeoutMs": 5000,
          "toolFilter": {
            "include": ["search", "read_*"],
            "exclude": []
          },
          "supportsParallelToolCalls": true
        }
      ]
    }

{
      "ok": true,
      "path": "/home/user/.openclaw/openclaw.json",
      "servers": [
        {
          "name": "docs",
          "ok": true,
          "issues": [
            {
              "level": "warning",
              "message": "OAuth credentials are not authorized; run openclaw mcp login docs"
            }
          ]
        }
      ]
    }

{
      "generatedAt": "2026-05-31T09:00:00.000Z",
      "servers": {
        "docs": {
          "launch": "streamable-http https://mcp.example.com/mcp",
          "tools": 2,
          "resources": true,
          "listChanged": {
            "tools": true,
            "resources": false,
            "prompts": false
          }
        }
      },
      "tools": ["docs__read_page", "docs__search"],
      "diagnostics": []
    }

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http",
        "requestTimeoutMs": 20000,
        "connectionTimeoutMs": 5000,
        "supportsParallelToolCalls": true,
        "auth": "oauth",
        "oauth": {
          "scope": "docs.read"
        },
        "sslVerify": true,
        "clientCert": "/path/to/client.crt",
        "clientKey": "/path/to/client.key",
        "toolFilter": {
          "include": ["search_*"],
          "exclude": ["admin_*"]
        }
      }
    }
  }
}

Stdio transport

Launches a local child process and communicates over stdin/stdout.

Field	Description
`command`	Executable to spawn (required)
`args`	Array of command-line arguments
`env`	Extra environment variables
`cwd` / `workingDirectory`	Working directory for the process

SSE / HTTP transport

Connects to a remote MCP server over HTTP Server-Sent Events.

Field	Description
`url`	HTTP or HTTPS URL of the remote server (required)
`headers`	Optional key-value map of HTTP headers (for example auth tokens)
`connectionTimeoutMs`	Per-server connection timeout in ms (optional)
`requestTimeoutMs`	Per-server MCP request timeout in milliseconds
`auth: "oauth"`	Use MCP OAuth credentials saved by `openclaw mcp login`
`sslVerify`	Set false only for explicitly trusted private HTTPS endpoints
`clientCert` / `clientKey`	mTLS client certificate and key paths
`supportsParallelToolCalls`	Hint that concurrent calls are safe for this server

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "auth": "oauth",
        "requestTimeoutMs": 20000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

OAuth workflow

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

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.

Field	Description
`url`	HTTP or HTTPS URL of the remote server (required)
`transport`	Set to `"streamable-http"` to select this transport; when omitted, OpenClaw uses `sse`
`headers`	Optional key-value map of HTTP headers (for example auth tokens)
`connectionTimeoutMs`	Per-server connection timeout in ms (optional)
`requestTimeoutMs`	Per-server MCP request timeout in milliseconds
`auth: "oauth"`	Use MCP OAuth credentials saved by `openclaw mcp login`
`sslVerify`	Set false only for explicitly trusted private HTTPS endpoints
`clientCert` / `clientKey`	mTLS client certificate and key paths
`supportsParallelToolCalls`	Hint that concurrent calls are safe for this server

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 30000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

Control UI

주요 항목:

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

MCP Apps

주요 항목:

OpenClaw advertises the io.modelcontextprotocol/ui extension only when Apps are enabled.
Only ui:// resources with the exact text/html;profile=mcp-app MIME type render.
UI resources are capped at 2 MiB, placed behind a double-iframe proxy on a dedicated outer origin, loaded into an opaque inner App origin, and constrained by CSP derived from the resource metadata.
App-only tools (_meta.ui.visibility: ["app"]) stay out of model tool lists. Apps can call only app-visible tools on their owning server that also pass the effective OpenClaw tool policy for the run that created the view.
Origin-bound App permissions such as camera, microphone, and geolocation are not granted while inner App documents use opaque origins for cross-App isolation.
App HTML, complete tool arguments, and raw results live in a bounded ten-minute in-memory view lease and are not written to disk or copied into transcript preview metadata. The transcript stores only a bounded server/tool/resource descriptor tied to the original tool-call ID. After a Gateway restart, the Control UI can verify that descriptor against the authenticated session transcript and refetch the ui:// resource; reconstructed views are read-only until a fresh run establishes current tool permissions.
In channel conversations, the latest successful App view in a turn adds one Open App-style action to the final assistant reply. Telegram DMs use a native Mini App button; Slack and Discord render the same portable action as a link. Other channels keep the original reply text and append an understandable HTTPS link.
Channel launch links are available only when Gateway Tailscale exposure has prepared a published HTTPS origin. gateway.tailscale.mode: "serve" is reachable only from the tailnet; "funnel" is reachable from the public internet. An externally managed Funnel preserved by gateway.tailscale.preserveFunnel is also treated as internet-reachable. See Tailscale.
Launch tickets are opaque, minted only while materializing the final channel reply, and expire after at most two minutes or when the underlying view lease expires, whichever comes first. The URL does not contain Gateway bearer credentials, session keys, view metadata, App HTML, tool input, or tool results.
If no published origin or ticket capacity is available, the view or ticket has expired, or the transport cannot render native controls, the original assistant text remains available. The Control UI keeps its existing inline App canvas and does not receive a duplicate launch action.
openclaw security audit warns while the bridge is enabled. Disable it with openclaw config set mcp.apps.enabled false --strict-json when it is not needed.

openclaw config set mcp.apps.enabled true --strict-json

{
  mcp: {
    apps: {
      enabled: true,
      sandboxOrigin: "https://mcp-apps.example.com",
      sandboxPort: 18790,
    },
  },
}

{
  mcp: {
    apps: { enabled: true },
    servers: {
      "basic-react": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],
      },
    },
  },
}

Current limits

This page documents the bridge as shipped today.

주요 항목:

conversation discovery depends on existing Gateway session route metadata
no generic push protocol beyond the Claude-specific adapter
no message edit or react tools yet
HTTP/SSE/streamable-http transport connects to a single remote server; no multiplexed upstream yet
permissions_list_open only includes approvals observed while the bridge is connected

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/cli/mcp
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
    openclaw mcp serve --claude-channel-mode off

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

pnpm test:docker:mcp-channels

MCP

핵심 요약

문서 구성

상세 내용

본문

Choose the right MCP path

OpenClaw as an MCP server

When to use serve

동작 방식

Choose a client mode

What serve exposes

사용법

Bridge tools

Event model

Claude channel notifications

MCP client config

옵션

Security and trust boundary

Testing

트러블슈팅

OpenClaw as an MCP client registry

Saved MCP server definitions

Common server recipes

JSON output shapes

Stdio transport

SSE / HTTP transport

OAuth workflow

Streamable HTTP transport

Control UI

MCP Apps

Current limits

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

MCP

핵심 요약

문서 구성

상세 내용

본문

Choose the right MCP path

OpenClaw as an MCP server

When to use serve

동작 방식

Choose a client mode

What serve exposes

사용법

Bridge tools

Event model

Claude channel notifications

MCP client config

옵션

Security and trust boundary

Testing

트러블슈팅

OpenClaw as an MCP client registry

Saved MCP server definitions

Common server recipes

JSON output shapes

Stdio transport

SSE / HTTP transport

OAuth workflow

Streamable HTTP transport

Control UI

MCP Apps

Current limits

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드