@cloudgrid-io/mcp 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "smoke:redrop": "node test/smoke-redrop.mjs",
     "smoke:oauth": "node test/smoke-oauth.mjs",
     "test:auth": "node test/auth.test.mjs",
+    "test:win-cli": "node test/windows-cli-resolution.test.mjs",
     "smoke:docs": "node test/smoke-docs.mjs",
     "start:docs": "node src/docs.js",
     "snapshot:corpus": "node scripts/snapshot-corpus.mjs",

package/src/corpus/cookbook.md

@@ -67,14 +67,14 @@ cloudgrid feedback list
 The fastest chain has one step and no login. Drop an HTML file, get a public URL:
 
 ```
-curl -sS -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
   -F "artifact=@./index.html;type=text/html"
 ```
 
-The response includes `url` (the live link) and `claim_url` (sign in within 7 days
-to keep it). This is what the `cloudgrid-drop` skill and the `cloudgrid_drop` MCP
-tool do for you. It is anonymous and serves inspirations only; a full app needs the
-signed-in `plug` flow above.
+The response includes `slug` (the live link is `https://guest.cloudgrid.io/<slug>`)
+and `claim_url` (sign in within 7 days to keep it). This is what the `cloudgrid-drop`
+skill and the `cloudgrid_drop` MCP tool do for you. It is anonymous and serves
+inspirations only; a full app needs the signed-in `plug` flow above.
 
 ## Shorter chains
 

package/src/corpus/skill-claim.md

@@ -4,7 +4,8 @@ name: claim
 description: |
   Claim an anonymous CloudGrid drop into the user's account. Use when the user
   dropped something anonymously and now wants to keep it, own it, or stop it from
-  expiring after signing in. The public URL does not change.
+  expiring after signing in. Ownership transfers to the user and the drop re-homes
+  into their grid, so its public URL changes.
 argument-hint: "[claim-url-or-token]"
 allowed-tools: Bash
 ---
@@ -12,9 +13,10 @@ allowed-tools: Bash
 # CloudGrid Claim
 
 Turn an anonymous drop into an owned one. After an anonymous drop, the user has a
-`claim_url` (or token). Once they sign in, claiming transfers ownership to them and
-extends the expiry from 7 days to 30. The shareable URL stays the same, so any link
-already shared keeps working.
+`claim_url` (or token) plus the drop's `entity_id`. Once they sign in, claiming
+transfers ownership to them and extends the expiry from 7 days to 30. Claiming
+re-homes the drop into the user's grid, so its public URL changes from
+`guest.cloudgrid.io/<slug>` to `<grid>.cloudgrid.io/<slug>` — share the new link.
 
 ## Step 0 — sign in first
 
@@ -23,31 +25,43 @@ skill (or `cloudgrid login` with the CLI) first.
 
 ## What you need
 
-The claim token from the anonymous drop. It is the `token` query parameter inside
-the `claim_url` the drop returned, for example
-`https://console.cloudgrid.io/claim?token=<TOKEN>`.
+Two things: the **entity id** of the anonymous drop (the `entity_id` field the drop
+returned), and the **claim token** — the `token` query parameter inside the
+`claim_url` the drop returned, e.g. `https://console.cloudgrid.io/claim?token=<TOKEN>`.
+A browser that still holds the `cg_anon_session` cookie from the drop can claim
+without a token instead.
 
 ## How to run it
 
+Claiming is now a "pickup" of the entity into your grid. The entity id goes in the
+URL path; the claim token goes in the body:
+
 ```
 JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
-# TOKEN is the claim token (from claim_url's ?token=...)
-curl -sS -X POST https://api.cloudgrid.io/api/v2/anon-claim \
-  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
+ORG=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
+# ENTITY_ID from the drop response; TOKEN from claim_url's ?token=...
+curl -sS -X POST "https://api.cloudgrid.io/api/v2/entities/$ENTITY_ID/pickup" \
+  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Org: $ORG" \
+  -H "Content-Type: application/json" \
   -d "{\"claim_token\":\"$TOKEN\"}"
 ```
 
