openclaw-mcp 1.5.0 → 1.7.0

package/README.md

@@ -54,6 +54,7 @@ services:
       - MCP_CLIENT_ID=openclaw
       - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
       - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
+      - MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
       - TRUST_PROXY=1
       - CORS_ORIGINS=https://claude.ai
     extra_hosts:
@@ -115,6 +116,8 @@ AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
 > - `MCP_ISSUER_URL` (or `--issuer-url`) to your public HTTPS URL — otherwise OAuth metadata advertises `http://localhost:3000` and clients fail to authenticate.
 > - `TRUST_PROXY=1` (or `--trust-proxy 1`) — otherwise `express-rate-limit` rejects the proxy's `X-Forwarded-For` header and `/token` crashes with `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`.
 
+> **Recommended:** Set `MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback` so authorization codes can only be delivered to Claude's callbacks. Note the exact `/api/mcp/auth_callback` path — matching is exact, and getting it wrong fails OAuth with `Unregistered redirect_uri` (see [Troubleshooting](docs/deployment.md#invalid_request--unregistered-redirect_uri-on-authorize)).
+
 See [Installation Guide](docs/installation.md) for details.
 
 ## Architecture
@@ -158,9 +161,15 @@ See [Installation Guide](docs/installation.md) for details.
 |------|-------------|
 | `openclaw_chat_async` | Queue a message, get task_id immediately |
 | `openclaw_task_status` | Check task progress and get results |
-| `openclaw_task_list` | List all tasks with filtering |
+| `openclaw_task_list` | List your tasks with filtering |
 | `openclaw_task_cancel` | Cancel a pending task |
 
+Tasks are scoped to the MCP connection that created them. In HTTP mode, where
+one process serves many clients, a client can only see and cancel its own
+tasks — another client's `task_id` reads as "not found" even if it is known.
+Reconnecting starts a fresh scope, so poll a task on the connection that
+queued it.
+
 ## 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).
@@ -258,7 +267,8 @@ AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
   openclaw-mcp --transport http
 ```
 
-Configure CORS to restrict access:
+CORS is disabled unless you opt in. Set `CORS_ORIGINS` only when a browser
+client needs to reach the server directly:
 
 ```bash
 CORS_ORIGINS=https://claude.ai,https://your-app.com
@@ -266,6 +276,19 @@ CORS_ORIGINS=https://claude.ai,https://your-app.com
 
 See [Configuration](docs/configuration.md) for all security options.
 
+### Upgrading to 1.7.0
+
+Two defaults changed for security. Both only affect HTTP mode; stdio is
+unchanged.
+
+- **CORS is now off by default.** Previously an unset `CORS_ORIGINS` sent
+  `Access-Control-Allow-Origin: *`. If a browser client depends on that, set
+  the origins explicitly (`CORS_ORIGINS=https://your-app.com`), or
+  `CORS_ORIGINS=*` to restore the old behaviour.
+- **Async tasks are scoped to the connection that created them.** A client
+  that used to poll a `task_id` queued by a different connection will now get
+  "not found".
+
 ## Migrating from SSE to HTTP transport
 
 Starting with v1.5.0, the primary transport is **Streamable HTTP** (`--transport http`). The legacy SSE transport (`--transport sse`) is deprecated but still works for backward compatibility.

package/dist/index.js

@@ -5,7 +5,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/config/constants.ts
 var SERVER_NAME = "openclaw-mcp";
-var SERVER_VERSION = "1.5.0";
+var SERVER_VERSION = "1.7.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==";
@@ -475,6 +475,7 @@ var InstanceRegistry = class {
 };
 
 // src/server/tools-registration.ts
+import { randomUUID as randomUUID2 } from "crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
@@ -641,12 +642,12 @@ async function handleOpenclawInstances(registry2, _input) {
 }
 
 // src/mcp/tasks/manager.ts
