openclaw-mcp 1.5.0 → 2.0.0-beta.1

package/docs/configuration.md

@@ -10,8 +10,9 @@ 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_TIMEOUT_MS`    | Request timeout in milliseconds. For async (streamed) tasks this is an **idle** timeout — it resets on every received chunk, so long-running gateway work is only aborted when the stream goes silent. | `120000` (2 min)         |
 | `OPENCLAW_MODEL`         | Model name for chat completions         | `openclaw`               |
+| `OPENCLAW_TASK_CONCURRENCY` | How many async tasks run in parallel (1–20) | `3`                  |
 
 ### Multi-Instance Mode
 
@@ -170,6 +171,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)
@@ -203,7 +210,19 @@ You're running behind a reverse proxy but haven't set `MCP_ISSUER_URL`. The OAut
 
 ### `POST /` or `GET /` returns 404 after OAuth succeeds
 
-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`.
+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/*`, and OAuth 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`
 

package/docs/index.html

@@ -652,7 +652,7 @@ MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
 MCP_ISSUER_URL=https://mcp.your-domain.com \
 CORS_ORIGINS=https://claude.ai \
 OPENCLAW_GATEWAY_TOKEN=your-token \
-npx openclaw-mcp --transport sse --port 3000</code></pre>
+npx openclaw-mcp --transport http --port 3000</code></pre>
           </div>
         </div>
       </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-mcp",
-  "version": "1.5.0",
+  "version": "2.0.0-beta.1",
   "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,10 +40,16 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "yargs": "^17.7.2"
+    "@modelcontextprotocol/express": "^2.0.0-beta.4",
+    "@modelcontextprotocol/node": "^2.0.0-beta.4",
+    "@modelcontextprotocol/server": "^2.0.0-beta.4",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.6.0",
+    "yargs": "^17.7.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^20.11.0",
     "@types/yargs": "^17.0.32",
     "@typescript-eslint/eslint-plugin": "^6.21.0",