-The response is `{ "claimed": [ { "url", "new_expires_at" }, ... ] }`.
+A successful claim returns HTTP 200 with `{ entity_id, slug, grid, url,
+new_expires_at, role_granted: "owner", ... }`.
 
 ## Reading the result
 
-- A non-empty `claimed` list means it worked. Tell the user the drop is now theirs,
-  the URL is unchanged, and the new expiry.
-- An empty `claimed` list means there was nothing to claim — it may already be
-  claimed or expired. Say so plainly.
+- HTTP 200 means it worked. Ownership transferred to the user; tell them the drop is
+  now theirs and give them the new `url` and `new_expires_at`. NOTE: claiming
+  re-homes the inspiration into the user's grid, so the public URL CHANGES from
+  `guest.cloudgrid.io/<slug>` to `<grid>.cloudgrid.io/<slug>` — share the new one.
+- HTTP 409 `ALREADY_CLAIMED` means there was nothing left to claim — it was already
+  picked up. Say so plainly.
+- HTTP 403 `CLAIM_TOKEN_REQUIRED` / `INVALID_CLAIM_TOKEN` means the token is missing,
+  wrong, or expired (and no owning cookie was sent).
 
 ## Notes
 
-- One token claims one drop. To claim several, repeat with each token.
-- The MCP `cloudgrid_claim` tool does this for you, and remembers the token from the
-  last anonymous drop so you can claim with no arguments.
+- One pickup claims one entity. To claim several, repeat with each entity id + token.
+- The MCP `cloudgrid_claim` tool does this for you, and remembers the entity id +
+  token from the last anonymous drop so you can claim with no arguments.

package/src/corpus/skill-drop.md

@@ -41,17 +41,21 @@ first. The content must be a full HTML document (start with `<!doctype html>` or
 `<html>`); if you only have a fragment, wrap it in a minimal document. HTML is
 capped at 2 MB for anonymous drops.
 
-Then POST it:
+Then POST it to the unified plug endpoint:
 
 ```
-curl -sS -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
   -F "artifact=@/path/to/index.html;type=text/html"
 ```
 
-The response is JSON. Read two fields:
+The response is JSON (HTTP 201 for an anonymous drop). Read these fields:
 
-- `url` — the live, shareable link. Give this to the user.
+- `slug` — the entity's public slug. An anonymous inspiration's live link is
+  `https://guest.cloudgrid.io/<slug>`. The response has no ready-made `url`;
+  compose it from the slug. (Apps/agents would be `https://<slug>.<grid>.cloudgrid.io`,
+  but anonymous drops are always inspirations.)
 - `claim_url` — the link to sign in and keep it past the 7-day expiry.
+- `claim_message` — a ready-to-show nudge to sign in and claim.
 
 ## If the user is signed in
 
@@ -62,45 +66,35 @@ request:
 ```
 JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
 ORG=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
-curl -sS -X POST https://api.cloudgrid.io/api/v2/drop/auto \
+curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
   -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Org: $ORG" \
-  -F "artifact=@/path/to/index.html;type=text/html" -F "org_slug=$ORG"
+  -F "artifact=@/path/to/index.html;type=text/html"
 ```
 
