openclaw-mcp 1.3.0 → 1.4.0

package/README.md

@@ -47,6 +47,7 @@ services:
     environment:
       - OPENCLAW_URL=http://host.docker.internal:18789
       - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
+      - OPENCLAW_MODEL=openclaw
       - AUTH_ENABLED=true
       - MCP_CLIENT_ID=openclaw
       - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
@@ -88,6 +89,7 @@ Add to your Claude Desktop config:
       "env": {
         "OPENCLAW_URL": "http://127.0.0.1:18789",
         "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
+        "OPENCLAW_MODEL": "openclaw",
         "OPENCLAW_TIMEOUT_MS": "300000"
       }
     }
@@ -141,6 +143,7 @@ See [Installation Guide](docs/installation.md) for details.
 |------|-------------|
 | `openclaw_chat` | Send messages to OpenClaw and get responses |
 | `openclaw_status` | Check OpenClaw gateway health |
+| `openclaw_instances` | List all configured OpenClaw instances |
 
 ### Async Tools (for long-running operations)
 
@@ -151,6 +154,80 @@ See [Installation Guide](docs/installation.md) for details.
 | `openclaw_task_list` | List all tasks with filtering |
 | `openclaw_task_cancel` | Cancel a pending task |
 
+## Multi-Instance Mode
+
+Orchestrate multiple OpenClaw gateways from a single MCP server. One bridge, many claws — route requests to prod, staging, dev, or whatever you name them (lobster-supreme and the-claw-abides are perfectly valid names).
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                        Claude.ai / Claude Desktop                    │
+│                              (MCP Client)                            │
+└──────────────────────┬───────────────────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                     OpenClaw MCP Bridge Server                        │
+│                                                                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
+│  │  Instance     │  │  Instance     │  │  Instance     │              │
+│  │  Registry     │  │  Resolver     │  │  Validator    │              │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
+│         │                 │                  │                        │
+│  ┌──────┴─────────────────┴──────────────────┴───────┐               │
+│  │              Per-Instance OpenClaw Clients          │              │
+│  │     (separate auth, timeout, URL per instance)     │              │
+│  └────────┬──────────────┬──────────────┬────────────┘               │
+└───────────┼──────────────┼──────────────┼────────────────────────────┘
+            │              │              │
+            ▼              ▼              ▼
+   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+   │  🦞 prod     │ │  🦞 staging  │ │  🦞 dev      │
+   │  (default)   │ │              │ │              │
+   │  :18789      │ │  :18789      │ │  :18789      │
+   │  OpenClaw GW │ │  OpenClaw GW │ │  OpenClaw GW │
+   └──────────────┘ └──────────────┘ └──────────────┘
+```
+
+### Setup
+
+```bash
+OPENCLAW_INSTANCES='[
+  {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
+  {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
+  {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
+]'
+```
+
+### Usage
+
+All tools accept an optional `instance` parameter to target a specific gateway:
+
+```
+# Chat with staging instance
+openclaw_chat message="Deploy status?" instance="staging"
+
+# Check health of prod
+openclaw_status instance="prod"
+
+# List all configured instances
+openclaw_instances
+
+# Async task targeting dev
+openclaw_chat_async message="Run tests" instance="dev"
+```
+
+When `instance` is omitted, the default instance is used. Each instance has its own auth token, timeout, and URL — fully isolated.
+
+### Key Features
+
+- **Zero-migration upgrade** — existing single-instance deployments work without any config change
+- **Per-instance isolation** — separate auth tokens, timeouts, and URLs
+- **Dynamic routing** — Claude picks the right instance per request
+- **Task tracking** — async tasks remember which instance they target
+- **Security** — tokens are never exposed via `openclaw_instances`
+
+See [Configuration — Multi-Instance Mode](docs/configuration.md#multi-instance-mode) for the full reference.
+
 ## Documentation
 
 - [Installation](docs/installation.md) — Setup for Claude Desktop & Claude.ai

package/dist/index.js

@@ -5,11 +5,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/config/constants.ts
 var SERVER_NAME = "openclaw-mcp";
-var SERVER_VERSION = "1.3.0";
+var SERVER_VERSION = "1.4.0";
 var DEFAULT_OPENCLAW_URL = "http://127.0.0.1:18789";
+var DEFAULT_MODEL = "openclaw";
 var SERVER_ICON_SVG_BASE64 = "PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjgiIGhlaWdodD0iMTI4IiB2aWV3Qm94PSIwIDAgMTI4IDEyOCIgZmlsbD0ibm9uZSI+PGRlZnM+PGxpbmVhckdyYWRpZW50IGlkPSJiZyIgeDE9IjAlIiB5MT0iMCUiIHgyPSIxMDAlIiB5Mj0iMTAwJSI+PHN0b3Agb2Zmc2V0PSIwJSIgc3RvcC1jb2xvcj0iIzFhMWEyZSIvPjxzdG9wIG9mZnNldD0iMTAwJSIgc3RvcC1jb2xvcj0iIzE2MjEzZSIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJjbGF3IiB4MT0iMCUiIHkxPSIwJSIgeDI9IjEwMCUiIHkyPSIxMDAlIj48c3RvcCBvZmZzZXQ9IjAlIiBzdG9wLWNvbG9yPSIjZmYzMzMzIi8+PHN0b3Agb2Zmc2V0PSIxMDAlIiBzdG9wLWNvbG9yPSIjY2MwMDAwIi8+PC9saW5lYXJHcmFkaWVudD48L2RlZnM+PHJlY3Qgd2lkdGg9IjEyOCIgaGVpZ2h0PSIxMjgiIHJ4PSIyNCIgZmlsbD0idXJsKCNiZykiLz48ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSg2NCA2NCkiIHN0cm9rZT0idXJsKCNjbGF3KSIgc3Ryb2tlLXdpZHRoPSI3IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGZpbGw9Im5vbmUiPjxwYXRoIGQ9Ik0tMjggLTM4YzAgMCAtMTAgMjAgMCAzMiIvPjxwYXRoIGQ9Ik0tMTIgLTQwYzAgMCAtNiAyMiA0IDM0Ii8+PHBhdGggZD0iTTI4IC0zOGMwIDAgMTAgMjAgMCAzMiIvPjxwYXRoIGQ9Ik0xMiAtNDBjMCAwIDYgMjIgLTQgMzQiLz48Y2lyY2xlIGN4PSIwIiBjeT0iMTAiIHI9IjIwIiBzdHJva2Utd2lkdGg9IjYiLz48cGF0aCBkPSJNLTEwIDR2LTQiIHN0cm9rZS13aWR0aD0iNCIvPjxwYXRoIGQ9Ik0xMCA0di00IiBzdHJva2Utd2lkdGg9IjQiLz48cGF0aCBkPSJNLTggMjBjNCA2IDEyIDYgMTYgMCIgc3Ryb2tlLXdpZHRoPSIzIi8+PC9nPjwvc3ZnPg==";
 
 // src/utils/logger.ts
+var debugEnabled = false;
 var SENSITIVE_PATTERNS = [
   /Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
   /api[_-]?key["\s:=]+[A-Za-z0-9\-._~+/]{8,}/gi,
@@ -27,6 +29,19 @@ function sanitizeLogMessage(message) {
 function log(message) {
   console.error(`[openclaw-mcp] ${sanitizeLogMessage(message)}`);
 }
+function setDebugEnabled(enabled) {
+  debugEnabled = enabled;
+}
+function isDebugEnabled() {
+  return debugEnabled;
+}
+function logDebug(messageOrFactory) {
+  if (!debugEnabled) {
+    return;
+  }
+  const message = typeof messageOrFactory === "function" ? messageOrFactory() : messageOrFactory;
+  console.error(`[openclaw-mcp] DEBUG: ${sanitizeLogMessage(message)}`);
+}
 function logError(message, error) {
   console.error(`[openclaw-mcp] ERROR: ${sanitizeLogMessage(message)}`);
   if (error) {
@@ -51,6 +66,11 @@ function parseArguments(version) {
     type: "string",
     description: "Bearer token for OpenClaw gateway authentication",
     default: process.env.OPENCLAW_GATEWAY_TOKEN || void 0
+  }).option("model", {
+    alias: "m",
+    type: "string",
+    description: "Model name for chat completions",
+    default: process.env.OPENCLAW_MODEL || DEFAULT_MODEL
   }).option("transport", {
     alias: "t",
     type: "string",
@@ -70,6 +90,10 @@ function parseArguments(version) {
     type: "number",
     description: "Request timeout in milliseconds",
     default: parseInt(process.env.OPENCLAW_TIMEOUT_MS || "120000", 10)
+  }).option("debug", {
+    type: "boolean",
+    description: "Enable debug logging",
+    default: process.env.DEBUG === "true" || process.env.NODE_ENV === "development"
   }).option("auth", {
     type: "boolean",
     description: "Enable OAuth authentication (SSE mode)",
@@ -90,6 +114,10 @@ function parseArguments(version) {
     type: "string",
     description: "Allowed OAuth redirect URIs (comma-separated)",
     default: process.env.MCP_REDIRECT_URIS || void 0
+  }).option("allow-dcr", {
+    type: "boolean",
+    description: "Allow OAuth Dynamic Client Registration (Cursor/Windsurf compatibility, dev-only)",
+    default: process.env.MCP_DANGEROUSLY_ALLOW_DCR === "true"
   }).help().parseSync();
   let instances;
   const instancesEnv = process.env.OPENCLAW_INSTANCES;
@@ -133,15 +161,18 @@ function parseArguments(version) {
   return {
     openclawUrl: argv["openclaw-url"],
     gatewayToken: argv["gateway-token"],
+    model: argv.model,
     transport: argv.transport,
     port: argv.port,
     host: argv.host,
     timeout: argv.timeout,
+    debug: argv.debug,
     authEnabled: argv.auth,
     clientId: argv["client-id"],
     clientSecret: argv["client-secret"],
     issuerUrl: argv["issuer-url"],
     redirectUris: argv["redirect-uris"] ? argv["redirect-uris"].split(",").map((s) => s.trim()).filter(Boolean) : void 0,
+    allowDcr: argv["allow-dcr"],
     instances
   };
 }
@@ -171,14 +202,17 @@ var OpenClawApiError = class extends OpenClawError {
 // src/openclaw/client.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
 var MAX_RESPONSE_SIZE_BYTES = 10 * 1024 * 1024;
+var MAX_DEBUG_BODY_LENGTH = 4096;
 var OpenClawClient = class {
   baseUrl;
   gatewayToken;
   timeoutMs;
-  constructor(baseUrl, gatewayToken, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  model;
+  constructor(baseUrl, gatewayToken, timeoutMs = DEFAULT_TIMEOUT_MS, model = "openclaw") {
     this.baseUrl = baseUrl.replace(/\/$/, "");
     this.gatewayToken = gatewayToken;
     this.timeoutMs = timeoutMs;
+    this.model = model;
   }
   buildHeaders() {
     const headers = {
@@ -189,8 +223,16 @@ var OpenClawClient = class {
     }
     return headers;
   }
+  truncateForLog(value) {
+    if (value.length <= MAX_DEBUG_BODY_LENGTH) return value;
+    return value.slice(0, MAX_DEBUG_BODY_LENGTH) + `... (truncated, ${value.length} chars total)`;
+  }
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
+    logDebug(() => `Request: ${options.method ?? "GET"} ${url}`);
+    if (options.body) {
+      logDebug(() => `Request body: ${this.truncateForLog(options.body)}`);
+    }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
@@ -203,11 +245,23 @@ var OpenClawClient = class {
         }
       });
       if (!response.ok) {
+        if (isDebugEnabled()) {
+          const contentLength2 = response.headers.get("content-length");
+          if (!contentLength2 || parseInt(contentLength2, 10) <= MAX_RESPONSE_SIZE_BYTES) {
+            const errorBody = await response.text();
+            if (errorBody.length <= MAX_RESPONSE_SIZE_BYTES) {
+              logDebug(
+                () => `Response error (${response.status}): ${this.truncateForLog(errorBody)}`
+              );
+            }
+          }
+        }
         throw new OpenClawApiError(
           `API request failed: ${response.status} ${response.statusText}`,
           response.status
         );
       }
+      logDebug(() => `Response: ${response.status} ${response.statusText}`);
       const contentLength = response.headers.get("content-length");
       if (contentLength && parseInt(contentLength, 10) > MAX_RESPONSE_SIZE_BYTES) {
         throw new OpenClawApiError("Response exceeds maximum allowed size (10MB)", 413);
@@ -276,7 +330,7 @@ var OpenClawClient = class {
    */
   async chat(message, sessionId) {
     const body = {
-      model: "claude-opus-4-5",
+      model: this.model,
       messages: [{ role: "user", content: message }],
       max_tokens: 4096
     };
@@ -306,7 +360,7 @@ var INSTANCE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 var InstanceRegistry = class {
   instances = /* @__PURE__ */ new Map();
   defaultName;
-  constructor(configs) {
+  constructor(configs, model) {
     if (configs.length === 0) {
       throw new Error("At least one OpenClaw instance must be configured");
     }
@@ -343,7 +397,7 @@ var InstanceRegistry = class {
         }
         explicitDefault = config.name;
       }
-      const client = new OpenClawClient(config.url, config.token, config.timeout);
+      const client = new OpenClawClient(config.url, config.token, config.timeout, model);
       this.instances.set(config.name, { config, client });
     }
     this.defaultName = explicitDefault ?? configs[0].name;
@@ -1123,8 +1177,15 @@ var ALLOW_ANY_REDIRECT = new Proxy([], {
     return Reflect.get(target, prop);
   }
 });
+var MAX_DYNAMIC_CLIENTS = 100;
 var OpenClawClientsStore = class {
   client;
+  dynamicClients = /* @__PURE__ */ new Map();
+  // Assigned conditionally in the constructor. The MCP SDK probes
+  // `clientsStore.registerClient` at router-setup time and only advertises
+  // `/register` when the property is defined, so we must NOT define a no-op
+  // method on the prototype — it has to be instance-level and gated on config.
+  registerClient;
   constructor(config) {
     if (config.clientId && config.clientSecret) {
       const redirectUris = config.redirectUris && config.redirectUris.length > 0 ? config.redirectUris : ALLOW_ANY_REDIRECT;
@@ -1139,16 +1200,25 @@ var OpenClawClientsStore = class {
         client_id_issued_at: Math.floor(Date.now() / 1e3)
       };
     }
+    if (config.allowDynamicRegistration) {
+      this.registerClient = (client) => {
+        if (this.dynamicClients.size >= MAX_DYNAMIC_CLIENTS) {
+          const oldestKey = this.dynamicClients.keys().next().value;
+          if (oldestKey !== void 0) {
+            this.dynamicClients.delete(oldestKey);
+          }
+        }
+        this.dynamicClients.set(client.client_id, client);
+        return client;
+      };
+    }
   }
   async getClient(clientId) {
     if (this.client && this.client.client_id === clientId) {
       return this.client;
     }
-    return void 0;
+    return this.dynamicClients.get(clientId);
   }
-  // No registerClient — dynamic client registration is intentionally disabled.
-  // Only the pre-configured client from MCP_CLIENT_ID + MCP_CLIENT_SECRET can authenticate.
-  // This prevents anyone who knows the server URL from self-registering and bypassing auth.
 };
 var OpenClawAuthProvider = class {
   clientsStore;
@@ -1287,9 +1357,15 @@ var OpenClawAuthProvider = class {
       resource: tokenData.resource
     };
   }
-  async revokeToken(_client, request) {
-    this.tokens.delete(request.token);
-    this.refreshTokens.delete(request.token);
+  async revokeToken(client, request) {
+    const tokenData = this.tokens.get(request.token);
+    if (tokenData && tokenData.clientId === client.client_id) {
+      this.tokens.delete(request.token);
+    }
+    const refreshData = this.refreshTokens.get(request.token);
+    if (refreshData && refreshData.clientId === client.client_id) {
+      this.refreshTokens.delete(request.token);
+    }
   }
 };
 
@@ -1530,7 +1606,14 @@ async function createSSEServer(config, deps2) {
 
 // src/index.ts
 var args = parseArguments(SERVER_VERSION);
-var registry = new InstanceRegistry(args.instances);
+setDebugEnabled(args.debug);
+var trimmedModel = args.model.trim();
+if (!trimmedModel) {
+  logError('OPENCLAW_MODEL / --model must be a non-empty string. Default is "openclaw".');
+  process.exit(1);
+}
+args.model = trimmedModel;
+var registry = new InstanceRegistry(args.instances, args.model);
 var deps = {
   registry,
   serverName: SERVER_NAME,
@@ -1538,8 +1621,12 @@ var deps = {
 };
 async function main() {
   log(`Starting ${SERVER_NAME} v${SERVER_VERSION}`);
+  log(`Model: ${args.model}`);
   log(`Transport: ${args.transport}`);
   log(`Request timeout: ${args.timeout}ms`);
+  if (args.debug) {
+    log("Debug logging: enabled");
+  }
   for (const instance of registry.list()) {
     const defaultLabel = instance.isDefault ? " (default)" : "";
     log(`Instance "${instance.name}": ${instance.url}${defaultLabel}`);
@@ -1567,7 +1654,8 @@ async function main() {
       sseConfig.authConfig = {
         clientId: args.clientId,
         clientSecret: args.clientSecret,
-        redirectUris: args.redirectUris
+        redirectUris: args.redirectUris,
+        allowDynamicRegistration: args.allowDcr
       };
       log(`OAuth client ID: ${args.clientId}`);
       if (!args.redirectUris || args.redirectUris.length === 0) {
@@ -1575,6 +1663,24 @@ async function main() {
           "WARNING: MCP_REDIRECT_URIS not set \u2014 any redirect_uri will be accepted. Set MCP_REDIRECT_URIS for production."
         );
       }
+      if (args.allowDcr) {
+        const isLoopback = args.host === "127.0.0.1" || args.host === "localhost" || args.host === "::1";
+        const publicOptIn = process.env.MCP_DANGEROUSLY_ALLOW_DCR_PUBLIC === "true";
+        if (!isLoopback && !publicOptIn) {
+          logError(
+            `MCP_DANGEROUSLY_ALLOW_DCR=true is set but HOST="${args.host}" is not loopback. Dynamic Client Registration combined with a publicly reachable bind allows anyone on the network to obtain a token. Bind to 127.0.0.1, or set MCP_DANGEROUSLY_ALLOW_DCR_PUBLIC=true to override. Refusing to start.`
+          );
+          process.exit(1);
+        }
+        log(
+          "WARNING: MCP_DANGEROUSLY_ALLOW_DCR is enabled \u2014 OAuth Dynamic Client Registration is open. Any client that can reach this server may self-register and obtain tokens. Use for local development only."
+        );
+        if (publicOptIn) {
+          log(
+            "WARNING: MCP_DANGEROUSLY_ALLOW_DCR_PUBLIC=true \u2014 DCR is exposed on a non-loopback bind. You have explicitly accepted the risk."
+          );
+        }
+      }
     } else if (args.authEnabled && !args.clientId) {
       logError("AUTH_ENABLED=true but MCP_CLIENT_ID is not set. Refusing to start without auth.");
       process.exit(1);

package/docs/configuration.md

@@ -11,11 +11,27 @@ All configuration can be done via environment variables. Copy `.env.example` to
 | `OPENCLAW_URL`           | OpenClaw gateway URL                    | `http://127.0.0.1:18789` |
 | `OPENCLAW_GATEWAY_TOKEN` | Bearer token for gateway authentication | (none)                   |
 | `OPENCLAW_TIMEOUT_MS`    | Request timeout in milliseconds         | `120000` (2 min)         |
+| `OPENCLAW_MODEL`         | Model name for chat completions         | `openclaw`               |
 
 ### Multi-Instance Mode
 
 Orchestrate multiple OpenClaw gateways from a single MCP server. Set `OPENCLAW_INSTANCES` as a JSON array — when present, it takes precedence over `OPENCLAW_URL` / `OPENCLAW_GATEWAY_TOKEN`.
 
+```
+                         ┌─────────────────┐
+                         │  Claude Client   │
+                         └────────┬────────┘
+                                  │
+                    ┌─────────────▼─────────────┐
+                    │   OpenClaw MCP Bridge      │
+                    │                            │
+                    │   instance="prod"  ──────────────► OpenClaw GW (prod)
+                    │   instance="staging" ────────────► OpenClaw GW (staging)
+                    │   instance="dev"  ───────────────► OpenClaw GW (dev)
+                    │   (no instance)   ──► default ──► OpenClaw GW (prod)
+                    └────────────────────────────┘
+```
+
 | Variable             | Description                    | Default                       |
 | -------------------- | ------------------------------ | ----------------------------- |
 | `OPENCLAW_INSTANCES` | JSON array of instance configs | (none — single-instance mode) |
@@ -45,11 +61,44 @@ Each instance object supports:
 All gateway-facing tools (`openclaw_chat`, `openclaw_status`, `openclaw_chat_async`) accept an optional `instance` parameter. When omitted, the default instance is used.
 
 ```
+# Target a specific instance
 openclaw_chat message="Hello" instance="staging"
-openclaw_instances  # list all available instances
+
+# Check health of a specific gateway
+openclaw_status instance="prod"
+
+# List all available instances (names, URLs, default — tokens are never exposed)
+openclaw_instances
+
+# Async tasks also support instance targeting
+openclaw_chat_async message="Run migration" instance="dev"
+
+# Filter task list by instance
+openclaw_task_list instance="staging"
+```
+
+**How instance resolution works:**
+
+1. If `instance` parameter is provided → use that instance
+2. If `instance` is omitted → use the instance marked as `default`
+3. If no instance is marked as default → the first instance in the array is used
+
+Each instance gets its own isolated HTTP client with independent auth token, timeout, and base URL. Async tasks store the target instance ID so results are always routed correctly.
+
+**Docker Compose with multi-instance:**
+
+```yaml
+services:
+  mcp-bridge:
+    image: ghcr.io/freema/openclaw-mcp:latest
+    environment:
+      - OPENCLAW_INSTANCES=[{"name":"prod","url":"http://prod-gw:18789","token":"tok1","default":true},{"name":"staging","url":"http://staging-gw:18789","token":"tok2"}]
+      - AUTH_ENABLED=true
+      - MCP_CLIENT_ID=openclaw
+      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
 ```
 
-**Backward compatibility:** When `OPENCLAW_INSTANCES` is not set, the server creates a single `"default"` instance from `OPENCLAW_URL` + `OPENCLAW_GATEWAY_TOKEN`. Existing deployments work without any configuration change.
+**Backward compatibility:** When `OPENCLAW_INSTANCES` is not set, the server creates a single `"default"` instance from `OPENCLAW_URL` + `OPENCLAW_GATEWAY_TOKEN`. Existing deployments work without any configuration change — zero migration required.
 
 ### Server Settings (SSE transport)
 
@@ -84,10 +133,12 @@ The server uses the MCP SDK's built-in OAuth 2.1 server with authorization code
 | `MCP_CLIENT_SECRET` | OAuth client secret                                         | When auth enabled          |
 | `MCP_ISSUER_URL`    | OAuth issuer URL override (e.g., `https://mcp.example.com`) | When behind HTTPS proxy    |
 | `MCP_REDIRECT_URIS` | Allowed redirect URIs (comma-separated)                     | Recommended for production |
+| `MCP_DANGEROUSLY_ALLOW_DCR`        | Enable Dynamic Client Registration (`true`/`false`)         | Dev only (see below)       |
+| `MCP_DANGEROUSLY_ALLOW_DCR_PUBLIC` | Escape hatch to allow DCR on non-loopback binds             | Never, unless you mean it  |
 
 **Client ID validation rules:**
 
-- 3–64 characters
+- 3-64 characters
 - Alphanumeric, dashes, underscores only
 - Must start with a letter or digit
 
@@ -104,4 +155,14 @@ When auth is enabled, the server exposes these OAuth 2.1 endpoints:
 - `POST /token` — Token exchange (requires client_secret)
 - `POST /revoke` — Token revocation
 
-Dynamic client registration is **disabled** — only the pre-configured client (from `MCP_CLIENT_ID` + `MCP_CLIENT_SECRET`) can authenticate. This prevents anyone who knows the server URL from self-registering and bypassing auth.
+Dynamic client registration is **disabled by default** — only the pre-configured client (from `MCP_CLIENT_ID` + `MCP_CLIENT_SECRET`) can authenticate. This prevents anyone who knows the server URL from self-registering and bypassing auth.
+
+#### Cursor / Windsurf compatibility (dev only)
+
+Cursor and Windsurf only support MCP servers that expose OAuth 2.0 Dynamic Client Registration (RFC 7591). To let them connect, set `MCP_DANGEROUSLY_ALLOW_DCR=true`. The server will then advertise a `/register` endpoint and accept ad-hoc client registrations (kept in an in-memory FIFO store, capped at 100 entries).
+
+`MCP_CLIENT_ID` and `MCP_CLIENT_SECRET` are still required — DCR augments the pre-configured client, it does not replace it. If you are only running Cursor locally you can use any valid values for them; they simply remain unused.
+
+**This is dev-only.** With DCR enabled alongside the server's auto-approve authorization flow, any client that can reach the server can register itself and obtain a token. To prevent accidental exposure the server refuses to start when `MCP_DANGEROUSLY_ALLOW_DCR=true` and `HOST` is not loopback (`127.0.0.1`, `localhost`, or `::1`). If you genuinely need DCR on a non-loopback bind (e.g., inside a trusted private network), also set `MCP_DANGEROUSLY_ALLOW_DCR_PUBLIC=true`.
+
+For production with Claude.ai, keep DCR disabled and use the pre-configured `MCP_CLIENT_ID` / `MCP_CLIENT_SECRET`.

package/docs/deployment.md

@@ -17,6 +17,8 @@ services:
     environment:
       - OPENCLAW_URL=${OPENCLAW_URL:-http://host.docker.internal:18789}
       - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN:-}
+      - OPENCLAW_MODEL=${OPENCLAW_MODEL:-openclaw}
+      - DEBUG=${DEBUG:-false}
       - AUTH_ENABLED=${AUTH_ENABLED:-true}
       - MCP_CLIENT_ID=${MCP_CLIENT_ID:-openclaw}
       - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET:-}
@@ -169,8 +171,24 @@ The MCP bridge communicates with the OpenClaw gateway via its OpenAI-compatible
 
 Without this, the MCP bridge will receive `405 Method Not Allowed` from the gateway.
 
+## Bridge / Gateway Compatibility
+
+| MCP Bridge | Gateway | Result |
+|------------|---------|--------|
+| ≤ 1.2.2 | ≥ 2026.3.24 | `400 Bad Request` — bridge sends `model: "claude-opus-4-5"`, gateway rejects it |
+| ≥ 1.3.0 | ≥ 2026.3.24 | Works — bridge defaults to `model: "openclaw"` |
+| ≥ 1.3.0 | older | Works — set `OPENCLAW_MODEL` to whatever the older gateway expects |
+
+If you're running a non-standard gateway setup with custom agent routing, set `OPENCLAW_MODEL=openclaw/<agentId>` to match your configuration.
+
 ## Troubleshooting
 
+### `400 Bad Request` from gateway on `openclaw_chat`
+
+Gateway versions 2026.3.24+ require `model: "openclaw"` (or `"openclaw/<agentId>"`). The MCP bridge defaults to `"openclaw"` since v1.3.0. If you're using an older bridge version, upgrade or set `OPENCLAW_MODEL=openclaw`. If you need custom model routing, set `OPENCLAW_MODEL` to the value your gateway expects.
+
+To diagnose, enable debug logging (`DEBUG=true`) which logs the outgoing request body and gateway error responses.
+
 ### `405 Method Not Allowed` from gateway
 
 The OpenClaw gateway's HTTP chat completions endpoint is disabled by default. Enable it in `openclaw.json` — see [Gateway Prerequisites](#openclaw-gateway-prerequisites) above.

package/docs/index.html

@@ -129,6 +129,7 @@ pre, code { font-family: 'JetBrains Mono', monospace; }
   display: none; gap: 2rem; font-size: 0.875rem;
   text-transform: uppercase; letter-spacing: 0.05em; font-weight: 500; color: var(--text);
 }
