mcp.md

OpenClaw rejects interpreter-startup, loader-hijack, and shell-init env keys before spawning a stdio MCP server, even if they appear in a server's env block. This uses the same host environment security policy as other OpenClaw-spawned processes: it blocks known interpreter startup hooks (for example NODE_OPTIONS, PYTHONSTARTUP, PERL5OPT, RUBYOPT, BASHOPTS, KSH_ENV), shared-library and function-injection prefixes (DYLD_*, LD_*, BASH_FUNC_*), and similar runtime-control variables. Startup drops these silently and logs a warning so they cannot inject an implicit prelude, swap the interpreter, enable a debugger, or hijack the dynamic linker against the stdio process. An explicit allowlist keeps ordinary MCP credential env vars usable (GITHUB_TOKEN, GH_TOKEN, GITLAB_TOKEN, NPM_TOKEN, NODE_AUTH_TOKEN, DATABASE_URL, MONGODB_URI, REDIS_URL, AMQP_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET), along with ordinary proxy and server-specific env vars (HTTP_PROXY, custom *_API_KEY, etc.). Other AWS_* keys such as AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE remain blocked because they point at credential files rather than carry a credential value directly.

If your MCP server genuinely needs one of the blocked variables, set it on the gateway host process instead of under the stdio server's env.

SSE / HTTP transport

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

Example:

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

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. By default, OAuth credentials are shared and operator-managed. Credentials saved by openclaw mcp login work with embedded MCP, CLI runners, and the local Codex app-server.

Native MCP OAuth sessions live in the owner-only shared SQLite database at <state-dir>/state/openclaw.sqlite (mcp_oauth_stores). The row can contain access and refresh tokens, dynamic client registration secrets, discovery metadata, and the temporary PKCE verifier. Refresh, login, and logout use the same SQLite lease, so parallel OpenClaw processes cannot consume one refresh token or resurrect a logged-out session.

Upgrades from the retired <state-dir>/mcp-oauth/*.json store are handled only by openclaw doctor --fix. Runtime code never reads, writes, or falls back to those files.

Until shared credentials are available, OpenClaw omits only that MCP server from the agent runtime instead of failing the agent turn. The operator, or an agent with shell access, can then run openclaw mcp login <name> and use the server on a later turn.

If a server rejects a token with insufficient_scope, OpenClaw preserves the requested scope and asks for openclaw mcp login <name> instead of repeating a refresh that cannot grant new scope. That login starts a new authorization request while keeping the previous token until replacement credentials are saved.

When a remote MCP service is already backed by a separate OpenClaw refresh-capable auth profile, you can optionally set oauth.authProfileId. OpenClaw refreshes either credential source before runtime projection and passes only the current access token to the downstream MCP client.

Set oauth.identity: "per-requester" when every authenticated sender should connect a separate account. Per-requester OAuth requires an HTTP server URL and cannot use oauth.authProfileId. Configure gateway.publicOrigin as the externally reachable HTTPS origin of the Gateway; HTTP is accepted only for literal loopback hosts (localhost, 127.0.0.1, or [::1]) during local development. The provider redirects to <gateway.publicOrigin>/oauth/mcp/callback after authorization.

{
  gateway: {
    publicOrigin: "https://gateway.example.com",
  },
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        auth: "oauth",
        oauth: {
          identity: "per-requester",
          scope: "docs.read",
        },
      },
    },
  },
}

The per-requester flow is sender-driven:

1. The sender calls a tool from the server before connecting an account.
2. OpenClaw returns a sign-in link for that sender instead of exposing another sender's credentials.
3. The provider redirects through the Gateway callback. After the callback succeeds, the sender retries the tool call with their connected account.

If gateway.publicOrigin is missing, the sign-in result names that setting and openclaw doctor reports the same operator fix. openclaw mcp login and openclaw mcp logout remain operator-only commands for shared credentials; they do not manage per-requester accounts.

Sign-in links are single-use bearer links: any chat participant who opens one connects their own account to the sender the link was issued for. Use per-requester OAuth in channels where every trusted sender is mutually trusted; a requester-private sign-in handoff is tracked as follow-up work.

The shared operator flow uses the following commands:

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

For an auth-profile-backed bearer, save the profile binding:

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

```bash
openclaw mcp login docs
```

OpenClaw starts the registered loopback callback, prints the authorization URL, and stores temporary OAuth verifier state in shared SQLite. Approve the request in the browser and return to the terminal; token exchange completes automatically after the callback arrives.

```bash
openclaw mcp login docs --code abc123
```

```bash
openclaw mcp status --verbose
openclaw mcp doctor docs --probe
```

```bash
openclaw mcp logout docs
```

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.

OpenClaw config uses transport: "streamable-http" as the canonical spelling. CLI-native MCP type: "http" values are accepted when saved through openclaw mcp set and repaired by openclaw doctor --fix in existing config, but transport is what embedded OpenClaw consumes directly.

Example:

{
  "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.

For a shorter setup walkthrough covering Settings, the composer path (+ → Connectors → Add MCP server…) and its This session / Everywhere scopes, CLI, and direct config, see Connect MCP servers.

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

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. A view with current App-interaction authority can request app-visible tools and resources from that same server.

Enable the host bridge:

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

Restart the Gateway after changing this setting. When enabled, OpenClaw starts a sandbox-only HTTP(S) listener on the Gateway port plus one (for the default Gateway, 18790). The Control UI loads Apps from that separate origin; the listener never serves Control UI, authenticated Gateway routes, or user data.

Direct Gateway connections need access to both ports. If a reverse proxy or TLS terminator exposes the Control UI, give Apps a dedicated public origin and proxy only that origin to the sandbox listener:

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

The sandbox origin must differ from the Control UI origin. Do not host other authenticated or sensitive content on it.

For example, the official basic React demo can be configured as:

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

Behavior and security boundaries:

• 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.
• Same-server resource listing and reads require that same current App-interaction authority. OpenClaw rechecks after upstream resource work, so a grant revoked in flight cannot return resource data to the App.
• 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:// document for display; reconstructed views cannot call tools or use the resource bridge until a fresh run establishes current App-interaction authority.
• 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; password-authenticated "funnel" is reachable from the public internet. Externally managed Funnel routes targeting the ordinary Gateway listener must migrate to managed "funnel" mode before OpenClaw can publish an internet-reachable origin. 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.
• Standalone App windows allow 30 seconds to load the view. Each server's requestTimeoutMs applies to individual MCP requests, not to a complete App operation that may refresh the catalog before calling a tool. App request cancellation or closing the window aborts its browser request and propagates to the managed MCP runtime; other callers can still finish a shared catalog refresh. Cancellation cannot undo side effects already performed by the server.
• When an App requests teardown, existing calls and authorized cleanup calls can finish until the App acknowledges shutdown or the one-second grace period expires. Closing or navigating away from the window cancels immediately.
• Returning to a standalone App restored from the browser's back/forward cache reloads and revalidates the view instead of reviving its torn-down connection. This resets transient App state and does not automatically retry interrupted operations. If the launch ticket has expired, open a fresh App link.
• 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.

Current limits

This page documents the bridge as shipped today.

Current limits:

• 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

Related

• Connect MCP servers
• CLI reference
• Plugins