How to add OpenClaw MCP Server to Windsurf

Secure bridge between Claude.ai/Desktop and a self-hosted OpenClaw AI assistant, with OAuth2 and multi-instance routing. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 173★ · stdio · oauth

Windsurf config for OpenClaw MCP Server

npx openclaw-mcp

{
  "mcpServers": {
    "openclaw-mcp-server": {
      "command": "npx",
      "args": [
        "openclaw-mcp"
      ],
      "env": {
        "OPENCLAW_URL": "http://127.0.0.1:18789",
        "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
        "OPENCLAW_MODEL": "openclaw",
        "OPENCLAW_TIMEOUT_MS": "300000"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the OpenClaw MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5OpenClaw MCP Server's tools become available to Cascade.

Before you start

Node.js >= 20
An OpenClaw gateway running with the HTTP API enabled (gateway.http.endpoints.chatCompletions.enabled = true)
OPENCLAW_GATEWAY_TOKEN for the OpenClaw gateway
For remote (Claude.ai) use: AUTH_ENABLED with MCP_CLIENT_ID / MCP_CLIENT_SECRET, MCP_ISSUER_URL and TRUST_PROXY=1 behind a reverse proxy
Docker (optional, for the GHCR image deployment)

What OpenClaw MCP Server can do in Windsurf

openclaw_chat

Send messages to OpenClaw and get responses (synchronous). Accepts an optional instance parameter to target a specific gateway.

openclaw_status

Check OpenClaw gateway health. Accepts an optional instance parameter.

openclaw_instances

List all configured OpenClaw instances (tokens are never exposed).

openclaw_chat_async

Queue a message for a long-running operation and get a task_id immediately. Accepts an optional instance parameter.

openclaw_task_status

Check task progress and get results.

openclaw_task_list

List all tasks with filtering.

openclaw_task_cancel

Cancel a pending task.

Security

Always enable authentication in production: set AUTH_ENABLED=true with MCP_CLIENT_ID and a strong MCP_CLIENT_SECRET (e.g. openssl rand -hex 32). Restrict origins via CORS_ORIGINS (e.g. https://claude.ai). When running behind a reverse proxy you must set MCP_ISSUER_URL to your public HTTPS URL and TRUST_PROXY=1, otherwise OAuth metadata and the /token rate limiter break. The remote connector URL must end with /mcp (the Streamable HTTP endpoint). OAuth 2.1 is used for the remote (Claude.ai) transport; the local stdio transport authenticates to the OpenClaw gateway via OPENCLAW_GATEWAY_TOKEN. Tokens are never exposed via openclaw_instances. The Docker image runs read_only with no-new-privileges.

OpenClaw MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the OpenClaw MCP Server config there under the "mcpServers" key and restart the client.

Is OpenClaw MCP Server safe to use with Windsurf?

Do I need Docker?

No. Docker is the recommended path for remote (Claude.ai) deployments via the GHCR image, but you can also run it locally with `npx openclaw-mcp` for Claude Desktop, or remotely with `npx openclaw-mcp --transport http --port 3000`.

Why does my Claude.ai connector return 404 after OAuth?

The connector URL must end with /mcp, which is the Streamable HTTP endpoint. A bare domain hits the server root and returns 404 after OAuth completes.

What must I set behind a reverse proxy?

Set MCP_ISSUER_URL (or --issuer-url) to your public HTTPS URL so OAuth metadata is correct, and TRUST_PROXY=1 (or --trust-proxy 1) so express-rate-limit accepts the proxy's X-Forwarded-For header instead of crashing /token.

View repo Full OpenClaw MCP Server page