+.hamburger { display: none; }
 .nav-links a:hover { color: var(--accent); transition: color 0.2s; }
 .nav-gh { display: flex; align-items: center; gap: 0; font-size: 0.75rem; font-weight: 700; }
 .nav-gh-btn {
@@ -288,8 +289,106 @@ pre, code { font-family: 'JetBrains Mono', monospace; }
   text-align: center; font-size: 10px; color: rgba(160,160,160,0.5);
 }
 
-/* === Desktop (640px+) === */
-@media (min-width: 640px) {
+/* === Mobile Hamburger Menu === */
+.hamburger {
+  display: flex; flex-direction: column; gap: 5px; padding: 0.5rem;
+  cursor: pointer; z-index: 60; background: none; border: none;
+}
+.hamburger span {
+  display: block; width: 22px; height: 2px; background: #fff;
+  transition: transform 0.3s, opacity 0.3s;
+}
+.hamburger.active span:nth-child(1) { transform: rotate(45deg) translate(5px, 5px); }
+.hamburger.active span:nth-child(2) { opacity: 0; }
+.hamburger.active span:nth-child(3) { transform: rotate(-45deg) translate(5px, -5px); }
+
+.mobile-menu {
+  display: none; position: fixed; inset: 0; z-index: 55;
+  background: rgba(8,8,8,0.97); backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+  flex-direction: column; align-items: center; justify-content: center; gap: 2rem;
+  font-size: 1.25rem; text-transform: uppercase; letter-spacing: 0.05em; font-weight: 700;
+}
+.mobile-menu.active { display: flex; }
+.mobile-menu a { color: var(--text); transition: color 0.2s; padding: 0.5rem 1rem; }
+.mobile-menu a:hover, .mobile-menu a:active { color: var(--accent); }
+
+/* === Mobile-first fixes === */
+@media (max-width: 639px) {
+  .hamburger { display: flex; }
+  .nav-gh { display: none; }
+
+  .hero { padding: 7rem 0 3rem; }
+  .hero h1 { font-size: 2.25rem; }
+  .hero-sub { font-size: 1rem; margin-top: 1.25rem; }
+  .hero-buttons { margin-top: 2rem; gap: 0.75rem; }
+  .btn-primary, .btn-secondary { padding: 0.875rem 1.5rem; font-size: 1rem; }
+  .stats-bar { margin-top: 2.5rem; gap: 1rem; font-size: 0.75rem; }
+
+  .how-section, .features-section, .tools-section, .quickstart-section, .cta-section {
+    padding: 4rem 0;
+  }
+  .how-section h2, .features-section h2, .tools-section h2,
+  .quickstart-section h2, .cta-section h2 {
+    font-size: 1.75rem; margin-bottom: 2rem;
+  }
+
+  .how-step { padding: 1.5rem; }
+  .how-step-num { font-size: 1.5rem; }
+  .how-step h3 { font-size: 1.1rem; }
+
+  .features-grid { gap: 1rem; }
+  .feature-card { padding: 1.5rem; }
+  .feature-card h3 { font-size: 1.1rem; }
+
+  .tools-table { font-size: 0.75rem; }
+  .tools-table th, .tools-table td { padding: 0.75rem 0.5rem; }
+  .tools-col-header h3 { font-size: 1.25rem; }
+
+  .tab-btn { padding: 0.75rem 1rem; font-size: 0.65rem; }
+  .tab-content { padding: 1rem; }
+  .tab-content pre code { font-size: 0.7rem; word-break: break-all; white-space: pre-wrap; }
+
+  .cta-btn-primary, .cta-btn-secondary {
+    padding: 1rem 2rem; font-size: 1rem; width: 100%; text-align: center;
+  }
+
+  .footer { padding: 2.5rem 0; }
+  .footer-links { gap: 1.25rem; }
+  .footer-bottom { margin-top: 2rem; }
+
+  .plugin-cards { gap: 0.75rem !important; }
+
+  /* Prevent horizontal overflow */
+  .terminal-body { font-size: 0.75rem; padding: 1rem; }
+  .container { padding: 0 1rem; }
+}
+
+/* === Tablet (640px - 1023px) === */
+@media (min-width: 640px) and (max-width: 1023px) {
+  .hamburger { display: flex; }
+  .nav-links { display: none; }
+  .hero h1 { font-size: 4rem; }
+  .hero-sub { font-size: 1.25rem; }
+  .hero-buttons { flex-direction: row; }
+  .btn-primary, .btn-secondary { width: auto; }
+  .how-grid { grid-template-columns: repeat(2, 1fr); }
+  .how-step:nth-child(2) { border-right: none; }
+  .features-grid { grid-template-columns: repeat(2, 1fr); }
+  .tools-grid { grid-template-columns: repeat(2, 1fr); }
+  .cta-section h2 { font-size: 2.5rem; }
+  .cta-buttons { flex-direction: row; }
+  .footer-inner { flex-direction: row; justify-content: space-between; align-items: center; }
+  .plugin-cards { grid-template-columns: repeat(2, 1fr) !important; }
+
+  .how-section, .features-section, .tools-section, .quickstart-section, .cta-section {
+    padding: 5rem 0;
+  }
+}
+
+/* === Desktop (1024px+) === */
+@media (min-width: 1024px) {
+  .hamburger { display: none; }
   .nav-links { display: flex; }
   .hero h1 { font-size: 6rem; }
   .hero-sub { font-size: 1.5rem; }
@@ -322,6 +421,9 @@ pre, code { font-family: 'JetBrains Mono', monospace; }
       <a href="#quickstart">Quick start</a>
       <a href="#plugin">Plugin</a>
     </div>
+    <button class="hamburger" aria-label="Menu" onclick="document.querySelector('.mobile-menu').classList.toggle('active');this.classList.toggle('active')">
+      <span></span><span></span><span></span>
+    </button>
     <div class="nav-gh">
       <a class="nav-gh-btn" href="https://github.com/freema/openclaw-mcp" target="_blank" rel="noopener">
         <svg viewBox="0 0 16 16" width="16" height="16" fill="white"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>
@@ -339,6 +441,16 @@ pre, code { font-family: 'JetBrains Mono', monospace; }
   </div>
 </nav>
 
+<!-- Mobile Menu Overlay -->
+<div class="mobile-menu" id="mobile-menu">
+  <a href="#how" onclick="closeMobileMenu()">How it works</a>
+  <a href="#features" onclick="closeMobileMenu()">Features</a>
+  <a href="#tools" onclick="closeMobileMenu()">Tools</a>
+  <a href="#quickstart" onclick="closeMobileMenu()">Quick start</a>
+  <a href="#plugin" onclick="closeMobileMenu()">Plugin</a>
+  <a href="https://github.com/freema/openclaw-mcp" target="_blank" rel="noopener" style="color:var(--accent)">GitHub</a>
+</div>
+
 <!-- Hero -->
 <header class="hero">
   <div class="container">
@@ -610,6 +722,14 @@ npx openclaw-mcp --transport sse --port 3000</code></pre>
   </div>
 </footer>
 
+<!-- Mobile Menu Script -->
+<script>
+function closeMobileMenu() {
+  document.querySelector('.mobile-menu').classList.remove('active');
+  document.querySelector('.hamburger').classList.remove('active');
+}
+</script>
+
 <!-- Tab Switching Script -->
 <script>
 (function() {

package/docs/installation.md

@@ -91,9 +91,11 @@ openclaw-mcp --help
 Options:
   --openclaw-url, -u  OpenClaw gateway URL     [default: "http://127.0.0.1:18789"]
   --gateway-token     Bearer token for gateway [default: none]
+  --model, -m         Model name for chat      [default: "openclaw"]
   --transport, -t     Transport mode           [choices: "stdio", "sse"] [default: "stdio"]
   --port, -p          Port for SSE server      [default: 3000]
   --host              Host for SSE server      [default: "0.0.0.0"]
+  --debug             Enable debug logging     [default: false]
   --auth              Enable OAuth             [default: false]
   --client-id         MCP OAuth client ID      [env: MCP_CLIENT_ID]
   --client-secret     MCP OAuth client secret  [env: MCP_CLIENT_SECRET]

package/docs/logging.md

@@ -36,13 +36,24 @@ The MCP server logs operational events to **stderr** using the `[openclaw-mcp]`
 - Invalid client configuration (missing secrets, bad client ID format)
 - Session errors
 
-### What Is NOT Logged
+### What Is NOT Logged (Info/Error levels)
 
 - **Message content** — user messages and OpenClaw responses are never logged
 - **Authentication tokens** — Bearer tokens, client secrets, gateway tokens
 - **Request/response bodies** — only error messages, not full payloads
 - **User-identifiable information** — no IPs, user agents, or personal data
 
+### Debug Level (`DEBUG=true`)
+
+> **Warning:** Debug mode is a diagnostic tool. It logs request and response payloads which may contain user message content. Do not enable in production under normal operation — use it only for active troubleshooting, then disable it.
+
+When debug logging is enabled, the following **are** logged for troubleshooting:
+
+- **Request bodies** — outgoing payloads sent to the gateway (truncated to 4096 chars)
+- **Error response bodies** — full error responses from the gateway (truncated to 4096 chars)
+
+Credentials are still redacted by the sanitization layer. Headers (including Authorization) are never logged, even in debug mode.
+
 ## Sensitive Data Redaction
 
 The logger automatically redacts patterns that look like credentials:
@@ -99,4 +110,4 @@ DEBUG=true        # Explicit debug flag
 NODE_ENV=development  # Development mode
 ```
 
-Debug logs include additional operational detail but still never log message content or credentials.
+Debug logs include request/response bodies for troubleshooting (truncated to 4096 chars). Credentials are still redacted, and headers (including Authorization) are never logged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Model Context Protocol (MCP) server for OpenClaw AI assistant integration",
   "author": "Tomáš Grasl <https://www.tomasgrasl.cz/>",
   "license": "MIT",
@@ -14,7 +14,7 @@
     "dev": "tsx watch src/index.ts",
     "build": "tsup",
     "start": "node dist/index.js",
-    "clean": "rm -rf dist",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext .ts",
     "lint:fix": "eslint src --ext .ts --fix",