OpenClaw MCP bridge

Local stdio MCP server that exposes OpenClaw gateway tools to Claude Code, Codex, and other MCP clients. This is the deployed bridge from ~/.openclaw/workspace/scripts/openclaw-mcp-proxy/, verified against OpenClaw 2026.9.1 on Node 24.18.

It is a local bridge, not an OpenClaw installation or a hosted service. No gateway config, credentials, or chat history are in this repository.

What it does

• Proxies gateway tool calls through the local /tools/invoke endpoint, using a generated argument schema with compatibility aliases.

• Implements read, write, edit, exec, glob, grep, and process directly in Node rather than proxying them.

• Adds sessions_yield: suspends the turn until spawned subagents finish, with per-run pending state persisted through atomic renames so concurrent spawns cannot lose updates.

• Resolves the requester agent so tool calls work under agents.ownership: "explicit" (see below).

With a 46-tool gateway schema it advertises 53 tools (46 gateway + 7 proxy-local).

Related MCP server: veriloop

Requirements

• Node.js 24+, and Python 3 for the generator's managed-install discovery.

• A running local OpenClaw gateway with config at ~/.openclaw/openclaw.json.

There are no npm dependencies.

npm test
npm run regen

Client configuration

{
  "mcpServers": {
    "openclaw": {
      "command": "node",
      "args": ["/absolute/path/to/openclaw-mcp/server.js"]
    }
  }
}

A running MCP client keeps its own child process, so restart the client (or reconnect the server) after regenerating the schema.

Tool schema

tools-schema.json is a generated, credential-free snapshot. Regenerate it after every OpenClaw upgrade, then reconnect the client:

npm run regen
# or, for a non-default layout:
OPENCLAW_INSTALL_ROOT=/absolute/path/to/node_modules/openclaw npm run regen

The generator inspects installed runtime factories and the HTTP deny list; it never executes a discovered tool. Plugin tools are read from the active plugin registry (openclaw plugins list --json), so an abandoned project generation left behind by an upgrade cannot leak stale tools into the schema. It depends on OpenClaw internals, so a future release may require a generator update.

Some plugin tools report captured 0/N because they are runtime- or factory-dependent (currently memory-core and codex); those are reachable through the gateway but cannot be captured by a static scan.

Runtime settings

Explicit agent ownership

Since 2026.8 a multi-agent roster sets agents.ownership: "explicit", and the gateway refuses a session key that names no owner — including the bare "main" it falls back to when no key is sent. Every tools/invoke then fails with "has no explicit owner". The bridge resolves a requester agent id once at startup (agents.defaults.systemAgent.agentId → sole agent → "main") and attaches it as a top-level agentId only for unscoped keys; an agent:<id>:<key> key already names its owner and would be rejected for disagreeing.

Gateway deadline

http.request's timeout is socket-idle only, so a gateway that accepts a request and then trickles or stalls could pin a call indefinitely. The bridge enforces its own wall-clock deadline (default 240 s, under Anthropic's ~5 minute idle tool-use boundary) and returns a recoverable MCP error instead of losing the whole turn to "Connection closed mid-response". A single settle path prevents a deadline that races a late reply from resolving and rejecting the same call.

Allowlist

OPENCLAW_MCP_ENABLED_TOOLS is enforced by the server on both tools/list and tools/call. Filtering the advertised list alone is not a boundary, because a client can call a name it was never advertised. A client-side enabled_tools setting is not a boundary either, since another client could ignore it.

Local exec and file tools run with the MCP process's OS permissions; this bridge is not a filesystem sandbox. Gateway-proxied tools remain subject to the gateway's own policies.

Tests

npm test

Covers requester fallback and argument aliasing, unscoped-requester agentId injection, the gateway wall-clock deadline, server-side allowlist enforcement on both list and call, and pending-yield persistence. Tests use temporary state and a fake loopback gateway; they never invoke live provider tools or send messages.

Relationship to everflowinv/openclaw-mcp

everflowinv/openclaw-mcp is a sibling bridge from a different installation, not an upstream of this one. This version takes its schema generator (registry-based plugin discovery, os.homedir(), OPENCLAW_INSTALL_ROOT), its wall-clock gateway deadline, and its tool allowlist.

Deliberately not taken:

• Hardcoded upstream MCP passthrough. That bridge contacts 127.0.0.1:8943 (guidepoint), 127.0.0.1:8950 (alphaengine), and https://mcp.firecrawl.dev at every startup, with tools/list awaiting the discovery. None of those exist for this installation, and there is no environment toggle to disable them.

• Eve Desktop dynamic sessions and the SQLite transcript reconstruction that serves them — installation-specific and disabled by default there.

Both bridges produce a byte-identical 46-tool schema against OpenClaw 2026.9.1.