openclaw-mcp CLAUDE.md

CLAUDE.md — openclaw-mcp Dev Guide

What this is

MCP (Model Context Protocol) server that bridges Claude Code ↔ OpenClaw agents. It's a stdio-based server — Claude Code spawns it as a subprocess and communicates via JSON-RPC over stdin/stdout.

Project structure

src/index.ts     — All the server logic (tools, handlers)
dist/            — Compiled output (gitignored)
package.json     — npm package config
tsconfig.json    — TypeScript config (ES2022, Node16 modules)

Build & run

npm install
npm run build        # tsc → dist/
npm run dev          # tsx for fast iteration (no compile step)

Test the server manually

The server speaks JSON-RPC 2.0 over stdio. Quick smoke test:

OPENCLAW_GATEWAY_URL=http://localhost:18789 \
OPENCLAW_GATEWAY_TOKEN=your_token \
node dist/index.js

It should print to stderr: OpenClaw MCP server running (gateway: http://localhost:18789) Then block waiting for JSON-RPC input. Ctrl+C to exit.

Adding a new tool

1. Add the tool definition in the ListToolsRequestSchema handler
2. Add a case in the CallToolRequestSchema switch
3. npm run build

Key design decisions

• No axios — uses native fetch() (Node 20+)
• Stdio transport — standard MCP pattern, works with claude mcp add
• Session keys — agent:{name}:mcp keeps MCP convos separate from Discord
• Error handling — tools return error text, never crash the server process
• 120s timeout — agents can be slow; give them room

Environment

• OPENCLAW_GATEWAY_URL — default http://localhost:18789
• OPENCLAW_GATEWAY_TOKEN — no default, logs warning if missing

Gateway API

The server talks to the OpenClaw gateway, which is OpenAI-compatible:

• POST /v1/chat/completions — send a message to an agent
• GET /v1/models — list available agents

Model IDs are in the format openclaw:{agent} (e.g. openclaw:daemon).