openclaw-mcp 1.4.1 → 1.6.0

package/README.md

@@ -54,6 +54,8 @@ 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:
       - "host.docker.internal:host-gateway"
@@ -70,7 +72,9 @@ export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
 docker compose up -d
 ```
 
-Then in Claude.ai add a custom MCP connector pointing to your server with `MCP_CLIENT_ID=openclaw` and your `MCP_CLIENT_SECRET`.
+Then in Claude.ai add a custom MCP connector pointing to `https://your-domain.com/mcp` with `MCP_CLIENT_ID=openclaw` and your `MCP_CLIENT_SECRET`.
+
+> **Important:** The connector URL **must end with `/mcp`** — that's the Streamable HTTP endpoint. A bare domain (`https://your-domain.com`) hits the server root and returns 404 after OAuth completes.
 
 > **Tip:** Pin a specific version instead of `latest` for production: `ghcr.io/freema/openclaw-mcp:1.1.0`
 
@@ -105,10 +109,14 @@ Add to your Claude Desktop config:
 AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
   MCP_ISSUER_URL=https://mcp.your-domain.com \
   CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
-  npx openclaw-mcp --transport sse --port 3000
+  npx openclaw-mcp --transport http --port 3000
 ```
 
-> **Important:** When running behind a reverse proxy (Caddy, nginx, etc.), you **must** set `MCP_ISSUER_URL` (or `--issuer-url`) to your public HTTPS URL. Without this, OAuth metadata will advertise `http://localhost:3000` and clients will fail to authenticate.
+> **Important:** When running behind a reverse proxy (Caddy, nginx, Traefik, Cloudflare Tunnel, etc.) you **must** set:
+> - `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.
 
@@ -250,7 +258,7 @@ export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
 
 # Run with auth enabled
 AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
-  openclaw-mcp --transport sse
+  openclaw-mcp --transport http
 ```
 
 Configure CORS to restrict access:
@@ -261,6 +269,36 @@ CORS_ORIGINS=https://claude.ai,https://your-app.com
 
 See [Configuration](docs/configuration.md) for all security options.
 
+## 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.
+
+### What changed
+
+| Before | After |
+|--------|-------|
+| `--transport sse` | `--transport http` (recommended) |
+| Primary endpoint: `GET /sse` | Primary endpoint: `POST/GET/DELETE /mcp` |
+| Health: `"transport": "sse"` | Health: `"transport": "streamable-http"` |
+
+### Migration steps
+
+1. **CLI / Docker**: Replace `--transport sse` with `--transport http`
+   ```bash
+   # Before
+   openclaw-mcp --transport sse --port 3000
+   # After
+   openclaw-mcp --transport http --port 3000
+   ```
+
+2. **Claude.ai connector URL**: No change needed — Claude.ai already uses `/mcp` (Streamable HTTP)
+
+3. **Legacy clients**: The `/sse` and `/messages` endpoints still work. A deprecation warning is logged on each SSE connection.
+
+4. **Dockerfile ENTRYPOINT**: Updated automatically if using the official Docker image
+
+> **Note:** `--transport sse` will continue to work as a deprecated alias. Both transports are served simultaneously regardless of which flag you use.
+
 ## Requirements
 
 - Node.js ≥ 20

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.4.1";
+var SERVER_VERSION = "1.6.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==";
@@ -74,17 +74,17 @@ function parseArguments(version) {
   }).option("transport", {
     alias: "t",
     type: "string",
-    choices: ["stdio", "sse"],
-    description: "Transport mode (stdio for local, sse for remote)",
+    choices: ["stdio", "http", "sse"],
+    description: 'Transport mode (stdio for local, http for remote; "sse" is a deprecated alias for "http")',
     default: "stdio"
   }).option("port", {
     alias: "p",
     type: "number",
-    description: "Port for SSE server",
+    description: "Port for HTTP server",
     default: parseInt(process.env.PORT || "3000", 10)
   }).option("host", {
     type: "string",
-    description: "Host for SSE server",
+    description: "Host for HTTP server",
     default: process.env.HOST || "0.0.0.0"
   }).option("timeout", {
     type: "number",
@@ -96,7 +96,7 @@ function parseArguments(version) {
     default: process.env.DEBUG === "true" || process.env.NODE_ENV === "development"
   }).option("auth", {
     type: "boolean",
-    description: "Enable OAuth authentication (SSE mode)",
+    description: "Enable OAuth authentication (HTTP mode)",
     default: process.env.AUTH_ENABLED === "true" || process.env.OAUTH_ENABLED === "true"
   }).option("client-id", {
     type: "string",
@@ -118,6 +118,10 @@ function parseArguments(version) {
     type: "boolean",
     description: "Allow OAuth Dynamic Client Registration (Cursor/Windsurf compatibility, dev-only)",
     default: process.env.MCP_DANGEROUSLY_ALLOW_DCR === "true"
+  }).option("trust-proxy", {
+    type: "string",
+    description: 'Express trust proxy setting when behind a reverse proxy (e.g. "1", "true", or a CIDR)',
+    default: process.env.TRUST_PROXY || void 0
   }).help().parseSync();
   let instances;
   const instancesEnv = process.env.OPENCLAW_INSTANCES;
@@ -173,6 +177,7 @@ function parseArguments(version) {
     issuerUrl: argv["issuer-url"],
     redirectUris: argv["redirect-uris"] ? argv["redirect-uris"].split(",").map((s) => s.trim()).filter(Boolean) : void 0,
     allowDcr: argv["allow-dcr"],
+    trustProxy: argv["trust-proxy"],
     instances
   };
 }
@@ -1152,7 +1157,7 @@ function registerTools(server, deps2) {
   });
 }
 