-The response has `owned_by: "authenticated"` and no `claim_url`. If the user is a
-member of several orgs and `X-CloudGrid-Org` is missing, the API replies with the
-list of orgs to choose from. The MCP `cloudgrid_drop` tool does this automatically
-when credentials are present.
-
-## Re-dropping (update in place)
-
-A re-drop of the same artifact updates it in place — same URL, new version, views
-and reactions intact. The platform matches ownership through the anon-session
-cookie, so keep a cookie jar across drops:
-
-```
-curl -sS -c jar.txt -X POST https://api.cloudgrid.io/api/v2/drop/auto \
-  -F "artifact=@index.html;type=text/html"                      # first drop
-curl -sS -b jar.txt -X POST https://api.cloudgrid.io/api/v2/drop/auto \
-  -F "previous_id=<entity_id from the first response>" \
-  -F "artifact=@index.html;type=text/html"                      # re-drop
-```
+A signed-in drop returns HTTP 202 with `slug` + `grid` and no `claim_url` (it is
+already owned). Its live link is `https://<grid>.cloudgrid.io/<slug>` for an
+inspiration. The org is taken from the `X-CloudGrid-Org` header — there is no
+`org_slug` form field. If the user is a member of several orgs and the header is
+missing, the API replies with the list of orgs to choose from. The MCP
+`cloudgrid_drop` tool does this automatically when credentials are present.
 
-Send `previous_id` before the artifact part. Read the status:
+## One drop = one entity (no in-place re-drop)
 
-- `200` — updated in place; the same `url` now serves the new bytes.
-- `202` — no change; this exact content is already live.
-- `201` — created new: no `previous_id`, or the previous drop was claimed, expired,
-  or not yours — the server falls back to create and never hard-fails.
+The unified `/api/v2/plug` endpoint is create-only for this flow: every drop mints
+a NEW entity with a NEW URL. There is no `previous_id` / in-place-update path and no
+`202 unchanged` no-op — those belonged to the retired `/drop/auto` endpoint. To
+publish an update, drop again; you get a fresh link. (To update an existing app in
+place, sign in and use `cloudgrid:plug`, which targets the entity by name.)
 
-Omit `previous_id` to start a separate new drop. The MCP `cloudgrid_drop` tool does
-all of this for you (re-drops update in place; `fresh: true` forces a new one).
+The MCP `cloudgrid_drop` tool accepts a `fresh` flag for backward compatibility,
+but it is now a no-op — each drop is already a fresh create.
 
 ## After the drop
 
-Print the `url` on its own line, by itself, so it can be copied in one go. Then add
-one line of context: an anonymous drop lasts 7 days and can be claimed to keep it;
-a signed-in drop is already owned. Do not bury the URL in prose.
+Print the composed `url` (e.g. `https://guest.cloudgrid.io/<slug>`) on its own line,
+by itself, so it can be copied in one go. Then add one line of context: an anonymous
+drop lasts 7 days and can be claimed to keep it; a signed-in drop is already owned.
+Do not bury the URL in prose.
 
 ## Limits and errors
 

package/src/tools.js

