@cloudgrid-io/mcp 0.5.2 → 0.5.4

package/README.md

@@ -79,7 +79,9 @@ also work in the web edition where no CLI exists. `cloudgrid_login` writes the s
 | `cloudgrid_logout` | `cloudgrid logout` | Sign out and clear local credentials. Destructive. |
 | `cloudgrid_status` | `cloudgrid status` | Org dashboard or entity detail. Read-only. |
 | `cloudgrid_info` | `cloudgrid info` | Entity metadata. Read-only. |
-| `cloudgrid_grid` | `cloudgrid get entities` | List entities on the grid. Read-only. |
+| `cloudgrid_get` | `cloudgrid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
+| `cloudgrid_describe_grid` | `cloudgrid describe grid <slug>` | Grid detail. Read-only. |
+| `cloudgrid_pickup` | `cloudgrid pickup <name>` | Download an entity's source and bind the folder. |
 | `cloudgrid_rename` | `cloudgrid rename` | Rename an entity's display name. |
 | `cloudgrid_unplug` | `cloudgrid unplug` | Take an entity off the grid. Destructive; requires confirm. |
 | `cloudgrid_delete` | `cloudgrid delete entity` | Archive an inspiration. Destructive; requires confirm. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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": {

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

@@ -94,7 +94,9 @@ export const CLI_TOOL_VERBS = {
   cloudgrid_logout:   ["logout"],
   cloudgrid_status:   ["status"],
   cloudgrid_info:     ["info"],
-  cloudgrid_grid:     ["get"],
+  cloudgrid_get:          ["get"],
+  cloudgrid_describe_grid: ["describe"],
+  cloudgrid_pickup:        ["pickup"],
   cloudgrid_rename:   ["rename"],
   cloudgrid_unplug:   ["unplug"],
   cloudgrid_delete:   ["delete"],
@@ -294,6 +296,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
@@ -359,19 +387,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}`);
   }
@@ -389,7 +421,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);
@@ -398,68 +431,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}`);
@@ -468,43 +467,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 {
@@ -514,16 +522,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}`);
@@ -537,26 +565,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] : [],
     },
   };
 }
@@ -795,6 +824,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."),
@@ -1103,12 +1133,69 @@ export function registerTools(server, ctx) {
     }),
   );
 
+  // cloudgrid_get is the single canonical lister for grids, entities, and spaces
+  // (wraps `cloudgrid get <resource> --json`). It replaces the former
+  // cloudgrid_grid (which wrapped only `get entities`) — retired here so there is
+  // exactly one way to list entities. resource="entities" reproduces the old
+  // cloudgrid_grid behaviour with `grid` mapping to the CLI's `--grid` flag.
   server.tool(
-    "cloudgrid_grid",
-    "List entities on the grid. Wraps `cloudgrid get entities`.",
-    { grid: z.string().optional().describe("Grid slug. Omit for the active grid.") },
+    "cloudgrid_get",
+    "List CloudGrid grids, entities, or spaces. Wraps `cloudgrid get <grids|entities|spaces> --json`.",
+    {
+      resource: z.enum(["grids", "entities", "spaces"]).describe("What to list: grids, entities, or spaces."),
+      grid: z.string().optional().describe("Grid slug (entities/spaces only). Omit for the active grid."),
+      kind: z.enum(["app", "agent", "inspiration"]).optional().describe("Filter by kind (entities only)."),
+      status: z.enum(["charged", "live", "dark", "archived"]).optional().describe("Filter by status (entities only)."),
+      space: z.string().optional().describe("Only entities scoped to this space slug (entities only)."),
+      archived: z.boolean().optional().describe("Include archived entities (entities only)."),
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(({ resource, grid, kind, status, space, archived }) => {
+      const args = ["get", resource];
+      // --grid applies to entities and spaces; grids has no such flag.
+      if (grid && resource !== "grids") args.push("--grid", grid);
+      if (resource === "entities") {
+        if (kind) args.push("--kind", kind);
+        if (status) args.push("--status", status);
+        if (space) args.push("--space", space);
+        if (archived) args.push("--archived");
+      }
+      args.push("--json");
+      return args;
+    }),
+  );
+
+  server.tool(
+    "cloudgrid_describe_grid",
+    "Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps `cloudgrid describe grid <slug> --json`.",
+    { grid: z.string().describe("Grid slug to describe.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
-    cliTool(({ grid }) => (grid ? ["get", "entities", "--grid", grid] : ["get", "entities"])),
+    cliTool(({ grid }) => ["describe", "grid", grid, "--json"]),
+  );
+
+  server.tool(
+    "cloudgrid_pickup",
+    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `cloudgrid pickup`.",
+    {
+      name: z.string().describe("Entity slug or id to pick up."),
+      target_dir: z.string().optional().describe("Directory to pick up into (relative to cwd). Defaults to the entity name."),
+      grid: z.string().optional().describe("Grid to resolve the entity in. Defaults to the active grid."),
+      version: z.string().optional().describe("Pick up an older version's source instead of HEAD."),
+      force: z.boolean().optional().describe("Pick up into a non-empty directory."),
+      no_bind: z.boolean().optional().describe("Download source only — skip cloudgrid.yaml and the link."),
+      cwd: z.string().optional().describe("Working directory the CLI runs in. The download lands here; pass an explicit, writable directory."),
+    },
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    cliTool(({ name, target_dir, grid, version, force, no_bind }) => {
+      const args = ["pickup", name];
+      if (target_dir) args.push(target_dir);
+      // The CLI's pickup --help exposes `--org <slug>` (legacy naming) for the grid.
+      if (grid) args.push("--org", grid);
+      if (version) args.push("--version", version);
+      if (force) args.push("--force");
+      if (no_bind) args.push("--no-bind");
+      return args;
+    }, { cwdParam: true }),
   );
 
   server.tool(