-// src/server/sse.ts
+// src/server/http.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -1170,13 +1175,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;
@@ -1369,7 +1376,23 @@ var OpenClawAuthProvider = class {
   }
 };
 
-// src/server/sse.ts
+// src/server/http.ts
+function parseTrustProxy(value) {
+  if (value === void 0 || value === "") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return void 0;
+  }
+  const lower = trimmed.toLowerCase();
+  if (lower === "true") return true;
+  if (lower === "false") return false;
+  if (/^\d+$/.test(trimmed)) {
+    return parseInt(trimmed, 10);
+  }
+  return trimmed;
+}
 function loadCorsConfig() {
   const corsOrigins = process.env.CORS_ORIGINS;
   if (!corsOrigins || corsOrigins === "*") {
@@ -1399,12 +1422,16 @@ function isOriginAllowed(origin, allowedOrigins) {
     return origin === allowed || origin === `https://${allowed}` || origin === `http://${allowed}`;
   });
 }
-async function createSSEServer(config, deps2) {
+async function createHttpServer(config, deps2) {
   const authEnabled = !!config.authConfig?.clientId;
   const corsConfig = loadCorsConfig();
-  const sseSessions = /* @__PURE__ */ new Map();
+  const legacySseSessions = /* @__PURE__ */ new Map();
   const streamableSessions = /* @__PURE__ */ new Map();
   const app = createMcpExpressApp({ host: config.host });
+  if (config.trustProxy !== void 0) {
+    app.set("trust proxy", config.trustProxy);
+    log(`Trust proxy: ${JSON.stringify(config.trustProxy)}`);
+  }
   app.use((req, res, next) => {
     if (!corsConfig.enabled) {
       next();
@@ -1450,7 +1477,8 @@ async function createSSEServer(config, deps2) {
   app.get("/health", (_req, res) => {
     res.json({
       status: "ok",
-      transport: "sse",
+      transport: "streamable-http",
+      legacySseSupported: true,
       auth: authEnabled
     });
   });
@@ -1463,19 +1491,20 @@ async function createSSEServer(config, deps2) {
   app.get(
     "/sse",
     ...withAuth(async (req, res) => {
+      log("Legacy SSE transport is deprecated; prefer Streamable HTTP at /mcp");
       const transport = new SSEServerTransport("/messages", res);
       const server = createMcpServer(deps2);
       const sessionId = transport.sessionId;
-      sseSessions.set(sessionId, { transport, server });
+      legacySseSessions.set(sessionId, { transport, server });
       log(`SSE session connected: ${sessionId}`);
       transport.onclose = () => {
-        sseSessions.delete(sessionId);
+        legacySseSessions.delete(sessionId);
         log(`SSE session disconnected: ${sessionId}`);
       };
       try {
         await server.connect(transport);
       } catch (error) {
-        sseSessions.delete(sessionId);
+        legacySseSessions.delete(sessionId);
         logError(`Failed to connect SSE session ${sessionId}`, error);
       }
     })
@@ -1484,7 +1513,7 @@ async function createSSEServer(config, deps2) {
     "/messages",
     ...withAuth(async (req, res) => {
       const sessionId = req.query.sessionId;
-      const session = sseSessions.get(sessionId);
+      const session = legacySseSessions.get(sessionId);
       if (!session) {
         res.status(404).json({ error: "Session not found" });
         return;
@@ -1554,7 +1583,7 @@ async function createSSEServer(config, deps2) {
   app.post("/mcp", ...withAuth(handleStreamableRequest));
   app.delete("/mcp", ...withAuth(handleStreamableRequest));
   const httpServer = app.listen(config.port, config.host, () => {
-    log(`SSE server listening on ${config.host}:${config.port}`);
+    log(`HTTP server listening on ${config.host}:${config.port}`);
     log(`Auth enabled: ${authEnabled}`);
     log(`CORS origins: ${corsConfig.enabled ? corsConfig.origins.join(", ") : "disabled"}`);
     if (authEnabled) {
@@ -1569,20 +1598,20 @@ async function createSSEServer(config, deps2) {
     }
     log("MCP Endpoints:");
     log("  GET  /health   - Health check (no auth)");
-    log("  GET  /sse      - Legacy SSE stream");
-    log("  POST /messages - Legacy SSE messages");
-    log("  ALL  /mcp      - Streamable HTTP");
+    log("  ALL  /mcp      - Streamable HTTP (primary)");
+    log("  GET  /sse      - Legacy SSE stream (deprecated)");
+    log("  POST /messages - Legacy SSE messages (deprecated)");
   });
   const shutdown = async () => {
-    log("Shutting down SSE server...");
-    for (const [id, session] of sseSessions) {
+    log("Shutting down HTTP server...");
+    for (const [id, session] of legacySseSessions) {
       try {
         await session.server.close();
       } catch (error) {
         logError(`Error closing SSE session ${id}`, error);
       }
     }
-    sseSessions.clear();
+    legacySseSessions.clear();
     for (const [id, session] of streamableSessions) {
       try {
         await session.server.close();
@@ -1592,7 +1621,7 @@ async function createSSEServer(config, deps2) {
     }
     streamableSessions.clear();
     httpServer.close(() => {
-      log("SSE server stopped");
+      log("HTTP server stopped");
       process.exit(0);
     });
     setTimeout(() => {
@@ -1631,11 +1660,15 @@ async function main() {
     const defaultLabel = instance.isDefault ? " (default)" : "";
     log(`Instance "${instance.name}": ${instance.url}${defaultLabel}`);
   }
-  if (args.transport === "sse") {
-    const sseConfig = {
+  if (args.transport === "sse" || args.transport === "http") {
+    if (args.transport === "sse") {
+      log("WARNING: --transport sse is deprecated; use --transport http instead");
+    }
+    const httpConfig = {
       port: args.port,
       host: args.host,
-      issuerUrl: args.issuerUrl
+      issuerUrl: args.issuerUrl,
+      trustProxy: parseTrustProxy(args.trustProxy)
     };
     if (args.authEnabled && args.clientId) {
       const clientIdRegex = /^[a-zA-Z0-9][a-zA-Z0-9_-]{2,63}$/;
@@ -1651,7 +1684,7 @@ async function main() {
         );
         process.exit(1);
       }
-      sseConfig.authConfig = {
+      httpConfig.authConfig = {
         clientId: args.clientId,
         clientSecret: args.clientSecret,
         redirectUris: args.redirectUris,
@@ -1685,7 +1718,7 @@ async function main() {
       logError("AUTH_ENABLED=true but MCP_CLIENT_ID is not set. Refusing to start without auth.");
       process.exit(1);
     }
-    await createSSEServer(sseConfig, deps);
+    await createHttpServer(httpConfig, deps);
   } else {
     const server = createMcpServer(deps);
     const transport = new StdioServerTransport();

package/docs/configuration.md

@@ -100,13 +100,26 @@ services:
 
 **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)
+### Server Settings (HTTP transport)
 
-| Variable | Description          | Default   |
-| -------- | -------------------- | --------- |
-| `PORT`   | SSE server port      | `3000`    |
-| `HOST`   | SSE server host      | `0.0.0.0` |
-| `DEBUG`  | Enable debug logging | `false`   |
+| Variable      | Description                                                       | Default                  |
+| ------------- | ----------------------------------------------------------------- | ------------------------ |
+| `PORT`        | HTTP server port                                                  | `3000`                   |
+| `HOST`        | HTTP server host                                                  | `0.0.0.0`                |
+| `DEBUG`       | Enable debug logging                                              | `false`                  |
+| `TRUST_PROXY` | Express `trust proxy` setting (required behind a reverse proxy)   | (unset — trust nothing)  |
+
+**`TRUST_PROXY` values:**
+
+| Value          | Meaning                                                                        |
+| -------------- | ------------------------------------------------------------------------------ |
+| (unset)        | Express default — do not trust any proxy                                       |
+| `1`            | Trust one hop — typical when there is a single reverse proxy in front          |
+| `true`         | Trust every proxy — only safe on a fully private network                       |
+| `loopback`     | Trust `127.0.0.1` and `::1`                                                    |
+| `10.0.0.0/8`   | Trust a specific IP or CIDR range                                              |
+
+When `TRUST_PROXY` is unset and a reverse proxy injects an `X-Forwarded-For` header, the MCP SDK's `/token` handler crashes with `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` and OAuth fails. Set this whenever the server is behind Caddy, nginx, Traefik, Cloudflare Tunnel, ngrok, or any other proxy.
 
 ### CORS Configuration
 
@@ -157,6 +170,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:
@@ -50,12 +51,18 @@ OPENCLAW_GATEWAY_TOKEN=your-gateway-token
 MCP_CLIENT_ID=openclaw
 MCP_CLIENT_SECRET=your-client-secret
 
-# Enable OAuth (required for production SSE)
+# Enable OAuth (required for production HTTP transport)
 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
 ```
@@ -78,7 +85,8 @@ docker compose up -d
 - [ ] `MCP_CLIENT_ID` is valid (3–64 chars, alphanumeric/dashes/underscores)
 - [ ] `MCP_CLIENT_SECRET` generated securely (`openssl rand -hex 32`, min 32 chars)
 - [ ] `MCP_ISSUER_URL` set to public HTTPS URL (when behind reverse proxy)
-- [ ] `MCP_REDIRECT_URIS` restricted to known callback URLs
+- [ ] `TRUST_PROXY` set to the right hop count / CIDR (when behind reverse proxy)
+- [ ] `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)
@@ -88,7 +96,9 @@ docker compose up -d
 
 The MCP bridge must be served over HTTPS for production use. Use a reverse proxy that handles TLS termination.
 
-> **Important:** You **must** set `MCP_ISSUER_URL` to your public HTTPS URL. Without this, OAuth metadata endpoints will advertise `http://localhost:3000` and MCP clients (including Claude.ai) will fail to authenticate with the error: `Protected resource http://localhost:3000/mcp does not match expected https://your-domain.com/mcp`.
+> **Important:** When running behind a reverse proxy you **must** set both:
+> - `MCP_ISSUER_URL` to your public HTTPS URL — otherwise OAuth metadata endpoints advertise `http://localhost:3000` and MCP clients (including Claude.ai) fail to authenticate with `Protected resource http://localhost:3000/mcp does not match expected https://your-domain.com/mcp`.
+> - `TRUST_PROXY=1` so Express trusts the proxy's `X-Forwarded-For` header — otherwise `express-rate-limit` (used by the MCP SDK auth handlers) crashes `/token` with `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`.
 
 ### Caddy (recommended)
 
@@ -122,6 +132,7 @@ services:
       - "3000"
     environment:
       - MCP_ISSUER_URL=https://mcp.your-domain.com
+      - TRUST_PROXY=1
       # ... other env vars
 
 volumes:
@@ -197,6 +208,26 @@ The OpenClaw gateway's HTTP chat completions endpoint is disabled by default. En
 
 You're running behind a reverse proxy but haven't set `MCP_ISSUER_URL`. The OAuth metadata endpoints are advertising `http://localhost:3000` instead of your public HTTPS URL. Set `MCP_ISSUER_URL` to your public URL (e.g., `https://mcp.your-domain.com`) or pass `--issuer-url` on the CLI.
 
+### `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`.
+
+### `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).
+
 ### `fetch failed` / MCP bridge can't reach gateway
 
 When both services run in Docker, the MCP bridge must connect via the Docker network hostname (e.g., `http://openclaw-gateway:18789`), not `localhost`. Make sure both containers are on the same Docker network.

package/docs/development.md

@@ -48,7 +48,7 @@ src/
 ├── mcp/
 │   └── tools/      # MCP tool implementations
 ├── openclaw/       # OpenClaw API client
-├── server/         # SSE server (for remote access)
+├── server/         # HTTP server (for remote access)
 ├── utils/          # Logging, errors, helpers
 ├── cli.ts          # CLI argument parsing
 └── index.ts        # Main entry point

package/docs/installation.md

@@ -38,7 +38,7 @@ For local use with Claude Desktop, use stdio transport (default):
 
 ## Claude.ai (Remote Access)
 
-For remote access via Claude.ai, deploy with SSE transport and OAuth 2.1 authentication.
+For remote access via Claude.ai, deploy with HTTP transport and OAuth 2.1 authentication.
 
 ### 1. Generate credentials
 
@@ -57,7 +57,7 @@ MCP_CLIENT_ID=openclaw \
 MCP_CLIENT_SECRET=your-secret \
 CORS_ORIGINS=https://claude.ai \
 OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
-openclaw-mcp --transport sse --port 3000
+openclaw-mcp --transport http --port 3000
 ```
 
 ### 3. Add to Claude.ai
@@ -92,17 +92,20 @@ 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"]
+  --transport, -t     Transport mode           [choices: "stdio", "http", "sse"] [default: "stdio"]
+  --port, -p          Port for HTTP server     [default: 3000]
+  --host              Host for HTTP 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]
   --issuer-url        OAuth issuer URL         [env: MCP_ISSUER_URL]
   --redirect-uris     Allowed redirect URIs    [env: MCP_REDIRECT_URIS]
+  --trust-proxy       Express trust proxy      [env: TRUST_PROXY]
   --version           Show version number
   --help              Show help
 ```
 
 > **Note:** `--issuer-url` is required when running behind a reverse proxy (Caddy, nginx, etc.) so that OAuth metadata endpoints return the correct public HTTPS URL instead of `http://localhost:3000`.
+
+> **Note:** `--trust-proxy` (or `TRUST_PROXY`) is also required when running behind a reverse proxy. Use `1` for a single proxy, `true` on a fully private network, or a CIDR/keyword (`loopback`, `linklocal`, `uniquelocal`) for more specific setups. Without it, `/token` crashes with `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`.

package/docs/logging.md

@@ -18,10 +18,10 @@ The MCP server logs operational events to **stderr** using the `[openclaw-mcp]`
 
 - Server name and version
 - OpenClaw gateway URL (host only, no tokens)
-- Transport type (stdio or SSE)
+- Transport type (stdio or HTTP)
 - Whether a gateway token is configured (yes/no, not the token itself)
 - OAuth client ID (when auth is enabled)
-- Listening address and port (SSE mode)
+- Listening address and port (HTTP mode)
 - CORS origins configuration
 
 ### Connections (SSE/HTTP transport)
@@ -71,7 +71,7 @@ This is a safety net — the code avoids logging sensitive values in the first p
 | Transport | Destination | Notes |
 |-----------|-------------|-------|
 | stdio | stderr | Cannot use stdout (reserved for MCP protocol) |
-| SSE/HTTP | stderr | Same format, same destination |
+| HTTP | stderr | Same format, same destination |
 | Docker | `docker logs openclaw-mcp` | stderr is captured by Docker's log driver |
 
 ## Docker Log Management

package/docs/threat-model.md

@@ -5,7 +5,7 @@
 ```
 Claude (Desktop / Claude.ai)
     |
-    | MCP Protocol (stdio or SSE/Streamable HTTP)
+    | MCP Protocol (stdio or Streamable HTTP)
     v
 OpenClaw MCP Server (this project)
     |
@@ -43,7 +43,7 @@ The MCP server is a **stateless proxy** — it translates MCP tool calls into Op
 ### Boundary 1: Claude <-> MCP Server
 
 - **stdio transport (local):** Trusted — communication stays on the local machine. No authentication required.
-- **SSE/HTTP transport (remote):** Untrusted network — requires OAuth 2.1 authentication, HTTPS (via reverse proxy), and CORS restrictions.
+- **HTTP transport (remote):** Untrusted network — requires OAuth 2.1 authentication, HTTPS (via reverse proxy), and CORS restrictions.
 
 ### Boundary 2: MCP Server <-> OpenClaw Gateway
 
@@ -75,7 +75,7 @@ The MCP server is a **stateless proxy** — it translates MCP tool calls into Op
 - Responses are parsed as JSON — no script execution
 - Error messages from the gateway are sanitized before being returned to Claude
 
-### 3. Network-Level Attacks (SSE transport)
+### 3. Network-Level Attacks (HTTP transport)
 
 **Risk:** Man-in-the-middle, replay attacks, unauthorized access.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-mcp",
-  "version": "1.4.1",
+  "version": "1.6.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": {