@@ -13,6 +13,7 @@ import { promisify } from "node:util";
 import { readFile } from "node:fs/promises";
 import { readFileSync, existsSync, statSync } from "node:fs";
 import { basename, dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { newLoginCode, buildLoginUrl, pollStatusOnce, decodeJwt } from "./auth.js";
 
@@ -125,20 +126,67 @@ function meetsMinVersion(version) {
 // Resolve the bundled CLI from this package's OWN node_modules only — never
 // walk up to parent directories (which may contain stale CLI versions).
 // Returns { entry, version } or null.
-function resolveBundledCli() {
+//
+// `fileURLToPath` (not `new URL(url).pathname`) is required for Windows: on a
+// Windows `file://` URL, `.pathname` is `/C:/Users/.../src` — a leading slash
+// before the drive letter, which is NOT a valid fs path, so `existsSync` fails
+// and the bundled CLI is never found even though the `.mcpb` bundles it.
+// `fileURLToPath` yields a proper `C:\Users\...\src`. macOS/Linux are unaffected.
+//
+// The `deps` seam (moduleUrl + path/fs impls) exists ONLY so the Windows-URL
+// regression test can drive the win32 code path deterministically on a POSIX CI
+// box. Production always uses the real `import.meta.url` and host path/fs.
+export function resolveBundledCli(deps = {}) {
+  const {
+    moduleUrl = import.meta.url,
+    urlToPath = fileURLToPath,
+    pathImpl = { dirname, join },
+    fsExists = existsSync,
+    fsRead = readFileSync,
+  } = deps;
   try {
-    const srcDir = dirname(new URL(import.meta.url).pathname);
-    const pkgPath = join(srcDir, "..", "node_modules", "@cloudgrid-io", "cli", "package.json");
-    if (!existsSync(pkgPath)) return null;
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const srcDir = pathImpl.dirname(urlToPath(moduleUrl));
+    const pkgPath = pathImpl.join(srcDir, "..", "node_modules", "@cloudgrid-io", "cli", "package.json");
+    if (!fsExists(pkgPath)) return null;
+    const pkg = JSON.parse(fsRead(pkgPath, "utf-8"));
     const bin = pkg.bin && pkg.bin.cloudgrid;
     if (!bin) return null;
-    return { entry: join(dirname(pkgPath), bin), version: pkg.version || null };
+    return { entry: pathImpl.join(pathImpl.dirname(pkgPath), bin), version: pkg.version || null };
   } catch {
     return null;
   }
 }
 
+// Windows `.cmd`/`.bat` shims (cloudgrid.cmd, npx.cmd) cannot be launched by
+// `execFile` without a shell — modern patched Node (CVE-2024-27980) rejects it
+// with EINVAL, and even where it doesn't, ENOENT results because the bare name
+// resolves to a `.cmd`. On win32 we route those through `cmd.exe /d /s /c` with
+// an explicitly quoted command line so args with spaces/quotes stay intact.
+// macOS/Linux never take this branch — they keep the plain execFile path.
+const IS_WIN = process.platform === "win32";
+
+// Quote a single Windows command-line token for cmd.exe. Wrap in double quotes,
+// escape embedded quotes/backslash-before-quote per Windows argv rules, and also
+// caret-escape cmd.exe metacharacters so nothing is interpreted by the shell.
+function winQuoteArg(arg) {
+  const s = String(arg);
+  // Escape backslashes that precede a quote, then the quotes themselves.
+  let inner = s.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  inner = `"${inner}"`;
+  // Caret-escape cmd.exe special chars (they live outside the quoted-arg parsing).
+  return inner.replace(/[()%!^"<>&|]/g, "^$&");
+}
+
+// execFile a command that may be a Windows `.cmd` shim, safely on every OS.
+function execMaybeCmd(command, args, options) {
+  if (!IS_WIN) return execFileAsync(command, args, options);
+  const line = [command, ...args].map(winQuoteArg).join(" ");
+  return execFileAsync(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", line], {
+    ...options,
+    windowsVerbatimArguments: true,
+  });
+}
+
 async function runCloudgrid(args, opts = {}) {
   const cwd = resolveCwd(opts.cwd);
   const execOpts = {
@@ -175,11 +223,13 @@ async function runCloudgrid(args, opts = {}) {
     );
   }
 
-  // 2. Global `cloudgrid` on PATH — version-gated
+  // 2. Global `cloudgrid` on PATH — version-gated.
+  //    On Windows the bin is `cloudgrid.cmd`; run it via cmd.exe (execMaybeCmd).
   {
+    const globalBin = IS_WIN ? "cloudgrid.cmd" : "cloudgrid";
     let useGlobal = false;
     try {
-      const { stdout: vOut } = await execFileAsync("cloudgrid", ["--version"], {
+      const { stdout: vOut } = await execMaybeCmd(globalBin, ["--version"], {
         timeout: 5_000,
         stdio: ["ignore", "pipe", "pipe"],
       });
@@ -196,7 +246,7 @@ async function runCloudgrid(args, opts = {}) {
     }
     if (useGlobal) {
       try {
-        const { stdout, stderr } = await execFileAsync("cloudgrid", args, execOpts);
+        const { stdout, stderr } = await execMaybeCmd(globalBin, args, execOpts);
         return (stdout || stderr || "").trim() || "Done.";
       } catch (err) {
         throw extract(err);
@@ -206,10 +256,12 @@ async function runCloudgrid(args, opts = {}) {
 
   // 3. Lazy fetch: npx -y @cloudgrid-io/cli@<pinned> <args>
   //    One-time download; npx caches it for subsequent invocations.
+  //    On Windows this is `npx.cmd`, run via cmd.exe (execMaybeCmd) so patched
+  //    Node doesn't EINVAL on the `.cmd` shim.
   console.error("cloudgrid-mcp: fetching the CloudGrid CLI (first use)…");
-  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+  const npx = IS_WIN ? "npx.cmd" : "npx";
   try {
-    const { stdout, stderr } = await execFileAsync(
+    const { stdout, stderr } = await execMaybeCmd(
       npx,
       ["-y", CLI_NPX_PKG, ...args],
       execOpts,
@@ -296,6 +348,32 @@ function looksLikeFullHtml(s) {
   return head.startsWith("<!doctype html") || head.startsWith("<html");
 }
 
+// Anonymous drops are owned by the platform Guest Org, whose slug is the apex
+// the public URL hangs off (https://guest.cloudgrid.io/<slug>).
+const GUEST_ORG_SLUG = "guest";
+
+// Compose an entity's public URL from the `/api/v2/plug` response. Unlike the
+// retired `/drop/auto`, `/plug` does NOT return a `url` field — it returns
+// `slug` + `grid` (+ a `detection.kind`) and expects the client to derive the
+// canonical URL, mirroring the platform's `entityUrl()` URL derivation:
+//   - inspiration (HTML drops): path-based at the org apex
+//       https://<grid>.cloudgrid.io/<slug>
+//   - runtime (app/agent):      subdomain
+//       https://<slug>.<grid>.cloudgrid.io
+// Anonymous drops are grid-less in the response (`grid: null`); they live under
+// the Guest Org, so the apex slug is the constant `guest`.
+function composePlugUrl(data) {
+  const slug = data?.slug;
+  if (!slug) return null;
+  const grid = data?.grid || GUEST_ORG_SLUG;
+  const kind = data?.detection?.kind;
+  if (kind === "app" || kind === "agent") {
+    return `https://${slug}.${grid}.cloudgrid.io`;
+  }
+  // inspiration (and any unknown/static kind) — path-based at the org apex.
+  return `https://${grid}.cloudgrid.io/${slug}`;
+}
+
 async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fresh }) {
   // Defensive: the web edition schema excludes `path`, but if a model still
   // passes one (e.g. from a cached tool description), reject early with a
@@ -361,19 +439,23 @@ async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fr
   }
 
   const form = new FormData();
-  // Redrop: a re-drop in the same session updates the previous drop in place (same URL,
-  // new version). `fresh: true` forces a new drop. The platform validates ownership and
-  // falls back to create if the caller does not own the previous drop.
-  // Field appended before the artifact so streaming parsers see it.
-  if (fresh !== true && ctx.state.lastDrop?.entity_id) {
-    form.append("previous_id", ctx.state.lastDrop.entity_id);
-  }
+  // The unified `/plug` create path is the same orchestrator `/drop/auto` used,
+  // but it is CREATE-ONLY for the drop flow: an anonymous caller naming a
+  // `target_entity_id` is rejected 401, and the authed create path mints a NEW
+  // entity. So `/plug` has NO in-place redrop / `previous_id` concept — every
+  // drop creates a fresh entity (new URL). `fresh` is accepted for backward
+  // compatibility but is now a no-op. See PR notes: the in-place-update +
+  // `202 unchanged` no-op semantics from `/drop/auto` are gone with M7.
+  void fresh;
+  // The artifact part name is unchanged from `/drop/auto` (`artifact`); the plug
+  // create path treats every non-`cloudgrid.yaml` part as raw artifact bytes.
   form.append("artifact", new Blob([bytes], { type }), name);
-  if (orgSlug) form.append("org_slug", orgSlug);
+  // `/plug` resolves the authed org from the `X-CloudGrid-Org` header (set
+  // above), not a form field — so `org_slug` is no longer sent.
 
   let res;
   try {
-    res = await fetch(`${API_BASE}/api/v2/drop/auto`, { method: "POST", headers, body: form });
+    res = await fetch(`${API_BASE}/api/v2/plug`, { method: "POST", headers, body: form });
   } catch (err) {
     throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
   }
@@ -391,7 +473,8 @@ async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fr
     throw new Error(`Drop failed (HTTP ${res.status}): ${msg}${hint ? ` ${hint}` : ""}`);
   }
 
-  // Persist the platform's anon-session cookie for ownership continuity.
+  // Persist the platform's anon-session cookie for ownership continuity (so a
+  // cookie-class caller can claim — via pickup — what it dropped).
   const setCookies = res.headers.getSetCookie
     ? res.headers.getSetCookie()
     : [res.headers.get("set-cookie")].filter(Boolean);
@@ -400,68 +483,34 @@ async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fr
     .find((c) => c.startsWith("cg_anon_session="));
   if (anonCookie) ctx.state.anonCookie = anonCookie;
 
-  // Remember the drop for redrop continuity — any caller class, any 2xx outcome.
-  if (data.entity_id || data.url) {
+  // `/plug` returns no `url`; derive the canonical public URL from slug + grid.
+  const url = composePlugUrl(data);
+
+  // Remember the drop for session continuity — any caller class.
+  if (data.entity_id || url) {
     ctx.state.lastDrop = {
       entity_id: data.entity_id ?? ctx.state.lastDrop?.entity_id ?? null,
-      url: data.url ?? ctx.state.lastDrop?.url ?? null,
+      url: url ?? ctx.state.lastDrop?.url ?? null,
     };
   }
 
-  if (res.status === 202) {
-    // Idempotent no-op — the bytes matched the live version exactly.
-    const url = (data.url ?? ctx.state.lastDrop?.url ?? "").trim();
-    return {
-      text: `No change — this exact content is already live: ${url}`,
-      structured: { url, status: "unchanged" },
-    };
-  }
-
-  if (res.status === 200) {
-    // Updated in place: same URL, new version, views/reactions intact.
-    const url = (data.url ?? ctx.state.lastDrop?.url ?? "").trim();
+  // Authenticated create (202): the drop minted an entity owned by the caller.
+  // `/plug`'s authed branch is reached only when an Authorization header was
+  // sent, so distinguish on the call class rather than a (now-absent) `owned_by`.
+  if (!isAnonymousCall) {
+    ctx.state.lastAnonClaim = null;
     const lines = ctx.edition === "web"
       ? [`Your app is live: ${url}`]
-      : [`Updated in place — same link: ${url}`];
-    if (ctx.edition !== "web" && data.owned_by === "authenticated") lines.push("Owned by you.");
-    if (data.expires_at) lines.push(`Expires ${data.expires_at}.`);
+      : [`Published to your org: ${url}`, "Owned by you."];
     const structured = {
       url,
-      status: "updated",
-      ...(data.owned_by ? { owned_by: data.owned_by } : {}),
-      ...(data.expires_at ? { expires_at: data.expires_at } : {}),
-    };
-    if (ctx.edition === "web") {
-      // Default authed web drops to "link" visibility so the URL is shareable
-      // and the console thumbnail renders without a sign-in wall.
-      if (data.visibility !== "link" && data.entity_id) {
-        await upgradeVisibilityToLink(ctx, data.entity_id, orgSlug);
-      }
-      lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
-      const vis = "link";
-      lines.push(`Visible to: ${VISIBILITY_LABELS[vis]}. Want to restrict access? I can set it to only you or your org.`);
-      structured.console_url = CONSOLE_URL;
-      structured.current_visibility = vis;
-      structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
-    }
-    return { text: lines.join("\n"), structured };
-  }
-
-  if (data.owned_by === "authenticated") {
-    ctx.state.lastAnonClaim = null;
-    const lines = ctx.edition === "web"
-      ? [`Your app is live: ${data.url}`]
-      : [`Published to your org: ${data.url}`, "Owned by you."];
-    if (data.expires_at) lines.push(`Expires ${data.expires_at}.`);
-    const structured = {
-      url: data.url,
       status: "created",
       owned_by: "authenticated",
-      ...(data.expires_at ? { expires_at: data.expires_at } : {}),
     };
     if (ctx.edition === "web") {
-      // Default authed web drops to "link" visibility (same as above).
-      if (data.visibility !== "link" && data.entity_id) {
+      // Default authed web drops to "link" visibility so the URL is shareable
+      // and the console thumbnail renders without a sign-in wall.
+      if (data.entity_id) {
         await upgradeVisibilityToLink(ctx, data.entity_id, orgSlug);
       }
       lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
@@ -470,43 +519,52 @@ async function runDrop(ctx, { html, path: filePath, filename, anonymous, org, fr
       structured.console_url = CONSOLE_URL;
       structured.current_visibility = vis;
       structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
-    } else {
-      lines.push("Drop again in this session to update it in place (same link); pass fresh to start a new one.");
     }
     return { text: lines.join("\n"), structured };
   }
 
-  // 201 — created new (first drop, fresh: true, or the server fell back to create).
-  if (data.claim_url) {
+  // Anonymous create (201) — Guest-Org inspiration, 7-day expiry, claimable.
+  // `/plug` carries the reward fields (`claim_url` + `claim_message`) and the
+  // real `entity_id`; pickup-by-id is how it is later claimed.
+  if (data.claim_url || data.entity_id) {
+    let token = null;
     try {
-      ctx.state.lastAnonClaim = {
-        token: new URL(data.claim_url).searchParams.get("token"),
-        entity_id: data.entity_id,
-        url: data.url,
-      };
+      token = data.claim_url ? new URL(data.claim_url).searchParams.get("token") : null;
     } catch {
-      ctx.state.lastAnonClaim = null;
+      token = null;
     }
+    ctx.state.lastAnonClaim = {
+      token,
+      entity_id: data.entity_id ?? null,
+      url,
+    };
+  }
+  const lines = [ctx.edition === "web" ? `Your app is live: ${url}` : `Live: ${url}`];
+  if (data.claim_message) {
+    lines.push(data.claim_message);
+  } else if (data.claim_url) {
+    lines.push("Sign in, then run cloudgrid_claim to keep it past 7 days.");
   }
-  const lines = [ctx.edition === "web" ? `Your app is live: ${data.url}` : `Live: ${data.url}`];
-  if (data.expires_at) lines.push(`Expires ${data.expires_at} — anonymous drops last 7 days.`);
-  if (data.claim_url) lines.push("Sign in, then run cloudgrid_claim to keep it past 7 days.");
-  lines.push("Drop again in this session to update it in place (same link); pass fresh to start a new one.");
   return {
     text: lines.join("\n"),
     structured: {
-      url: data.url,
+      url,
       status: "created",
-      ...(data.expires_at ? { expires_at: data.expires_at } : {}),
     },
   };
 }
 
-async function runClaim(ctx, { claim_token, claim_url }) {
+async function runClaim(ctx, { claim_token, claim_url, entity_id }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("You are not signed in. Run cloudgrid_login first, then claim.");
   }
+
+  // `/api/v2/anon-claim` (claim-token-in-body, returns a list) was retired; the
+  // claim now runs through `POST /api/v2/entities/:id/pickup`, which takes the
+  // entity id in the PATH and the `claim_token` in the body, and re-homes the
+  // Guest-Org inspiration into the caller's grid (ownership transfer). The
+  // anon-session cookie is the token-less alternative auth.
   let claimToken = claim_token;
   if (!claimToken && claim_url) {
     try {
@@ -516,16 +574,36 @@ async function runClaim(ctx, { claim_token, claim_url }) {
     }
   }
   if (!claimToken && ctx.state.lastAnonClaim) claimToken = ctx.state.lastAnonClaim.token;
-  if (!claimToken) {
-    throw new Error("No claim token. Pass claim_token or claim_url from an anonymous drop.");
+
+  // Pickup needs the target entity id in the URL path. Prefer an explicit one,
+  // else the entity remembered from this session's anonymous drop.
+  const targetId = entity_id || ctx.state.lastAnonClaim?.entity_id;
+  if (!targetId) {
+    throw new Error(
+      "No drop to claim. Pass entity_id (or drop something anonymously first in this session), " +
+        "so the pickup knows which entity to claim.",
+    );
   }
 
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+  };
+  // The claim re-homes the inspiration into the caller's grid; the platform
+  // resolves the destination from the active-org context, so send the org
+  // header (the same header every other authed write uses).
+  const orgSlug = await ctx.getActiveOrg();
+  if (orgSlug) headers["X-CloudGrid-Org"] = orgSlug;
+  // Replay the anon-session cookie so a cookie-class caller can claim what it
+  // dropped, even without a claim token.
+  if (ctx.state.anonCookie) headers["Cookie"] = ctx.state.anonCookie;
+
   let res;
   try {
-    res = await fetch(`${API_BASE}/api/v2/anon-claim`, {
+    res = await fetch(`${API_BASE}/api/v2/entities/${encodeURIComponent(targetId)}/pickup`, {
       method: "POST",
-      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-      body: JSON.stringify({ claim_token: claimToken }),
+      headers,
+      body: JSON.stringify(claimToken ? { claim_token: claimToken } : {}),
     });
   } catch (err) {
     throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
@@ -539,26 +617,27 @@ async function runClaim(ctx, { claim_token, claim_url }) {
     /* handled below */
   }
   if (!res.ok) {
+    // 409 ALREADY_CLAIMED is the idempotent "nothing left to do" outcome.
+    if (res.status === 409) {
+      ctx.state.lastAnonClaim = null;
+      return {
+        text: "Nothing to claim — it was already claimed.",
+        structured: { claimed: 0, urls: [] },
+      };
+    }
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
     throw new Error(`Claim failed (HTTP ${res.status}): ${msg}`);
   }
-  const claimed = Array.isArray(data?.claimed) ? data.claimed : [];
-  if (claimed.length === 0) {
-    return {
-      text: "Nothing to claim — it may already be claimed or expired.",
-      structured: { claimed: 0, urls: [] },
-    };
-  }
+
   ctx.state.lastAnonClaim = null;
-  const lines = [`Claimed ${claimed.length}, now yours:`];
-  for (const c of claimed) {
-    lines.push(`${c.url}${c.new_expires_at ? ` (expires ${c.new_expires_at})` : ""}`);
-  }
+  const url = data?.url || data?.redirect_url || ctx.state.lastDrop?.url || null;
+  const lines = ["Claimed 1, now yours:"];
+  lines.push(`${url ?? ""}${data?.new_expires_at ? ` (expires ${data.new_expires_at})` : ""}`.trim());
   return {
     text: lines.join("\n"),
     structured: {
-      claimed: claimed.length,
-      urls: claimed.map((c) => c.url),
+      claimed: 1,
+      urls: url ? [url] : [],
     },
   };
 }
@@ -797,6 +876,7 @@ export function registerTools(server, ctx) {
       inputSchema: {
         claim_token: z.string().optional().describe("The claim token from an anonymous drop."),
         claim_url: z.string().optional().describe("The claim_url from an anonymous drop; the token is read from it."),
+        entity_id: z.string().optional().describe("The entity id of the anonymous drop to claim. Defaults to this session's last anonymous drop."),
       },
       outputSchema: {
         claimed: z.number().describe("Number of drops claimed."),