webcake-landing-mcp 1.0.7 → 1.0.9

package/README.md

@@ -54,15 +54,18 @@ valid element/page skeletons, a page validator, and tools to create or edit page
 The AI agent produces the full `{ page, popup, settings, options, cartConfigs }` JSON; `create_page`
 persists it (source-only — the page opens in the editor where re-saving renders it).
 
-## Two ways to run
+## Setup methods (pick one)
 
-| Mode | Command | When |
-|------|---------|------|
-| **CDN / npx** (no clone) | `npx -y webcake-landing-mcp` | Fastest start — npm fetches & runs it, no clone or build. Auto-updates to the latest published version. |
-| **Local** (cloned build) | `node /abs/path/dist/index.js` | Hacking on the server, offline, or pinning a specific build. Run `npm run build` first. |
+| # | Method | Best for | Auth | Jump to |
+|---|--------|----------|------|---------|
+| 1 | **Local stdio** — add to an IDE (Claude Desktop / Cursor / …) via `npx` or a built file | Daily use on your machine | env `WEBCAKE_JWT`, or `login`, or none (reference tools) | [IDE config](#configuration-by-ide--ai-tool) |
+| 2 | **`login`** — grab the token through the browser (no copy-paste) | Avoiding a manual token paste (stdio / single-user remote) | browser session → saved `auth.json` | [Connect once](#connect-once--grab-your-token-automatically-login) |
+| 3 | **Remote HTTP (`serve`)** — run as an HTTP server, test with MCP Inspector / `mcp-remote` / curl | Trying the remote transport locally | per-request `x-webcake-jwt` header, or env | [Remote](#run-as-a-remote-connector-streamable-http) |
+| 4 | **VPS + claude.ai connector** — deploy public HTTPS, add as a custom connector | Sharing one hosted server | single-account (env token); per-user needs OAuth (not implemented) | [Deploy on a VPS](#deploy-on-a-vps) |
 
-Both expose the exact same tools. Every IDE config below shows the **local** form; to use **CDN** mode,
-just swap `command`/`args` for the npx form (see [Run without cloning](#run-without-cloning-npx)).
+Two **run forms** apply to any method: **`npx -y webcake-landing-mcp …`** (no clone, auto-updates) or **`node /abs/path/dist/index.js …`** (a cloned build — run `npm run build` first). The IDE configs below show the local form; swap `command`/`args` for the npx form to use CDN mode.
+
+The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
 
 ## Quick Install (Recommended)
 
@@ -184,6 +187,99 @@ The MCP config is the same as the local one, but `command`/`args` point at `npx`
 > npx caches the package after the first run, so subsequent launches are fast. Use a pinned version
 > (`webcake-landing-mcp@1.0.0`) if you need a reproducible build.
 
+## Run as a remote connector (Streamable HTTP)
+
+The server also speaks the **remote MCP** (Streamable HTTP) transport, so it can be added through
+Claude's **"Add custom connector"** dialog via a URL — not just as a local stdio server.
+
+Start it in HTTP mode (default port `8787`, or set `PORT` / `--port`):
+
+```bash
+npx -y webcake-landing-mcp serve --port 8787
+# → MCP endpoint at http://localhost:8787/mcp   (GET / or /health returns a status JSON)
+```
+
+Expose it over **HTTPS** at a public URL (a reverse proxy, a tunnel like `ngrok http 8787`, or any
+host), then in Claude → **Add custom connector**:
+
+- **Name**: `webcake-landing`
+- **Remote MCP server URL**: `https://<your-host>/mcp`
+
+The dialog has no header field, so to pass a token through it, **put it in the URL**:
+`https://<your-host>/mcp?jwt=<ljwt>` (also accepts `&api_base=…`, `&org_id=…`, `&host=…`, `&app_base=…`).
+Give each person a URL with their own `jwt` → **per-user without OAuth**. An explicit `x-webcake-jwt` header
+still wins over the query. ⚠️ A token in a URL can land in access/proxy logs — require **HTTPS** and disable
+query-string logging on your reverse proxy; a header (or OAuth) is safer when the client supports it.
+
+### Auth — per-request, multi-user (no shared token)
+
+In stdio mode the JWT comes from env. In HTTP mode each request carries the caller's **own** credentials
+via headers, so a hosted server is multi-user and never bakes in a shared secret:
+
+| Header | Maps to | Notes |
+|--------|---------|-------|
+| `x-webcake-jwt` (or `Authorization: Bearer <jwt>`) | `WEBCAKE_JWT` | the account token — sent per request |
+| `x-webcake-org-id` | `WEBCAKE_ORG_ID` | default org |
+| `x-webcake-api-base` | `WEBCAKE_API_BASE` | usually set once via env on the host instead |
+| `x-webcake-host` | `WEBCAKE_HOST` | Phoenix host-routing header |
+| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | editor/preview URL base |
+
+Any header that is absent falls back to the corresponding env var — so you can also run it **single-user**
+by setting `WEBCAKE_API_BASE` + `WEBCAKE_JWT` in the host's env and keeping the URL private.
+
+> ⚠️ The reference + generation tools (`get_generation_guide`, `list_elements`, `validate_page`, …) need
+> no secret; only the persistence tools (`create_page`, `update_page`, …) use the JWT. If a request has no
+> JWT, those tools return `missing_env` instead of touching the network.
+>
+> Note: the claude.ai connector dialog has **no header field** (only OAuth, which this server does not
+> implement yet). Two ways around it: put the token in the URL as `?jwt=<ljwt>` (above — per-user, but the
+> token shows up in logs), or use a header-capable client (`mcp-remote --header …`, below). A token in the
+> server's env instead gives a shared **single-account** for everyone on that URL.
+
+### Test it locally (no public URL needed)
+
+`localhost` can't be used in the claude.ai dialog (Anthropic fetches the URL from its own servers). To try the
+running `serve` server on your machine:
+
+- **MCP Inspector** (GUI — easiest): `npx @modelcontextprotocol/inspector` → Transport **Streamable HTTP** →
+  URL `http://localhost:8787/mcp` → under Headers add `x-webcake-jwt` (+ `x-webcake-api-base`) → Connect → call tools.
+- **`mcp-remote`** (use the remote server from a stdio client like Claude Desktop, with headers):
+  ```json
+  { "mcpServers": { "webcake-remote": { "command": "npx",
+    "args": ["-y", "mcp-remote", "http://localhost:8787/mcp",
+             "--header", "x-webcake-jwt:<ljwt>",
+             "--header", "x-webcake-api-base:https://api.webcake.io"] } } }
+  ```
+- **curl**: `initialize` (read the `mcp-session-id` response header) → `tools/list` → `tools/call`, all with
+  `Accept: application/json, text/event-stream`.
+
+### Deploy on a VPS
+
+1. **Build + run as a service** — `/etc/systemd/system/webcake-mcp.service`:
+   ```ini
+   [Service]
+   WorkingDirectory=/opt/webcake-landing-mcp
+   ExecStart=/usr/bin/node dist/index.js serve --port 8787
+   Environment=WEBCAKE_API_BASE=https://api.webcake.io
+   Environment=WEBCAKE_JWT=<ljwt>          # single-account only — see auth note below
+   Restart=always
+   [Install]
+   WantedBy=multi-user.target
+   ```
+   `sudo systemctl enable --now webcake-mcp` (build once: `npm install && npm run build`).
+2. **HTTPS + domain** (claude.ai requires https) — e.g. Caddy auto-TLS, `/etc/caddy/Caddyfile`:
+   ```
+   mcp.yourdomain.com { reverse_proxy localhost:8787 }
+   ```
+3. **Add to claude.ai** → Remote MCP server URL = `https://mcp.yourdomain.com/mcp`.
+
+**Auth on a shared server:**
+- **Single-account** (works with the dialog today): `WEBCAKE_JWT` in the service env → everyone using the
+  connector shares that one Webcake account. Keep the URL private / gated; the token expires (~90 days).
+- **Per-user** (each person their own account): give each person a URL with their own `?jwt=<ljwt>` (works
+  through the dialog, but the token appears in logs), or use a header-capable client (`mcp-remote --header …`),
+  or add **OAuth** (not implemented) for the cleanest flow.
+
 ## Manual Setup (local)
 
 ```bash
@@ -197,6 +293,55 @@ npm run smoke      # offline self-test of factory + validator (prints "ALL GOOD"
 The reference/validation tools work with **zero config**. Env vars are only needed for the persistence
 tools (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`).
 
+## Connect once — grab your token automatically (`login`)
+
+Instead of copying a JWT by hand, run:
+
+```bash
+# Production — zero config (defaults: connect via webcake.io, API via api.webcake.io):
+npx -y webcake-landing-mcp login
+
+# Local dev — point at your local SPA (5173) + API (5800):
+node dist/index.js login \
+  --connect-url http://localhost:5173/mcp-connect \
+  --api-base http://localhost:5800
+```
+
+It opens your browser → (log into Webcake if needed) → the token is saved to
+`~/.webcake-landing-mcp/auth.json`, which the server then reads automatically.
+
+You're already logged in to Webcake in your browser, so `login` just opens a Webcake "connect"
+page that reads your **`ljwt`** (landing) cookie and hands the token back to a localhost callback —
+no copy-paste. The saved token is used by **both** the stdio server and a single-user `serve`
+deployment (env vars still take precedence). The landing JWT lasts ~90 days, so you rarely reconnect.
+
+Two URLs, don't mix them up:
+
+- **Connect page = the SPA** (`--connect-url` / `WEBCAKE_CONNECT_URL`): `https://webcake.io/mcp-connect`
+  in prod, `http://localhost:5173/mcp-connect` locally. Otherwise derived from `WEBCAKE_APP_BASE` +
+  `/mcp-connect`, defaulting to `https://webcake.io/mcp-connect`.
+- **API base = the backend** (`--api-base` / `WEBCAKE_API_BASE`): `https://api.webcake.io` in prod,
+  `http://localhost:5800` locally. Defaults to `https://api.webcake.io`.
+
+Other flags: `--org-id`, `--port`, `--no-open`. Saved-file dir: `WEBCAKE_CONFIG_DIR` (default
+`~/.webcake-landing-mcp`).
+
+**Backend endpoint to add** (in your Webcake backend — it owns the session cookie):
+
+```
+GET /mcp-connect?redirect_uri=<loopback>&state=<s>
+   → read the `ljwt` cookie (the logged-in user's landing token)
+   → 302 to  <redirect_uri>?token=<ljwt>&state=<s>
+   (if there's no cookie: 302 to the login page first, then back here)
+```
+
+For safety, only honor `redirect_uri` values on `http://127.0.0.1:*` / `http://localhost:*`.
+(Reference implementation: `builderx_spa/src/views/McpConnect.vue` reads `cookies.get('ljwt')` — so this
+flow can also be done entirely in the SPA, no backend route needed.)
+
+> Multi-user remote (the claude.ai connector dialog) can't do this browser loopback — there each
+> user sends their own token via the `x-webcake-jwt` header (see the remote-connector section above).
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -206,6 +351,8 @@ tools (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizatio
 | `WEBCAKE_ORG_ID` | No | Default organization id for `create_page` (overridden by its `organization_id` arg). Omit → personal page. |
 | `WEBCAKE_HOST` | No | Optional `Host` header (Phoenix routes by host, e.g. `builder.localhost`). |
 | `WEBCAKE_APP_BASE` | No | Optional base used to build editor/preview URLs in the result. |
+| `WEBCAKE_CONNECT_URL` | No | The SPA "connect" page for `login` (default `https://webcake.io/mcp-connect`; else `WEBCAKE_APP_BASE` + `/mcp-connect`). |
+| `WEBCAKE_CONFIG_DIR` | No | Dir for the saved `auth.json` written by `login` (default `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` and `WEBCAKE_JWT` are only needed for the persistence tools. The reference and
 > validation tools (`get_generation_guide`, `list_elements`, `get_element`, `validate_page`, …) work without them.

package/README.vi.md

@@ -55,15 +55,18 @@ element/trang hợp lệ, bộ kiểm tra trang, và các tool để tạo/sửa
 `{ page, popup, settings, options, cartConfigs }`; `create_page` lưu nó (chỉ-source — trang mở trong editor,
 lưu lại sẽ render).
 
-## Hai cách chạy
+## Các cách setup (chọn một)
 
-| Chế độ | Lệnh | Khi nào |
-|------|------|------|
-| **CDN / npx** (không clone) | `npx -y webcake-landing-mcp` | Khởi động nhanh nhất — npm tự tải & chạy, không cần clone hay build. Tự cập nhật bản mới nhất. |
-| **Local** (clone & build) | `node /abs/path/dist/index.js` | Khi đang sửa server, offline, hoặc cần ghim một bản build cụ thể. Chạy `npm run build` trước. |
+| # | Cách | Hợp cho | Auth | Xem |
+|---|------|---------|------|-----|
+| 1 | **Local stdio** — gắn vào IDE (Claude Desktop / Cursor / …) qua `npx` hoặc file build | Dùng hằng ngày trên máy | env `WEBCAKE_JWT`, hoặc `login`, hoặc không cần (tool tham chiếu) | [Cấu hình IDE](#cấu-hình-theo-ide--công-cụ-ai) |
+| 2 | **`login`** — tự lấy token qua browser (khỏi copy-paste) | Khỏi dán token tay (stdio / remote 1 người) | session browser → file `auth.json` | [Kết nối một lần](#kết-nối-một-lần--tự-lấy-token-login) |
+| 3 | **Remote HTTP (`serve`)** — chạy như HTTP server, test bằng MCP Inspector / `mcp-remote` / curl | Thử transport remote ở local | header `x-webcake-jwt` mỗi request, hoặc env | [Remote](#chạy-như-remote-connector-streamable-http) |
+| 4 | **VPS + claude.ai connector** — deploy HTTPS public, thêm làm custom connector | Chia sẻ 1 server hosted | single-account (token env); per-user cần OAuth (chưa có) | [Deploy lên VPS](#deploy-lên-vps) |
 
-Cả hai cùng expose y hệt các tool. Mọi cấu hình IDE bên dưới dùng dạng **local**; để dùng **CDN**, chỉ cần
-đổi `command`/`args` sang dạng npx (xem [Chạy không cần clone (npx)](#chạy-không-cần-clone-npx)).
+Hai **dạng chạy** áp dụng cho mọi cách: **`npx -y webcake-landing-mcp …`** (không clone, tự cập nhật) hoặc **`node /abs/path/dist/index.js …`** (bản đã clone & build — chạy `npm run build` trước). Cấu hình IDE bên dưới dùng dạng local; đổi `command`/`args` sang dạng npx để dùng CDN.
+
+Các **tool tham chiếu + generation** (`get_generation_guide`, `list_elements`, `validate_page`, …) chạy **zero config**; chỉ **tool lưu trữ** (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`) mới cần token. Token ưu tiên theo thứ tự: **header mỗi request → biến env → file `auth.json`** (`login`).
 
 ## Cài nhanh (Khuyến nghị)
 
@@ -184,6 +187,97 @@ Cấu hình MCP giống bản local, chỉ khác `command`/`args` trỏ tới `n
 > npx cache lại package sau lần chạy đầu, nên các lần sau khởi động nhanh. Dùng phiên bản ghim
 > (`webcake-landing-mcp@1.0.0`) nếu cần build tái lập được.
 
+## Chạy như remote connector (Streamable HTTP)
+
+Server còn nói được transport **remote MCP** (Streamable HTTP), nên có thể thêm qua dialog
+**"Add custom connector"** của Claude bằng một URL — không chỉ stdio local.
+
+Chạy chế độ HTTP (port mặc định `8787`, hoặc đặt `PORT` / `--port`):
+
+```bash
+npx -y webcake-landing-mcp serve --port 8787
+# → endpoint MCP tại http://localhost:8787/mcp   (GET / hoặc /health trả JSON trạng thái)
+```
+
+Đưa ra **HTTPS** ở URL public (reverse proxy, tunnel như `ngrok http 8787`, hoặc host bất kỳ), rồi vào
+Claude → **Add custom connector**:
+
+- **Name**: `webcake-landing`
+- **Remote MCP server URL**: `https://<host-của-bạn>/mcp`
+
+Dialog không có ô header, nên muốn truyền token qua đó thì **để vào URL**:
+`https://<host-của-bạn>/mcp?jwt=<ljwt>` (nhận thêm `&api_base=…`, `&org_id=…`, `&host=…`, `&app_base=…`).
+Mỗi người một URL với `jwt` riêng → **per-user mà không cần OAuth**. Header `x-webcake-jwt` thật vẫn ưu tiên
+hơn query. ⚠️ Token nằm trong URL có thể lọt vào access/proxy log — **bắt buộc HTTPS** và tắt log query ở
+reverse proxy; dùng header (hoặc OAuth) an toàn hơn nếu client hỗ trợ.
+
+### Auth — mỗi request, đa người dùng (không token chung)
+
+Ở stdio JWT lấy từ env. Ở chế độ HTTP, mỗi request mang credential **riêng** của người gọi qua header,
+nên server hosted là đa người dùng và không nhúng secret chung:
+
+| Header | Tương ứng | Ghi chú |
+|--------|-----------|---------|
+| `x-webcake-jwt` (hoặc `Authorization: Bearer <jwt>`) | `WEBCAKE_JWT` | token tài khoản — gửi mỗi request |
+| `x-webcake-org-id` | `WEBCAKE_ORG_ID` | org mặc định |
+| `x-webcake-api-base` | `WEBCAKE_API_BASE` | thường set 1 lần qua env trên host |
+| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | base URL editor/preview |
+
+Header nào thiếu thì fallback về biến env tương ứng — nên cũng chạy **một người dùng** được bằng cách đặt
+`WEBCAKE_API_BASE` + `WEBCAKE_JWT` trong env của host và giữ URL riêng tư.
+
+> ⚠️ Tool tham chiếu + generation (`get_generation_guide`, `list_elements`, `validate_page`, …) không cần
+> secret; chỉ tool lưu trữ (`create_page`, `update_page`, …) dùng JWT. Request không có JWT thì các tool đó
+> trả `missing_env` chứ không gọi mạng.
+>
+> Lưu ý: dialog claude.ai **không có ô header** (chỉ có OAuth, mà server này **chưa làm**). Hai cách lách:
+> để token vào URL dạng `?jwt=<ljwt>` (như trên — per-user, nhưng token lộ trong log), hoặc dùng client hỗ trợ
+> header (`mcp-remote --header …`, bên dưới). Đặt token ở env server thì thành **single-account** chung cho mọi người trên URL đó.
+
+### Test ở local (không cần URL public)
+
+`localhost` không dùng được trong dialog claude.ai (Anthropic gọi URL từ server của họ). Để thử server `serve`
+chạy trên máy:
+
+- **MCP Inspector** (GUI — dễ nhất): `npx @modelcontextprotocol/inspector` → Transport **Streamable HTTP** →
+  URL `http://localhost:8787/mcp` → mục Headers thêm `x-webcake-jwt` (+ `x-webcake-api-base`) → Connect → bấm gọi tool.
+- **`mcp-remote`** (dùng server remote từ client stdio như Claude Desktop, kèm header):
+  ```json
+  { "mcpServers": { "webcake-remote": { "command": "npx",
+    "args": ["-y", "mcp-remote", "http://localhost:8787/mcp",
+             "--header", "x-webcake-jwt:<ljwt>",
+             "--header", "x-webcake-api-base:https://api.webcake.io"] } } }
+  ```
+- **curl**: `initialize` (đọc header `mcp-session-id` trả về) → `tools/list` → `tools/call`, tất cả kèm
+  `Accept: application/json, text/event-stream`.
+
+### Deploy lên VPS
+
+1. **Build + chạy như service** — `/etc/systemd/system/webcake-mcp.service`:
+   ```ini
+   [Service]
+   WorkingDirectory=/opt/webcake-landing-mcp
+   ExecStart=/usr/bin/node dist/index.js serve --port 8787
+   Environment=WEBCAKE_API_BASE=https://api.webcake.io
+   Environment=WEBCAKE_JWT=<ljwt>          # chỉ cho single-account — xem ghi chú auth dưới
+   Restart=always
+   [Install]
+   WantedBy=multi-user.target
+   ```
+   `sudo systemctl enable --now webcake-mcp` (build 1 lần: `npm install && npm run build`).
+2. **HTTPS + domain** (claude.ai bắt buộc https) — vd Caddy tự cấp TLS, `/etc/caddy/Caddyfile`:
+   ```
+   mcp.yourdomain.com { reverse_proxy localhost:8787 }
+   ```
+3. **Thêm vào claude.ai** → Remote MCP server URL = `https://mcp.yourdomain.com/mcp`.
+
+**Auth trên server chia sẻ:**
+- **Single-account** (dùng được với dialog ngay): đặt `WEBCAKE_JWT` ở env service → mọi người dùng connector
+  chung 1 tài khoản Webcake. Giữ URL riêng tư / có cổng chặn; token hết hạn (~90 ngày).
+- **Per-user** (mỗi người 1 account): cho mỗi người một URL với `?jwt=<ljwt>` riêng (chạy được qua dialog,
+  nhưng token lộ trong log), hoặc dùng client hỗ trợ header (`mcp-remote --header …`), hoặc thêm **OAuth**
+  (chưa làm) cho gọn nhất.
+
 ## Cài thủ công (local)
 
 ```bash
@@ -197,6 +291,55 @@ npm run smoke      # self-test offline của factory + validator (in "ALL GOOD")
 Các tool tham chiếu/kiểm tra chạy với **zero config**. Biến môi trường chỉ cần cho các tool lưu trữ
 (`create_page`, `update_page`, `list_pages`, `get_page`, `list_organizations`).
 
+## Kết nối một lần — tự lấy token (`login`)
+
+Thay vì copy JWT bằng tay, chạy:
+
+```bash
+# Production — zero config (mặc định: connect qua webcake.io, API qua api.webcake.io):
+npx -y webcake-landing-mcp login
+
+# Local dev — trỏ vào SPA (5173) + API (5800) ở máy:
+node dist/index.js login \
+  --connect-url http://localhost:5173/mcp-connect \
+  --api-base http://localhost:5800
+```
+
+Nó mở browser → (đăng nhập Webcake nếu cần) → token được lưu vào
+`~/.webcake-landing-mcp/auth.json`, server tự đọc.
+
+Bạn đang đăng nhập Webcake sẵn trong browser, nên `login` chỉ mở trang "connect" của Webcake — trang này
+đọc cookie **`ljwt`** (landing) và trả token về một callback loopback nội bộ — khỏi copy-paste. Token đã lưu
+được dùng bởi **cả** server stdio lẫn deploy `serve` một-người-dùng (env vẫn ưu tiên). Landing JWT sống ~90
+ngày nên hiếm khi phải kết nối lại.
+
+Hai URL, đừng nhầm:
+
+- **Trang connect = SPA** (`--connect-url` / `WEBCAKE_CONNECT_URL`): `https://webcake.io/mcp-connect` ở prod,
+  `http://localhost:5173/mcp-connect` ở local. Nếu không, suy ra từ `WEBCAKE_APP_BASE` + `/mcp-connect`,
+  mặc định `https://webcake.io/mcp-connect`.
+- **API base = backend** (`--api-base` / `WEBCAKE_API_BASE`): `https://api.webcake.io` ở prod,
+  `http://localhost:5800` ở local. Mặc định `https://api.webcake.io`.
+
+Cờ khác: `--org-id`, `--port`, `--no-open`. Thư mục file lưu: `WEBCAKE_CONFIG_DIR` (mặc định
+`~/.webcake-landing-mcp`).
+
+**Endpoint cần thêm ở backend** (trong Webcake backend — nơi giữ cookie session):
+
+```
+GET /mcp-connect?redirect_uri=<loopback>&state=<s>
+   → đọc cookie `ljwt` (landing token của user đang đăng nhập)
+   → 302 tới  <redirect_uri>?token=<ljwt>&state=<s>
+   (nếu chưa có cookie: 302 sang trang login trước, xong quay lại đây)
+```
+
+Để an toàn, chỉ chấp nhận `redirect_uri` ở `http://127.0.0.1:*` / `http://localhost:*`.
+(Mẫu tham khảo: `builderx_spa/src/views/McpConnect.vue` đọc `cookies.get('ljwt')` — nên flow này làm hẳn ở
+SPA cũng được, khỏi cần route backend.)
+
+> Remote đa người dùng (dialog claude.ai) không làm được browser loopback này — ở đó mỗi user gửi token riêng
+> qua header `x-webcake-jwt` (xem mục remote-connector ở trên).
+
 ## Biến môi trường
 
 | Biến | Bắt buộc | Mô tả |
@@ -206,6 +349,8 @@ Các tool tham chiếu/kiểm tra chạy với **zero config**. Biến môi trư
 | `WEBCAKE_ORG_ID` | Không | Organization mặc định cho `create_page` (bị ghi đè bởi tham số `organization_id`). Bỏ trống → trang cá nhân. |
 | `WEBCAKE_HOST` | Không | Header `Host` tuỳ chọn (Phoenix route theo host, ví dụ `builder.localhost`). |
 | `WEBCAKE_APP_BASE` | Không | Base tuỳ chọn để dựng URL editor/preview trong kết quả. |
+| `WEBCAKE_CONNECT_URL` | Không | Trang "connect" (SPA) cho `login` (mặc định `https://webcake.io/mcp-connect`; nếu không thì `WEBCAKE_APP_BASE` + `/mcp-connect`). |
+| `WEBCAKE_CONFIG_DIR` | Không | Thư mục chứa `auth.json` do `login` ghi (mặc định `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` và `WEBCAKE_JWT` chỉ cần cho các tool lưu trữ. Các tool tham chiếu và kiểm tra
 > (`get_generation_guide`, `list_elements`, `get_element`, `validate_page`, …) chạy không cần chúng.

package/dist/auth/login.js

@@ -0,0 +1,115 @@
+/**
+ * `webcake-landing-mcp login` — grab the user's Webcake JWT automatically via the
+ * browser, no copy-paste.
+ *
+ * Flow (works for local stdio AND a single-user remote deploy):
+ *   1. open a loopback server on 127.0.0.1:<port>,
+ *   2. open the browser to the Webcake "connect" URL with redirect_uri=<loopback>,
+ *   3. the user is already logged in to Webcake, so Webcake reads their `jwt`
+ *      cookie server-side and 302s back to the loopback with ?token=<jwt>,
+ *   4. we save it to the credentials file (persistence/config.ts#saveSavedConfig),
+ *      which the stdio/http server then reads automatically.
+ *
+ * Backend contract (added to landing_page_backend — owned by the user):
+ *   GET {WEBCAKE_CONNECT_URL}?redirect_uri=<loopback>&state=<s>
+ *     → read cookie `jwt` → 302 to <redirect_uri>?token=<jwt>&state=<s>
+ *       (or 302 to the login page first, then back). Restrict redirect_uri to
+ *       http://127.0.0.1:* / http://localhost:* for safety.
+ */
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { saveSavedConfig } from "../persistence/config.js";
+// Production defaults — the connect page lives on the SPA (webcake.io), the API
+// lives on api.webcake.io. For local dev override with --connect-url / --api-base
+// (e.g. http://localhost:5173/mcp-connect and http://localhost:5800) or the
+// WEBCAKE_APP_BASE / WEBCAKE_API_BASE env vars.
+const DEFAULT_CONNECT_URL = "https://webcake.io/mcp-connect";
+const DEFAULT_API_BASE = "https://api.webcake.io";
+function parseArgs(argv) {
+    const get = (name) => {
+        const i = argv.indexOf(name);
+        return i !== -1 ? argv[i + 1] : undefined;
+    };
+    return {
+        connectUrl: get("--connect-url"),
+        apiBase: get("--api-base"),
+        orgId: get("--org-id"),
+        port: get("--port") ? Number(get("--port")) : undefined,
+        open: !argv.includes("--no-open"),
+    };
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        /* ignore — the URL is also printed */
+    }
+}
+const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>Connected</title>
+<body style="font-family:system-ui;text-align:center;padding:48px">
+<h2>✓ Connected to Webcake</h2><p>You can close this tab and return to your terminal.</p></body>`;
+function resolveConnectUrl(opts) {
+    if (opts.connectUrl)
+        return opts.connectUrl;
+    if (process.env.WEBCAKE_CONNECT_URL)
+        return process.env.WEBCAKE_CONNECT_URL;
+    // The connect page is on the SPA (WEBCAKE_APP_BASE), NOT the API base.
+    const appBase = process.env.WEBCAKE_APP_BASE;
+    if (appBase)
+        return `${appBase.replace(/\/+$/, "")}/mcp-connect`;
+    return DEFAULT_CONNECT_URL;
+}
+export async function runLogin(argv) {
+    const opts = parseArgs(argv);
+    const connectUrl = resolveConnectUrl(opts);
+    const apiBase = opts.apiBase || process.env.WEBCAKE_API_BASE || DEFAULT_API_BASE;
+    const state = randomBytes(16).toString("hex");
+    await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url || "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end("Not found");
+                return;
+            }
+            const token = url.searchParams.get("token");
+            if (!token || url.searchParams.get("state") !== state) {
+                res.writeHead(400, { "content-type": "text/html" }).end("<p>Invalid or expired login — re-run the command.</p>");
+                return;
+            }
+            const path = saveSavedConfig({
+                jwt: token,
+                ...(apiBase ? { base: apiBase.replace(/\/+$/, "") } : {}),
+                ...(opts.orgId ? { orgId: opts.orgId } : {}),
+                savedAt: new Date().toISOString(),
+            });
+            res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_HTML);
+            console.error(`\n✓ Connected. Token saved to ${path}`);
+            if (!apiBase) {
+                console.error("  tip: also set WEBCAKE_API_BASE (or pass --api-base) so the server knows the backend URL.");
+            }
+            server.close();
+            resolve();
+        });
+        server.on("error", reject);
+        server.listen(opts.port ?? 0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : opts.port;
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const sep = connectUrl.includes("?") ? "&" : "?";
+            const full = `${connectUrl}${sep}redirect_uri=${encodeURIComponent(redirectUri)}&state=${state}`;
+            console.error("Opening your browser to connect to Webcake (log in there if prompted):");
+            console.error("  " + full + "\n");
+            if (opts.open)
+                openBrowser(full);
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new Error("login timed out after 180s."));
+        }, 180_000).unref();
+    });
+}

package/dist/http.js

@@ -0,0 +1,118 @@
+/**
+ * Remote transport: a Streamable-HTTP server so the MCP can be added as a Claude
+ * "custom connector" via a public URL — alongside the stdio mode in index.ts.
+ *
+ * Stateful sessions: an `initialize` POST (no session id) spins up a fresh
+ * McpServer + transport and returns an `mcp-session-id`; later requests reuse it
+ * via that header. Each request carries the caller's OWN Webcake JWT — via a header
+ * (x-webcake-jwt / Authorization) OR a URL query param (.../mcp?jwt=<token>, for
+ * clients like the claude.ai dialog that can't set headers; see applyQueryAuth +
+ * persistence/config.ts#configFromHeaders). So a hosted server is multi-user.
+ *
+ * All logging stays on stderr (console.error), same as stdio mode.
+ */
+import { randomUUID } from "node:crypto";
+import { createServer as createHttpServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "./server.js";
+const MCP_PATH = "/mcp";
+function sendJson(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function rpcError(res, status, message) {
+    sendJson(res, status, { jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    return raw ? JSON.parse(raw) : undefined;
+}
+// Map credentials passed in the URL query (e.g. .../mcp?jwt=<token>) onto the
+// x-webcake-* headers so the normal per-request config path handles them. This is
+// for clients that can't set custom headers — notably the claude.ai connector
+// dialog, which only takes a URL. An explicit header always wins over the query.
+// SECURITY: a token in the URL can land in access/proxy logs — prefer headers,
+// require HTTPS, and disable query-string logging on your reverse proxy.
+const QUERY_AUTH = {
+    jwt: "x-webcake-jwt",
+    api_base: "x-webcake-api-base",
+    org_id: "x-webcake-org-id",
+    host: "x-webcake-host",
+    app_base: "x-webcake-app-base",
+};
+function applyQueryAuth(req) {
+    const q = (req.url ?? "").indexOf("?");
+    if (q === -1)
+        return;
+    const params = new URLSearchParams((req.url ?? "").slice(q + 1));
+    for (const [param, header] of Object.entries(QUERY_AUTH)) {
+        const value = params.get(param);
+        // Only fill in when there's no explicit header (header wins). The transport
+        // builds its Request from `req.rawHeaders` (via @hono/node-server), so we MUST
+        // push there — mutating `req.headers` alone is not seen by the tool handlers.
+        if (value && req.headers[header] == null) {
+            req.headers[header] = value;
+            req.rawHeaders.push(header, value);
+        }
+    }
+}
+export async function startHttpServer(port) {
+    // mcp-session-id -> live transport (each bound to its own McpServer instance).
+    const transports = new Map();
+    const httpServer = createHttpServer(async (req, res) => {
+        const path = (req.url ?? "").split("?")[0];
+        // Lightweight health check for hosting platforms.
+        if (req.method === "GET" && (path === "/" || path === "/health")) {
+            return sendJson(res, 200, { ok: true, server: "webcake-landing", transport: "streamable-http", endpoint: MCP_PATH });
+        }
+        if (path !== MCP_PATH)
+            return rpcError(res, 404, `Not found. Send MCP requests to ${MCP_PATH}.`);
+        // Accept credentials via ?jwt=/?api_base=/... (for clients that can't set headers).
+        applyQueryAuth(req);
+        const sidHeader = req.headers["mcp-session-id"];
+        const sessionId = Array.isArray(sidHeader) ? sidHeader[0] : sidHeader;
+        try {
+            // Existing session: delegate any method (POST/GET/DELETE) to its transport.
+            if (sessionId && transports.has(sessionId)) {
+                const transport = transports.get(sessionId);
+                const body = req.method === "POST" ? await readBody(req) : undefined;
+                await transport.handleRequest(req, res, body);
+                return;
+            }
+            // New session: only a POST `initialize` may open one.
+            if (req.method === "POST") {
+                const body = await readBody(req);
+                if (!sessionId && isInitializeRequest(body)) {
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: (id) => {
+                            transports.set(id, transport);
+                        },
+                    });
+                    transport.onclose = () => {
+                        if (transport.sessionId)
+                            transports.delete(transport.sessionId);
+                    };
+                    const server = createServer();
+                    await server.connect(transport);
+                    await transport.handleRequest(req, res, body);
+                    return;
+                }
+                return rpcError(res, 400, "Bad Request: no valid mcp-session-id (send an initialize request first).");
+            }
+            return rpcError(res, 400, "Bad Request: missing or unknown mcp-session-id.");
+        }
+        catch (err) {
+            console.error("[webcake-http] request error:", err);
+            if (!res.headersSent)
+                rpcError(res, 500, "Internal server error.");
+        }
+    });
+    await new Promise((resolve) => httpServer.listen(port, resolve));
+    // stderr only.
+    console.error(`[webcake-elements] MCP Streamable-HTTP server ready on http://localhost:${port}${MCP_PATH}`);
+}

package/dist/index.js

@@ -2,11 +2,16 @@
 /**
  * Webcake landing MCP server (stdio) — entry point.
  *
- * Thin dispatcher: `webcake-landing-mcp install|uninstall|--help` runs the
- * bundled IDE installer; otherwise it starts the stdio MCP server. The server
- * itself (McpServer + tool registration) is built in ./server.ts; the knowledge,
- * factory, validator, and HTTP client live under ./core, ./domains, ./tools, and
- * ./persistence.
+ * Thin dispatcher:
+ *   - `webcake-landing-mcp install|uninstall|--help` → bundled IDE installer
+ *   - `webcake-landing-mcp login` → grab the Webcake JWT via the browser and save it
+ *     (~/.webcake-landing-mcp/auth.json); see ./auth/login.ts
+ *   - `webcake-landing-mcp serve [--port N]` (or PORT env) → remote Streamable-HTTP
+ *     server (for Claude "custom connector" via a public URL); see ./http.ts
+ *   - no subcommand → stdio MCP server (the default; for desktop/CLI configs)
+ * The server itself (McpServer + tool registration) is built in ./server.ts; the
+ * knowledge, factory, validator, and HTTP client live under ./core, ./domains,
+ * ./tools, and ./persistence.
  *
  * stdout is the MCP channel — all logging goes to stderr (console.error) only.
  */
@@ -27,6 +32,19 @@ async function main() {
         await runInstaller(rest);
         return;
     }
+    if (sub === "login") {
+        const { runLogin } = await import("./auth/login.js");
+        await runLogin(process.argv.slice(3));
+        return;
+    }
+    if (sub === "serve" || sub === "http" || sub === "serve-http") {
+        const { startHttpServer } = await import("./http.js");
+        const flagIdx = process.argv.indexOf("--port");
+        const raw = (flagIdx !== -1 ? process.argv[flagIdx + 1] : undefined) ?? process.env.PORT;
+        const port = Number(raw);
+        await startHttpServer(Number.isFinite(port) && port > 0 ? port : 8787);
+        return;
+    }
     const transport = new StdioServerTransport();
     const server = createServer();
     await server.connect(transport);

package/dist/persistence/config.js

@@ -1,6 +1,31 @@
-export function readConfig() {
-    const base = process.env.WEBCAKE_API_BASE;
-    const jwt = process.env.WEBCAKE_JWT;
+/**
+ * Resolve the persistence config. Three sources, in priority order:
+ *  1. per-request `overrides` (remote/Streamable-HTTP mode: each client sends its
+ *     OWN Webcake JWT via HTTP headers — see `configFromHeaders` — so a hosted
+ *     server is multi-user and never bakes a shared secret into env), then
+ *  2. environment variables (stdio / single-user mode), then
+ *  3. the saved credentials file written by `webcake-landing-mcp login`
+ *     (~/.webcake-landing-mcp/auth.json) — so a user can connect once via the
+ *     browser instead of pasting a token.
+ *
+ * The JWT is never hard-coded (the repo is public). `readConfig` returns
+ * { config: null, missing } when required values are absent so the persistence
+ * tools can report exactly what to provide.
+ *
+ *   WEBCAKE_API_BASE  e.g. http://localhost:5800   (required to call the backend)
+ *   WEBCAKE_JWT       the account JWT               (required to call the backend)
+ *   WEBCAKE_ORG_ID    optional default organization id for create_page
+ *   WEBCAKE_HOST      optional Host header override (Phoenix routes by host)
+ *   WEBCAKE_APP_BASE  optional base for editor/preview URLs in the result
+ *   WEBCAKE_CONFIG_DIR  optional dir for the saved auth.json (default ~/.webcake-landing-mcp)
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+export function readConfig(overrides = {}) {
+    const saved = readSavedConfig();
+    const base = overrides.base ?? process.env.WEBCAKE_API_BASE ?? saved.base;
+    const jwt = overrides.jwt ?? process.env.WEBCAKE_JWT ?? saved.jwt;
     const missing = [];
     if (!base)
         missing.push("WEBCAKE_API_BASE");
@@ -12,10 +37,60 @@ export function readConfig() {
         config: {
             base: base.replace(/\/+$/, ""),
             jwt: jwt,
-            orgId: process.env.WEBCAKE_ORG_ID,
-            host: process.env.WEBCAKE_HOST,
-            appBase: process.env.WEBCAKE_APP_BASE?.replace(/\/+$/, ""),
+            orgId: overrides.orgId ?? process.env.WEBCAKE_ORG_ID ?? saved.orgId,
+            host: overrides.host ?? process.env.WEBCAKE_HOST ?? saved.host,
+            appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? saved.appBase)?.replace(/\/+$/, ""),
         },
         missing: [],
     };
 }
+function header(headers, name) {
+    const v = headers?.[name];
+    return Array.isArray(v) ? v[0] : v ?? undefined;
+}
+/**
+ * Build request-scoped config overrides from HTTP headers. Lets a remote client
+ * send its own credentials per request instead of a server-wide env token:
+ *   x-webcake-jwt        the account JWT (or `Authorization: Bearer <jwt>`)
+ *   x-webcake-org-id     organization id
+ *   x-webcake-api-base   backend base URL (usually set once via env instead)
+ *   x-webcake-host       Host header override
+ *   x-webcake-app-base   editor/preview URL base
+ * Any header that is absent falls back to the corresponding env var in readConfig.
+ */
+export function configFromHeaders(headers) {
+    const auth = header(headers, "authorization");
+    const bearer = auth && /^Bearer\s+/i.test(auth) ? auth.replace(/^Bearer\s+/i, "").trim() : undefined;
+    return {
+        base: header(headers, "x-webcake-api-base"),
+        jwt: header(headers, "x-webcake-jwt") ?? bearer,
+        orgId: header(headers, "x-webcake-org-id"),
+        host: header(headers, "x-webcake-host"),
+        appBase: header(headers, "x-webcake-app-base"),
+    };
+}
+/** Directory for the saved auth file (override with WEBCAKE_CONFIG_DIR). */
+export function configDir() {
+    return process.env.WEBCAKE_CONFIG_DIR || join(homedir(), ".webcake-landing-mcp");
+}
+export function savedConfigPath() {
+    return join(configDir(), "auth.json");
+}
+/** Read the saved credentials; {} when the file is absent or unreadable. */
+export function readSavedConfig() {
+    try {
+        const parsed = JSON.parse(readFileSync(savedConfigPath(), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge + persist credentials to the saved file (0600). Returns the path written. */
+export function saveSavedConfig(partial) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true });
+    const path = savedConfigPath();
+    writeFileSync(path, JSON.stringify({ ...readSavedConfig(), ...partial }, null, 2), { mode: 0o600 });
+    return path;
+}

package/dist/tools/persistence.js

@@ -4,21 +4,27 @@
  * default to dry_run=true and return a JWT-redacted request preview; they only
  * hit the network when dry_run===false. Validation uses the injected Domain;
  * the HTTP calls go through the Webcake client.
+ *
+ * Credentials resolve per request: in remote/Streamable-HTTP mode each call's
+ * headers (extra.requestInfo.headers) carry the client's own Webcake JWT, so a
+ * hosted server is multi-user; in stdio/single-user mode they come from env.
  */
 import { z } from "zod";
 import { text } from "../mcp/response.js";
-import { readConfig } from "../persistence/config.js";
+import { readConfig, configFromHeaders } from "../persistence/config.js";
 import { buildRequestRedacted, buildUpdateRequestRedacted, createPage, listOrganizations, listPages, getPageSource, updatePageSource, } from "../persistence/webcake-client.js";
 export function registerPersistenceTools(server, domain) {
+    // Resolve config from THIS request's headers (remote per-user JWT) first, then env.
+    const cfgFor = (extra) => readConfig(configFromHeaders(extra?.requestInfo?.headers));
     // 8) List organizations -----------------------------------------------------
-    server.tool("list_organizations", "List the account's Webcake organizations (id, name, is_default). The default org (type===1, usually the personal workspace) is where pages normally go. Call this BEFORE create_page, show the options to the user and ask which org to use — defaulting to the is_default one. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {}, async () => {
-        const { config, missing } = readConfig();
+    server.tool("list_organizations", "List the account's Webcake organizations (id, name, is_default). The default org (type===1, usually the personal workspace) is where pages normally go. Call this BEFORE create_page, show the options to the user and ask which org to use — defaulting to the is_default one. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {}, async (_args, extra) => {
+        const { config, missing } = cfgFor(extra);
         if (!config) {
             return text({
                 ok: false,
                 reason: "missing_env",
                 missing_env: missing,
-                hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT in the MCP server env.",
+                hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT in the MCP server env (stdio), or send the JWT via the x-webcake-jwt header (remote).",
             });
         }
         return text(await listOrganizations(config));
@@ -37,7 +43,7 @@ export function registerPersistenceTools(server, domain) {
             .boolean()
             .optional()
             .describe("Default TRUE — preview the request without sending. Set false to actually create."),
-    }, async ({ source, name, organization_id, dry_run }) => {
+    }, async ({ source, name, organization_id, dry_run }, extra) => {
         const pageName = name ?? "AI Page";
         const isDry = dry_run !== false; // default true (safe)
         const orgId = organization_id != null ? `${organization_id}` : undefined;
@@ -52,7 +58,7 @@ export function registerPersistenceTools(server, domain) {
             });
         }
         const parsed = domain.coerce(source);
-        const { config, missing } = readConfig();
+        const { config, missing } = cfgFor(extra);
         if (isDry) {
             return text({
                 dry_run: true,
@@ -63,7 +69,7 @@ export function registerPersistenceTools(server, domain) {
                 request: config
                     ? buildRequestRedacted(config, pageName, parsed, orgId)
                     : {
-                        note: "Set WEBCAKE_API_BASE + WEBCAKE_JWT to enable real creation. Would POST to {WEBCAKE_API_BASE}/api/v1/ai/create_page_from_source.",
+                        note: "Set WEBCAKE_API_BASE + WEBCAKE_JWT (env) or send the x-webcake-jwt header to enable real creation. Would POST to {WEBCAKE_API_BASE}/api/v1/ai/create_page_from_source.",
                     },
                 hint: "Re-run with dry_run=false to actually create the page.",
             });
@@ -73,22 +79,22 @@ export function registerPersistenceTools(server, domain) {
                 created: false,
                 reason: "missing_env",
                 missing_env: missing,
-                hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT in the MCP server env, then retry.",
+                hint: "Configure WEBCAKE_API_BASE and WEBCAKE_JWT (env), or send the x-webcake-jwt header (remote), then retry.",
             });
         }
         const outcome = await createPage(config, pageName, parsed, orgId);
         return text({ created: outcome.ok, ...outcome, warnings: result.warnings });
     });
     // 10) List pages ------------------------------------------------------------
-    server.tool("list_pages", "List the pages owned by the account (id, name, organization_id, updated_at), most-recent first. Use it to let the user pick a page to edit (then get_page → modify → update_page). Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {}, async () => {
-        const { config, missing } = readConfig();
+    server.tool("list_pages", "List the pages owned by the account (id, name, organization_id, updated_at), most-recent first. Use it to let the user pick a page to edit (then get_page → modify → update_page). Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {}, async (_args, extra) => {
+        const { config, missing } = cfgFor(extra);
         if (!config)
             return text({ ok: false, reason: "missing_env", missing_env: missing });
         return text(await listPages(config));
     });
     // 11) Get page (read source) ------------------------------------------------
-    server.tool("get_page", "Fetch an existing page's decoded source tree { page, popup, settings, options, cartConfigs } so you can EDIT it. Returns name + organization_id too. Edit the returned `source`, then validate_page and update_page. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", { page_id: z.string().describe("The page id (from list_pages or a URL).") }, async ({ page_id }) => {
-        const { config, missing } = readConfig();
+    server.tool("get_page", "Fetch an existing page's decoded source tree { page, popup, settings, options, cartConfigs } so you can EDIT it. Returns name + organization_id too. Edit the returned `source`, then validate_page and update_page. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", { page_id: z.string().describe("The page id (from list_pages or a URL).") }, async ({ page_id }, extra) => {
+        const { config, missing } = cfgFor(extra);
         if (!config)
             return text({ ok: false, reason: "missing_env", missing_env: missing });
         return text(await getPageSource(config, page_id));
@@ -100,7 +106,7 @@ export function registerPersistenceTools(server, domain) {
             .any()
             .describe("The full edited page source { page, popup, settings, options, cartConfigs } (object or JSON string)."),
         dry_run: z.boolean().optional().describe("Default TRUE — preview without sending. Set false to actually save."),
-    }, async ({ page_id, source, dry_run }) => {
+    }, async ({ page_id, source, dry_run }, extra) => {
         const isDry = dry_run !== false;
         const result = domain.validate(source);
         if (!result.valid) {
@@ -113,7 +119,7 @@ export function registerPersistenceTools(server, domain) {
             });
         }
         const parsed = domain.coerce(source);
-        const { config, missing } = readConfig();
+        const { config, missing } = cfgFor(extra);
         if (isDry) {
             return text({
                 dry_run: true,
@@ -123,7 +129,7 @@ export function registerPersistenceTools(server, domain) {
                 missing_env: missing,
                 request: config
                     ? buildUpdateRequestRedacted(config, page_id, parsed)
-                    : { note: "Set WEBCAKE_API_BASE + WEBCAKE_JWT to enable real updates." },
+                    : { note: "Set WEBCAKE_API_BASE + WEBCAKE_JWT (env) or send the x-webcake-jwt header to enable real updates." },
                 hint: "Re-run with dry_run=false to actually save the edit.",
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "type": "module",
   "bin": {