+import { randomUUID } from "crypto";
 var MAX_TASKS = 1e3;
 var CLEANUP_INTERVAL_MS = 10 * 60 * 1e3;
 var CLEANUP_MAX_AGE_MS = 60 * 60 * 1e3;
 var TaskManager = class {
   tasks = /* @__PURE__ */ new Map();
-  taskCounter = 0;
   cleanupInterval;
   constructor() {
     this.cleanupInterval = setInterval(() => this.cleanup(CLEANUP_MAX_AGE_MS), CLEANUP_INTERVAL_MS);
@@ -655,16 +656,17 @@ var TaskManager = class {
     }
   }
   /**
-   * Generate unique task ID
+   * Generate an unguessable task ID.
+   *
+   * Deliberately not sequential: a predictable counter would let a caller
+   * enumerate IDs and probe for tasks it does not own. Ownership checks are
+   * the real defence, this just removes the oracle.
    */
   generateId() {
-    this.taskCounter++;
-    const timestamp = Date.now().toString(36);
-    const counter = this.taskCounter.toString(36).padStart(4, "0");
-    return `task_${timestamp}_${counter}`;
+    return `task_${randomUUID()}`;
   }
   /**
-   * Create a new task
+   * Create a new task owned by `options.ownerId`.
    */
   create(options) {
     if (this.tasks.size >= MAX_TASKS) {
@@ -679,6 +681,7 @@ var TaskManager = class {
       status: "pending",
       input: options.input,
       createdAt: /* @__PURE__ */ new Date(),
+      ownerId: options.ownerId,
       sessionId: options.sessionId,
       instanceId: options.instanceId,
       priority: options.priority ?? 0
@@ -688,16 +691,21 @@ var TaskManager = class {
     return task;
   }
   /**
-   * Get task by ID
+   * Get a task by ID, but only if `ownerId` owns it.
+   *
+   * Returns undefined both for unknown IDs and for tasks owned by someone
+   * else, so callers cannot distinguish the two.
    */
-  get(id) {
-    return this.tasks.get(id);
+  get(id, ownerId) {
+    const task = this.tasks.get(id);
+    if (!task || task.ownerId !== ownerId) return void 0;
+    return task;
   }
   /**
-   * List all tasks, optionally filtered by status
+   * List the tasks owned by `ownerId`, optionally filtered further.
    */
-  list(filter) {
-    let tasks = Array.from(this.tasks.values());
+  list(ownerId, filter) {
+    let tasks = Array.from(this.tasks.values()).filter((t) => t.ownerId === ownerId);
     if (filter?.status) {
       tasks = tasks.filter((t) => t.status === filter.status);
     }
@@ -713,7 +721,10 @@ var TaskManager = class {
     });
   }
   /**
-   * Update task status
+   * Update task status.
+   *
+   * Internal worker path only — never reachable from a tool handler, so it
+   * takes no ownerId.
    */
   updateStatus(id, status, result, error) {
     const task = this.tasks.get(id);
@@ -731,10 +742,10 @@ var TaskManager = class {
     return true;
   }
   /**
-   * Cancel a pending task
+   * Cancel a pending task owned by `ownerId`.
    */
-  cancel(id) {
-    const task = this.tasks.get(id);
+  cancel(id, ownerId) {
+    const task = this.get(id, ownerId);
     if (!task) return false;
     if (task.status !== "pending") {
       return false;
@@ -745,16 +756,22 @@ var TaskManager = class {
     return true;
   }
   /**
-   * Delete a task (cleanup)
+   * Delete a task (cleanup). Internal only.
    */
   delete(id) {
     return this.tasks.delete(id);
   }
   /**
-   * Get next pending task (for workers)
+   * Get next pending task across all owners (for the background worker).
+   *
+   * Internal only — the worker has to see every queue, which is exactly why
+   * tool handlers must go through the owner-scoped methods instead.
    */
   getNextPending() {
-    const pending = this.list({ status: "pending" });
+    const pending = Array.from(this.tasks.values()).filter((t) => t.status === "pending").sort((a, b) => {
+      if (b.priority !== a.priority) return b.priority - a.priority;
+      return a.createdAt.getTime() - b.createdAt.getTime();
+    });
     return pending[0];
   }
   /**
@@ -775,9 +792,12 @@ var TaskManager = class {
     return cleaned;
   }
   /**
-   * Get statistics
+   * Get statistics for the tasks owned by `ownerId`.
+   *
+   * Scoped like everything else: a global total would leak how busy other
+   * connections are.
    */
-  stats() {
+  stats(ownerId) {
     const byStatus = {
       pending: 0,
       running: 0,
@@ -785,13 +805,13 @@ var TaskManager = class {
       failed: 0,
       cancelled: 0
     };
+    let total = 0;
     for (const task of this.tasks.values()) {
+      if (task.ownerId !== ownerId) continue;
       byStatus[task.status]++;
+      total++;
     }
-    return {
-      total: this.tasks.size,
-      byStatus
-    };
+    return { total, byStatus };
   }
 };
 var taskManager = new TaskManager();
@@ -915,7 +935,7 @@ function startTaskProcessor(registry2) {
   });
   log("Task processor started");
 }
-async function handleOpenclawChatAsync(registry2, input) {
+async function handleOpenclawChatAsync(registry2, input, ownerId) {
   if (!validateInputIsObject(input)) {
     return errorResponse("Invalid input: expected an object");
   }
@@ -957,6 +977,7 @@ async function handleOpenclawChatAsync(registry2, input) {
   const task = taskManager.create({
     type: "chat",
     input: { message: msgResult.value, session_id: sessionId },
+    ownerId,
     sessionId,
     priority,
     instanceId
@@ -974,7 +995,7 @@ async function handleOpenclawChatAsync(registry2, input) {
     )
   );
 }
-async function handleOpenclawTaskStatus(_registry, input) {
+async function handleOpenclawTaskStatus(_registry, input, ownerId) {
   if (!validateInputIsObject(input)) {
     return errorResponse("Invalid input: expected an object");
   }
@@ -983,7 +1004,7 @@ async function handleOpenclawTaskStatus(_registry, input) {
     return errorResponse(tidResult.error);
   }
   const task_id = tidResult.value;
-  const task = taskManager.get(task_id);
+  const task = taskManager.get(task_id, ownerId);
   if (!task) {
     return errorResponse(`Task not found: ${task_id}`);
   }
@@ -1015,7 +1036,7 @@ var VALID_TASK_STATUSES = [
   "failed",
   "cancelled"
 ];
-async function handleOpenclawTaskList(_registry, input) {
+async function handleOpenclawTaskList(_registry, input, ownerId) {
   if (!validateInputIsObject(input)) {
     return errorResponse("Invalid input: expected an object");
   }
@@ -1042,8 +1063,12 @@ async function handleOpenclawTaskList(_registry, input) {
     }
     instanceFilter = instResult.value;
   }
-  const tasks = taskManager.list({ status, sessionId: session_id, instanceId: instanceFilter });
-  const stats = taskManager.stats();
+  const tasks = taskManager.list(ownerId, {
+    status,
+    sessionId: session_id,
+    instanceId: instanceFilter
+  });
+  const stats = taskManager.stats(ownerId);
   const taskList = tasks.map((t) => ({
     task_id: t.id,
     type: t.type,
@@ -1064,7 +1089,7 @@ async function handleOpenclawTaskList(_registry, input) {
     )
   );
 }
-async function handleOpenclawTaskCancel(_registry, input) {
+async function handleOpenclawTaskCancel(_registry, input, ownerId) {
   if (!validateInputIsObject(input)) {
     return errorResponse("Invalid input: expected an object");
   }
@@ -1073,7 +1098,7 @@ async function handleOpenclawTaskCancel(_registry, input) {
     return errorResponse(tidResult.error);
   }
   const task_id = tidResult.value;
-  const task = taskManager.get(task_id);
+  const task = taskManager.get(task_id, ownerId);
   if (!task) {
     return errorResponse(`Task not found: ${task_id}`);
   }
@@ -1082,7 +1107,7 @@ async function handleOpenclawTaskCancel(_registry, input) {
       `Cannot cancel task with status: ${task.status}. Only pending tasks can be cancelled.`
     );
   }
-  const cancelled = taskManager.cancel(task_id);
+  const cancelled = taskManager.cancel(task_id, ownerId);
   if (!cancelled) {
     return errorResponse("Failed to cancel task");
   }
@@ -1120,13 +1145,14 @@ function createMcpServer(deps2) {
 }
 function registerTools(server, deps2) {
   const { registry: registry2 } = deps2;
+  const ownerId = randomUUID2();
   const toolHandlers = /* @__PURE__ */ new Map([
     ["openclaw_chat", (input) => handleOpenclawChat(registry2, input)],
     ["openclaw_status", (input) => handleOpenclawStatus(registry2, input)],
-    ["openclaw_chat_async", (input) => handleOpenclawChatAsync(registry2, input)],
-    ["openclaw_task_status", (input) => handleOpenclawTaskStatus(registry2, input)],
-    ["openclaw_task_list", (input) => handleOpenclawTaskList(registry2, input)],
-    ["openclaw_task_cancel", (input) => handleOpenclawTaskCancel(registry2, input)],
+    ["openclaw_chat_async", (input) => handleOpenclawChatAsync(registry2, input, ownerId)],
+    ["openclaw_task_status", (input) => handleOpenclawTaskStatus(registry2, input, ownerId)],
+    ["openclaw_task_list", (input) => handleOpenclawTaskList(registry2, input, ownerId)],
+    ["openclaw_task_cancel", (input) => handleOpenclawTaskCancel(registry2, input, ownerId)],
     ["openclaw_instances", (input) => handleOpenclawInstances(registry2, input)]
   ]);
   const allTools = [
@@ -1158,7 +1184,7 @@ function registerTools(server, deps2) {
 }
 
 // src/server/http.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID4 } from "crypto";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
@@ -1166,7 +1192,7 @@ import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
 
 // src/auth/provider.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 import {
   InvalidRequestError,
   InvalidTokenError
@@ -1175,13 +1201,15 @@ var TOKEN_TTL_MS = 60 * 60 * 1e3;
 var AUTH_CODE_TTL_MS = 10 * 60 * 1e3;
 var REFRESH_TOKEN_TTL_MS = 24 * 60 * 60 * 1e3;
 var REAPER_INTERVAL_MS = 5 * 60 * 1e3;
-var ALLOW_ANY_REDIRECT = new Proxy([], {
-  get(target, prop) {
-    if (prop === "includes") return () => true;
-    if (prop === "length") return 1;
-    return Reflect.get(target, prop);
+var AllowAnyRedirectUris = class extends Array {
+  includes(_searchElement, _fromIndex) {
+    return true;
   }
-});
+  some(_predicate, _thisArg) {
+    return true;
+  }
+};
+var ALLOW_ANY_REDIRECT = new AllowAnyRedirectUris();
 var MAX_DYNAMIC_CLIENTS = 100;
 var OpenClawClientsStore = class {
   client;
@@ -1263,7 +1291,7 @@ var OpenClawAuthProvider = class {
    * Auto-approve: generate auth code and redirect immediately.
    */
   async authorize(client, params, res) {
-    const code = randomUUID();
+    const code = randomUUID3();
     this.codes.set(code, { client, params, createdAt: Date.now() });
     const searchParams = new URLSearchParams({ code });
     if (params.state !== void 0) {
@@ -1291,8 +1319,8 @@ var OpenClawAuthProvider = class {
       throw new InvalidRequestError("Authorization code was not issued to this client");
     }
     this.codes.delete(authorizationCode);
-    const accessToken = randomUUID();
-    const refreshToken = randomUUID();
+    const accessToken = randomUUID3();
+    const refreshToken = randomUUID3();
     const scopes = codeData.params.scopes || [];
     this.tokens.set(accessToken, {
       token: accessToken,
@@ -1325,8 +1353,8 @@ var OpenClawAuthProvider = class {
       throw new InvalidRequestError("Refresh token was not issued to this client");
     }
     this.refreshTokens.delete(refreshToken);
-    const accessToken = randomUUID();
-    const newRefreshToken = randomUUID();
+    const accessToken = randomUUID3();
+    const newRefreshToken = randomUUID3();
     const tokenScopes = scopes || data.scopes;
     this.tokens.set(accessToken, {
       token: accessToken,
@@ -1393,12 +1421,12 @@ function parseTrustProxy(value) {
 }
 function loadCorsConfig() {
   const corsOrigins = process.env.CORS_ORIGINS;
-  if (!corsOrigins || corsOrigins === "*") {
-    return { origins: ["*"], enabled: true };
-  }
-  if (corsOrigins.toLowerCase() === "none" || corsOrigins === "") {
+  if (!corsOrigins || corsOrigins.toLowerCase() === "none") {
     return { origins: [], enabled: false };
   }
+  if (corsOrigins === "*") {
+    return { origins: ["*"], enabled: true };
+  }
   return {
     origins: corsOrigins.split(",").map((s) => s.trim()).filter(Boolean),
     enabled: true
@@ -1549,7 +1577,7 @@ async function createHttpServer(config, deps2) {
       return;
     }
     const transport = new StreamableHTTPServerTransport({
-      sessionIdGenerator: () => randomUUID2(),
+      sessionIdGenerator: () => randomUUID4(),
       onsessioninitialized: (newSessionId) => {
         streamableSessions.set(newSessionId, { transport, server });
         log(`Streamable session initialized: ${newSessionId}`);
@@ -1584,6 +1612,11 @@ async function createHttpServer(config, deps2) {
     log(`HTTP server listening on ${config.host}:${config.port}`);
     log(`Auth enabled: ${authEnabled}`);
     log(`CORS origins: ${corsConfig.enabled ? corsConfig.origins.join(", ") : "disabled"}`);
+    if (corsConfig.origins.includes("*")) {
+      logError(
+        "WARNING: CORS_ORIGINS=* allows any web page to call this server from a browser. List explicit origins instead."
+      );
+    }
     if (authEnabled) {
       log("OAuth 2.1 authentication is REQUIRED for all connections");
       log("Endpoints:");

package/docs/configuration.md

@@ -123,17 +123,24 @@ When `TRUST_PROXY` is unset and a reverse proxy injects an `X-Forwarded-For` hea
 
 ### CORS Configuration
 
-| Variable       | Description                       | Default |
-| -------------- | --------------------------------- | ------- |
-| `CORS_ORIGINS` | Allowed origins (comma-separated) | `*`     |
+| Variable       | Description                       | Default            |
+| -------------- | --------------------------------- | ------------------ |
+| `CORS_ORIGINS` | Allowed origins (comma-separated) | _(CORS disabled)_  |
+
+CORS is **off unless you opt in**. With it off the server sends no
+`Access-Control-Allow-Origin` header, so browsers refuse cross-origin calls to
+it. Non-browser clients — Claude.ai, Claude Desktop, and anything speaking
+stdio — are unaffected; set this only when a web page has to reach the server
+directly.
 
 **CORS_ORIGINS examples:**
 
-- `*` — Allow all origins (not recommended for production)
-- `none` — Disable CORS entirely
+- _(unset)_ or `none` — CORS disabled (default)
 - `https://claude.ai` — Single origin
 - `https://claude.ai,https://your-app.com` — Multiple origins
 - `*.example.com` — Wildcard subdomain
+- `*` — Allow all origins. Lets any web page drive this server through a
+  visitor's browser; do not use in production.
 
 ### Authentication (OAuth 2.1)
 
@@ -170,6 +177,18 @@ When auth is enabled, the server exposes these OAuth 2.1 endpoints:
 
 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.
 
+#### Redirect URI allow-list
+
+`MCP_REDIRECT_URIS` restricts which `redirect_uri` values the `/authorize` endpoint accepts for the pre-configured client. When unset, any redirect URI is accepted (the client secret verified during token exchange remains the actual auth gate) — set it in production so authorization codes can only be delivered to callbacks you trust.
+
+Claude.ai uses exactly this callback (note the `/api/mcp/auth_callback` path):
+
+```bash
+MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
+```
+
+Matching is exact (scheme, host, path). A common mistake is registering `https://claude.ai/oauth/callback`, which does **not** match and makes Claude.ai fail with `Unregistered redirect_uri`. If you also connect other clients (e.g. MCP Inspector), append their callbacks to the comma-separated list — loopback callbacks (`http://localhost/...`, `http://127.0.0.1/...`) match on any port per RFC 8252.
+
 #### 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).

package/docs/deployment.md

@@ -24,6 +24,7 @@ services:
       - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET:-}
       - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
       - MCP_REDIRECT_URIS=${MCP_REDIRECT_URIS:-}
+      - TRUST_PROXY=${TRUST_PROXY:-}
       - CORS_ORIGINS=${CORS_ORIGINS:-https://claude.ai}
       - NODE_ENV=production
     extra_hosts:
@@ -56,6 +57,12 @@ AUTH_ENABLED=true
 # Public URL (required when behind a reverse proxy)
 MCP_ISSUER_URL=https://mcp.your-domain.com
 
+# Trust the reverse proxy's X-Forwarded-For (required behind a reverse proxy)
+TRUST_PROXY=1
+
+# Allowed OAuth redirect URIs — Claude.ai callbacks (recommended for production)
+MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
+
 # Allowed CORS origins
 CORS_ORIGINS=https://claude.ai
 ```
@@ -79,7 +86,7 @@ docker compose up -d
 - [ ] `MCP_CLIENT_SECRET` generated securely (`openssl rand -hex 32`, min 32 chars)
 - [ ] `MCP_ISSUER_URL` set to public HTTPS URL (when behind reverse proxy)
 - [ ] `TRUST_PROXY` set to the right hop count / CIDR (when behind reverse proxy)
-- [ ] `MCP_REDIRECT_URIS` restricted to known callback URLs
+- [ ] `MCP_REDIRECT_URIS` restricted to known callback URLs (for Claude.ai: `https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback`)
 - [ ] CORS restricted to known origins (`CORS_ORIGINS=https://claude.ai`)
 - [ ] `OPENCLAW_GATEWAY_TOKEN` set for gateway authentication
 - [ ] Dynamic client registration is disabled (default — no `/register` endpoint)
@@ -205,6 +212,18 @@ You're running behind a reverse proxy but haven't set `MCP_ISSUER_URL`. The OAut
 
 Your Claude.ai connector URL is missing the `/mcp` path. The MCP Streamable HTTP transport is mounted at `/mcp`, not at the server root (which is intentional — root is reserved for `/health`, `/.well-known/*`, OAuth endpoints, and legacy SSE endpoints). Update the connector URL in Claude.ai to end with `/mcp`, e.g. `https://mcp.your-domain.com/mcp`.
 
+### `invalid_request` / `Unregistered redirect_uri` on `/authorize`
+
+The `redirect_uri` the client sent is not on the server's allow-list. Two common causes:
+
+1. **`MCP_REDIRECT_URIS` is set but doesn't contain the client's exact callback.** Claude.ai uses `https://claude.ai/api/mcp/auth_callback` (and `https://claude.com/api/mcp/auth_callback`) — a similar-looking entry like `https://claude.ai/oauth/callback` does **not** match. Matching is exact on scheme, host, and path; only loopback callbacks (`localhost`, `127.0.0.1`, `[::1]`) get port relaxation per RFC 8252.
+
+2. **You're on bridge ≤ 1.5.0 with `MCP_REDIRECT_URIS` unset.** The allow-any fallback in those versions was silently broken by a change in MCP SDK 1.29 (the SDK switched its membership check from `.includes()` to `.some()`), so *every* redirect_uri was rejected — fresh `npx openclaw-mcp@latest` installs picked the new SDK up automatically. Upgrade to bridge ≥ 1.6.0, or set `MCP_REDIRECT_URIS` explicitly (recommended for production anyway):
+
+```bash
+MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
+```
+
 ### `ValidationError: ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` on `/token`
 
 The server is behind a reverse proxy that sets `X-Forwarded-For`, but Express's `trust proxy` is left at its default (`false`). The MCP SDK's OAuth handlers use `express-rate-limit`, which refuses to read the forwarded header in that configuration and crashes the request. Set `TRUST_PROXY=1` (single proxy in front) or `--trust-proxy 1`. Use a higher hop count, a CIDR/IP, or a keyword (`loopback`, `linklocal`, `uniquelocal`) for more complex topologies — see [Server Settings](configuration.md#server-settings-http-transport).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-mcp",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "mcpName": "io.github.freema/openclaw-mcp",
   "description": "Model Context Protocol (MCP) server for OpenClaw AI assistant integration",
   "author": "Tomáš Grasl <https://www.tomasgrasl.cz/>",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "yargs": "^17.7.2"
   },
   "devDependencies": {