@cloudgrid-io/mcp 0.20.55 → 0.21.0

package/README.md

@@ -84,7 +84,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 <!-- gen:tools -->
 ## Tools
 
-36 tools registered (14 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
+37 tools registered (15 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
 
 ### Direct-API tools (both editions)
 
@@ -92,6 +92,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 |---|---|---|
 | `grid_pickup` | API | Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. |
 | `grid_pull` | API | Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_... |
+| `grid_collab` | API | Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, no... |
 | `grid_create_grid` | API | Create a new grid (workspace) for the signed-in user — they become its admin. |
 | `grid_note` | API | Optionally leave a one-paragraph summary of what you built this session and why. |
 | `grid_plug` | API | Plug an app, website, game, or single HTML page into CloudGrid — the live runtime that runs it and provides its infra... |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.55",
+  "version": "0.21.0",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -10,7 +10,7 @@
     "src"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.19"
   },
   "scripts": {
     "start": "node src/index.js",
@@ -59,7 +59,11 @@
     "test:system-ca": "node test/system-ca.test.mjs",
     "test:tool-titles-and-vocab": "node test/tool-titles-and-vocab.test.mjs",
     "test:visibility-mapping": "node test/visibility-mapping.test.mjs",
-    "test:verb-distinction": "node test/verb-distinction.test.mjs"
+    "test:verb-distinction": "node test/verb-distinction.test.mjs",
+    "test:collab": "node test/collab.test.mjs",
+    "test:url-shape": "node test/url-shape-guard.test.mjs",
+    "test:pull-grid": "node test/pull-grid-param.test.mjs",
+    "test:pull-output-schema": "node test/pull-output-schema.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",

package/src/corpus/cli-reference.md

@@ -95,7 +95,7 @@ grid grid
 | `env` / `secrets` | Manage runtime env vars and secrets (secret values are never printed) |
 | `grid` / `list` | List what's on your hub / org |
 | `rename` / `delete` / `unplug` | Rename, archive, take off the grid |
-| `pull` / `clone` / `fork` | Download source; clone or fork an entity |
+| `collab` / `pull` / `pickup` | Grant push access (`collab`), continue in place (`pull`), or fork a copy (`pickup`) |
 | `feedback [message]` | Send feedback to the CloudGrid team |
 | `brain refresh <name>` | Re-run Grid Brain metadata (description, tags, diagram) |
 | `doctor` | Diagnostic checks (Node, Docker, API reachability, auth) |

package/src/corpus/playbook.md

@@ -39,7 +39,7 @@ Operating rules:
 15. Editing an existing thing from just its URL (a fresh chat, no prior context — e.g. "change the background to green here <url>"): call grid_get_app_source(url) first. It resolves the entity_id and returns the current HTML plus its kind, single_html, capabilities, and replug_handle — read those to pick the branch:
   - Single-HTML inspiration you can re-plug (single_html: true and capabilities.replug: true): edit the returned HTML and call grid_plug with target_entity_id (or grid+slug — the replug_handle) to update the SAME URL in place. This works on every edition, including hosted.
   - Multi-file app or agent (kind is app or agent, or single_html: false): do NOT try to edit it as one inline HTML file. Tell the user it is a multi-file <kind>, give them the entity_id and the source (source_download_url), and explain that rebuilding it needs the local edition (Claude Desktop/Code) or the CLI — the hosted server cannot rebuild a multi-file app.
-  - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. Offer to fork it into the user's own grid with grid_pickup and edit the copy instead. Three distinct verbs, do not conflate them: grid_pickup = make your OWN COPY (a fork, a NEW entity); grid_pull = continue the SAME entity in place (needs push access — you own it or are a collaborator); and "collab" = GET push access to that same entity, which is the CLI `grid collab <entity>` (grants permission only and fetches nothing — pull afterwards to get the code). Getting collaborator access has no MCP tool — it is CLI-only — so if the user asks to "collab", do NOT call grid_pickup; explain that granting access is the CLI `grid collab`, distinct from pickup's fork.
+  - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. If the user wants their OWN copy, offer to fork it into their grid with grid_pickup and edit the copy. If the user wants to COLLABORATE on the SAME entity, use grid_collab. Three distinct verbs, do not conflate them: grid_pickup = make your OWN COPY (a fork, a NEW entity); grid_pull = continue the SAME entity in place (needs push access — you own it or are a collaborator); grid_collab = GET push access to that same entity (grants permission only and fetches nothing — run grid_pull afterwards to get the code, and if the owner gates access grid_collab sends them a request to approve). So if the user asks to "collab", do NOT call grid_pickup; call grid_collab — distinct from pickup's fork.
 16. Help CloudGrid QA. When you plug, fill BOTH of grid_plug's user_request (a brief version of the user's ask) AND session_note (one short paragraph on what you built and why) — include both by default; omit only if the user objects. A successful plug posts the QA log on that same call, so do NOT call grid_note after plugging — session_note is the narrative path. Use grid_note only BEFORE a plug, or in a session that ends without one. Everything here is recorded for quality review and never changes the plug.
 17. Auth check before an owned plug, with a guest fallback — ALWAYS ask first. grid_start reports signed_in. If the user wants to publish and is NOT signed in (or the plug returns a create-time 401), do NOT silently fail, do NOT invent an auth flow, and NEVER pass anon: true on your own — ask them plainly: "Sign in and plug it to your grid, or plug it as a guest right now (live immediately at a guest link that expires in 7 days unless claimed)?" Only if they choose guest, re-call grid_plug with anon: true and surface the claim_url + owner_token. grid_plug enforces this server-side: the first unauthenticated create in a session returns needs_auth (the ask) even when anon: true was passed — relay it to the user and stop; do not answer it yourself. This is distinct from rule 7: rule 7 forbids the anon fallback on a SERVER error (5xx) for a signed-in user (it burns quota and downgrades ownership); THIS rule is about not being authenticated at all, where guest is a legitimate choice the USER makes.
 18. Using the CLI (runtime apps, `grid dev`, or any shell step): the verb is `grid`, but ALWAYS invoke it as `npx -y @cloudgrid-io/cli@latest <command>` — never a bare `grid` or `cloudgrid`. A `grid` already on the machine is usually a stale global that the API rejects on its version floor, so a bare command fails with a version error and wastes turns; `npx …@latest` needs no install and is always current. In a local edition, prefer the MCP `grid_*` tools — they resolve a current CLI for you — and drop to `npx …@latest` only for shell-only steps like `grid dev`.

package/src/corpus/rules/publish-fallbacks.md

@@ -14,8 +14,8 @@ loops forever.
 
 This is a known platform issue, not a mistake in your request. Do not retry with
 different flag or path permutations — they will all fail the same way. If a
-terminal is available, deploy from the CLI instead (`grid plug <path>`).
-If no terminal is available, stop and tell the user
+terminal is available, deploy from the CLI instead (`grid plug <path>` or
+`grid plug <url>`). If no terminal is available, stop and tell the user
 this is a known issue and needs the CLI.
 
 ## 429 anonymous cap

package/src/corpus/templates/semantic-search/services/backend/requirements.txt

@@ -3,5 +3,5 @@ uvicorn[standard]==0.30.1
 pymongo==4.8.0
 numpy==1.26.4
 httpx==0.27.0
-pypdf==6.14.2
+pypdf==6.15.0
 python-docx==1.1.2

package/src/corpus/templates/semantic-search/services/refresh/requirements.txt

@@ -5,5 +5,5 @@
 # pypdf / python-docx are imported lazily by source.extract_text for pdf/docx.
 pymongo==4.8.0
 httpx==0.27.0
-pypdf==6.14.2
+pypdf==6.15.0
 python-docx==1.1.2

package/src/corpus/troubleshooting/deploy-errors.md

@@ -10,7 +10,7 @@ Match the symptom to the row, apply the fix, and stop. Do not retry permutations
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `SCOPE_INVALID` on deploy | Known platform issue, not your request | Deploy from a terminal with `grid plug <path>`. Do not retry flag or path permutations. If no terminal is available, tell the user it is a known issue that needs the CLI. |
+| `SCOPE_INVALID` on deploy | Known platform issue, not your request | Deploy from a terminal with `grid plug <path>` or `grid plug <url>`. Do not retry flag or path permutations. If no terminal is available, tell the user it is a known issue that needs the CLI. |
 | `429` anonymous cap reached | Anonymous deploy quota is exhausted | Stop. Do not log in to work around it and do not retry today. Tell the user the cap is reached; they can try later or sign in for a higher limit as a deliberate choice. |
 | `409 EDIT_REJECTED` on re-plug | The target entity is archived or expired | Do not silently create a new entity — that mints a new URL and orphans the shared one. Ask the user before creating a fresh entity. |
 | `401` on an anonymous edit | Missing or stale `owner_token` | Re-plug with the `owner_token` from the last deploy of that entity. Each anonymous edit returns a fresh token — store the new one and use it next time. |

package/src/tools/deploy.js

@@ -21,6 +21,29 @@ import {
 import { okResult } from "./util.js";
 import { runCloudgrid } from "./cli.js";
 
+/**
+ * The API refuses an infra-dependent write while a grid is still provisioning.
+ *
+ * The code is being renamed ORG_PROVISIONING -> GRID_PROVISIONING
+ * (cloudgrid-io/cloudgrid#2673, the org->grid retirement). This accepts BOTH,
+ * which is what makes the API-side rename safe: an mcp that understands both is
+ * version-independent from the API's side, so the rename can land the moment
+ * this ships rather than waiting for adoption.
+ *
+ * Keep both until the API no longer emits the old name AND the floor of
+ * installed mcp versions understands the new one. mcp is published to npm, so
+ * installed copies keep matching whatever they shipped with — dropping the old
+ * name early breaks plugs into brand-new grids, silently, by turning a
+ * retryable 409 into a hard failure.
+ *
+ * One predicate, two call sites, so they cannot drift.
+ */
+const PROVISIONING_CODES = new Set(["GRID_PROVISIONING", "ORG_PROVISIONING"]);
+function isProvisioningCode(code) {
+  return PROVISIONING_CODES.has(code);
+}
+
+
 // ── Org listing (bearer-authed, web edition) ──────────────────────────────────
 // Fetches the signed-in user's orgs via GET /api/v2/orgs. The JWT does not
 // carry orgs (claims: sub, email, name, iat, exp), so the API is the canonical
@@ -635,10 +658,10 @@ export async function runReport(
 // Like `git clone` of the SAME entity: your next grid_plug (target_entity_id)
 // updates it. Needs push access — you must OWN it or be a COLLABORATOR. A
 // view-only caller is told they can't edit/plug it (fork a copy with grid_pickup,
-// or GET collaborator push access with the CLI `grid collab` — grants permission
+// or GET collaborator push access with grid_collab — grants permission
 // only, pull again once granted). A claim_token also
 // claims an anonymous drop into your account (ownership transfer).
-export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
+export async function runPull(ctx, { claim_token, claim_url, entity_id, grid } = {}) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("You are not signed in. Run grid_login first, then claim.");
@@ -685,8 +708,11 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
   };
   // 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.getActiveGrid();
+  // header (the same header every other authed write uses). The `grid`
+  // parameter (added for #247: the hosted transport cannot set HTTP headers,
+  // so multi-grid users must pass the grid explicitly) takes precedence, then
+  // the session's active grid.
+  const orgSlug = grid || (await ctx.getActiveGrid());
   // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
   if (orgSlug) {
     headers["X-CloudGrid-Grid"] = orgSlug;
@@ -724,18 +750,47 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
       };
     }
     const code = data?.error?.code || null;
+    // ORG_NOT_ACCESSIBLE: the `grid` param has a typo or the user isn't a
+    // member of that grid. The server message already contains an "Available:"
+    // hint listing valid grid slugs — surface it so the agent can self-correct.
+    if (code === "ORG_NOT_ACCESSIBLE") {
+      const serverMsg = data?.error?.message || "The specified grid is not accessible.";
+      const hint = data?.error?.details?.[0]?.hint || "";
+      return {
+        text:
+          `${serverMsg}${hint ? ` ${hint}` : ""} ` +
+          `Check the grid slug for typos and retry grid_pull with the correct \`grid\` parameter.`,
+        structured: { error: { code: "ORG_NOT_ACCESSIBLE" } },
+      };
+    }
+    // NO_ACTIVE_ORG: the account has no grid at all — route to in-flow grid
+    // creation instead of the misleading "no push access" advice.
+    if (code === "NO_ACTIVE_ORG") {
+      return {
+        text:
+          "The account has no grid yet. Do not send the user to the console — create one from here: " +
+          "suggest a short slug, confirm it with the user, call grid_create_grid, then re-call grid_pull.",
+        structured: { needs_grid_create: true },
+      };
+    }
     // No push access → not an error to throw; tell the user their options.
     if (res.status === 403 || code === "NOT_ALLOWLISTED" || code === "PICKUP_DISABLED" || code === "FORBIDDEN_ROLE") {
       return {
         text:
           `You don't have push access to this entity, so you can't edit or plug it. Two options: ` +
           `make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME ` +
-          `entity with the CLI \`grid collab <entity>\` — that grants permission only and fetches nothing, so ` +
-          `pull again once it is granted (if the owner gates access, \`grid collab\` becomes a request they approve).`,
+          `entity with grid_collab (the CLI equivalent is \`grid collab <entity>\`) — that grants permission only and fetches nothing, so ` +
+          `pull again once it is granted (if the owner gates access, grid_collab becomes a request they approve).`,
         structured: { can_edit: false, owner_is_you: false, access: "view_only" },
       };
     }
-    const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    let msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    // The API's "Set the X-CloudGrid-Grid header" error is unactionable for an
+    // MCP client (no client can set HTTP headers on a tool call). Rewrite it to
+    // name the tool parameter the caller CAN set (#247).
+    if (res.status === 400 && /X-CloudGrid-Grid/i.test(msg)) {
+      msg = "You belong to more than one grid. Pass the `grid` parameter to specify which grid to use.";
+    }
     throw new Error(`Pull failed (HTTP ${res.status}): ${msg}`);
   }
 
@@ -758,7 +813,7 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
     head = `You have collaborator push access to ${slug}${where} — your next grid_plug (target_entity_id) updates the SHARED entity; the team sees the new version and can roll it back.`;
     canEdit = true;
   } else {
-    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME entity with the CLI \`grid collab ${slug}\` (it grants permission only and fetches nothing — pull again once granted).`;
+    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME entity with grid_collab (CLI equivalent: \`grid collab ${slug}\`) — it grants permission only and fetches nothing, so pull again once granted.`;
     canEdit = false;
   }
   const lines = [head];
@@ -780,6 +835,161 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
 }
 
 
+// grid_collab — GET PUSH ACCESS to the SAME live entity you do NOT own (issue
+// #253). This is the third adopt/access verb, distinct from the other two:
+//   grid_pickup = make your OWN COPY (a fork: new entity, forked_from lineage)
+//   grid_pull   = continue an entity you ALREADY have access to (fetch the code)
+//   grid_collab = grant yourself push access to someone else's SAME entity
+//                 (permission only — fetches nothing; run grid_pull afterwards)
+//
+// Mirrors the CLI reference (packages/cli/src/commands/collab.ts). It records the
+// grant server-side via the CANONICAL join path POST /api/v2/entities/:id/collab
+// — the SAME entity, NOT a fork. The fork route is POST /runtimes/:id/remix
+// (runPickup); collab never touches it, so a collab can never silently become a
+// pickup (the #242 defect). On a POLICY denial (NOT_ALLOWLISTED / PICKUP_DISABLED
+// — the owner gated who may join) it does NOT dead-end on the 403: it turns the
+// denial into a REQUEST the owner approves, via POST /:id/collab-requests, exactly
+// as the CLI does (collab.ts:129). Other 403s (NOT_A_GRID_MEMBER / FORBIDDEN_ROLE)
+// are grid-boundary problems, not policy denials, so they are surfaced, never
+// converted to a request. Pure authenticated API calls, no CLI or filesystem —
+// so, like grid_pickup / grid_pull, it ships on BOTH editions.
+export async function runCollab(ctx, { entity_id, grid } = {}) {
+  const token = await ctx.getToken();
+  if (!token) {
+    throw new Error("You are not signed in. Run grid_login first, then collab.");
+  }
+  const target = entity_id;
+  if (!target) {
+    throw new Error("`entity_id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
+  }
+
+  const orgSlug = grid || (await ctx.getActiveGrid());
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+  };
+  if (orgSlug) {
+    // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak, so
+    // a bare-slug target resolves in the intended grid (mirrors runPull).
+    headers["X-CloudGrid-Grid"] = orgSlug;
+    headers["X-CloudGrid-Org"] = orgSlug;
+  }
+
+  const collabUrl = `${API_BASE}/api/v2/entities/${encodeURIComponent(target)}/collab`;
+  let res;
+  try {
+    res = await fetch(collabUrl, { method: "POST", headers, body: JSON.stringify({}) });
+  } catch (err) {
+    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
+  }
+
+  const raw = await res.text();
+  let data = null;
+  try { data = JSON.parse(raw); } catch { /* handled below */ }
+
+  if (!res.ok) {
+    const code = data?.error?.code || null;
+    // ── Policy denial → REQUEST ACCESS (the whole point of the tool). Scoped to
+    // the two policy codes ONLY: a grid-boundary 403 (NOT_A_GRID_MEMBER /
+    // FORBIDDEN_ROLE) is a different problem and must NOT spam the owner. ──────
+    if (res.status === 403 && (code === "NOT_ALLOWLISTED" || code === "PICKUP_DISABLED")) {
+      return await requestCollabAccess(ctx, target, headers);
+    }
+    if (res.status === 404 || code === "RUNTIME_NOT_FOUND" || code === "NOT_FOUND" || (typeof code === "string" && code.endsWith("_NOT_FOUND"))) {
+      throw new Error(`No entity matched '${target}'. Check the id or grid/slug (a canonical UUID or <grid-slug>/<entity-slug>).`);
+    }
+    if (res.status === 403 && code === "NOT_A_GRID_MEMBER") {
+      throw new Error(data?.error?.message || `You're not a member of the grid that owns '${target}'. Ask its owner to invite you to the grid first, then collab.`);
+    }
+    if (res.status === 403 && code === "FORBIDDEN_ROLE") {
+      throw new Error(data?.error?.message || `Collaborating on '${target}' needs builder or admin role in its grid.`);
+    }
+    if (res.status === 400 && code === "NOT_A_RUNTIME") {
+      throw new Error(data?.error?.message || `'${target}' is an Inspiration, not an app or agent — it has no collaborators. Fork it with grid_pickup instead.`);
+    }
+    const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    throw new Error(`Collab failed (HTTP ${res.status}): ${msg}`);
+  }
+
+  // ── Grant recorded on the SAME entity (permission only — no code fetched) ────
+  // Interpret the unified §4 pickup contract, exactly as runPull does, but frame
+  // it as an access grant and point at grid_pull for the code (founder split
+  // 2026-07-23: collab = permission, pull = code).
+  const slug = data?.slug || target;
+  const where = data?.grid ? ` in ${data.grid}` : "";
+  const ownerIsYou = data?.owner?.is_you === true;
+  const canReplug = data?.capabilities?.replug === true;
+  let head, canEdit;
+  if (ownerIsYou) {
+    head = `${slug}${where} is yours — nothing to grant. Use grid_pull to get the code, then grid_plug (target_entity_id) to update it.`;
+    canEdit = true;
+  } else if (canReplug) {
+    head = `You're now a collaborator on ${slug}${where} — you have PUSH ACCESS to the SAME entity (not a copy). This granted permission only; use grid_pull to get the code, then grid_plug (target_entity_id) updates the shared entity — the team sees the new version and can roll it back.`;
+    canEdit = true;
+  } else {
+    head = `You can view ${slug}${where}, but the grant did not give you push access. Make your own separate copy (a fork) with grid_pickup instead.`;
+    canEdit = false;
+  }
+  const lines = [head];
+  if (data?.url) lines.push(`URL: ${data.url}`);
+  return {
+    text: lines.join("\n"),
+    structured: {
+      ...(data?.entity_id ? { entity_id: data.entity_id } : {}),
+      ...(slug ? { slug } : {}),
+      grid: data?.grid ?? null,
+      ...(data?.url ? { url: data.url } : {}),
+      owner_is_you: ownerIsYou,
+      can_edit: canEdit,
+      access_requested: false,
+      request_pending: false,
+    },
+  };
+}
+
+// Turn a policy 403 into a request: POST /:id/collab-requests and tell the user
+// what happens next (mirrors CLI collab-requests.ts requestCollabAccess). A
+// request IS a success outcome, so this returns a normal result, never throws for
+// the expected 409s (a pending ask, or an access race the owner just opened).
+async function requestCollabAccess(ctx, target, headers) {
+  const url = `${API_BASE}/api/v2/entities/${encodeURIComponent(target)}/collab-requests`;
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers, body: JSON.stringify({}) });
+  } catch (err) {
+    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
+  }
+  const raw = await res.text();
+  let data = null;
+  try { data = JSON.parse(raw); } catch { /* handled below */ }
+  const code = data?.error?.code || null;
+
+  if (res.ok) {
+    return {
+      text:
+        `The owner gates who can collaborate on '${target}', so I asked them for push access on your behalf. ` +
+        `They've been notified — once they approve, run grid_collab again to join, then grid_pull to get the code.`,
+      structured: { access_requested: true, request_pending: true, owner_is_you: false, can_edit: false },
+    };
+  }
+  if (res.status === 409 && code === "COLLAB_REQUEST_EXISTS") {
+    return {
+      text: `You already asked for access to '${target}'. The owner hasn't decided yet — you'll be able to join once they approve.`,
+      structured: { access_requested: true, request_pending: true, owner_is_you: false, can_edit: false },
+    };
+  }
+  if (res.status === 409 && code === "COLLAB_ALREADY_ALLOWED") {
+    // Race: the owner opened access between the join 403 and this request.
+    return {
+      text: `You already have access to '${target}'. Run grid_collab again to join, then grid_pull to get the code.`,
+      structured: { access_requested: false, request_pending: false, owner_is_you: false, can_edit: false },
+    };
+  }
+  const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+  throw new Error(`Couldn't request access to '${target}' (HTTP ${res.status}): ${msg}`);
+}
+
+
 // ── grid_plug — the unified create/re-plug verb (spec v2 §3) ──────────────
 
 // Total upload budget mirrors the server's multipart cap (100 MB).
@@ -1122,7 +1332,7 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
   // internally with a bounded budget; this guidance is the budget-exhausted tail,
   // so the wording tells the agent to wait and re-call rather than surface a raw
   // code. (Issue #235.)
-  if (status === 409 && code === "ORG_PROVISIONING") {
+  if (status === 409 && isProvisioningCode(code)) {
     return "The grid is still finishing setup — a brand-new grid provisions its infrastructure in the background (usually within ~30s). Wait ~15s and call grid_plug again with the SAME parameters; it deploys once the grid is ready. Do not switch to anonymous and do not send the user to the console.";
   }
   // 409 EDIT_REJECTED — an in-place re-plug the server won't take.
@@ -1142,7 +1352,7 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
     if (code === "NO_ACTIVE_ORG") {
       return "The account has no grid yet. Do not send the user to the console — create one from here: suggest a short slug, confirm it with the user, call grid_create_grid, then re-call grid_plug with grid: <slug>.";
     }
-    return "You lack the role to plug this target. To re-plug someone else's entity, pull it first (grid_pull), or make your own copy (grid_pickup).";
+    return "You lack the role to plug this target. To get push access to the SAME entity, use `grid_collab` — it grants permission only and fetches nothing, so run `grid_pull` again once it is granted (if the owner gates access, it becomes a request they approve). To make your own separate copy (a fork), use `grid_pickup`.";
   }
   // ── Consent-gated report offer (Task 34) ──────────────────────────────────
   // GENUINE bugs only: a build/deploy failure, any 5xx, INTERNAL_ERROR, or an
@@ -1599,7 +1809,7 @@ export async function runPlug(ctx, input, deps = {}) {
   for (;;) {
     ({ res, raw, data } = await sendPlug());
     if (res.ok) break;
-    if (res.status === 409 && data?.error?.code === "ORG_PROVISIONING") {
+    if (res.status === 409 && isProvisioningCode(data?.error?.code)) {
       const hint = data?.error?.details?.[0]?.hint || "";
       // Terminal failure — provisioning did not complete; retrying is futile.
       if (/did not (complete|finish)/i.test(hint)) {

package/src/tools/register.js

@@ -21,6 +21,7 @@ import {
   detectSourceManifest,
   runReport,
   runPull,
+  runCollab,
   runPlug,
   runPickup,
   runCreateGrid,
@@ -132,7 +133,7 @@ export function registerTools(server, ctx) {
     "grid_pickup",
     {
       title: "Copy an app into your grid",
-      description: "Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. This is a FORK, not a \"collab\": it never grants you access to anyone else's live entity. Getting PUSH ACCESS to the SAME entity is a different operation — the CLI command `grid collab <entity>` — so do NOT reach for grid_pickup when the user asks to collab. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
+      description: "Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. This is a FORK, not a \"collab\": it never grants you access to anyone else's live entity. Getting PUSH ACCESS to the SAME entity is a different operation — the grid_collab tool (or the CLI `grid collab <entity>`) — so do NOT reach for grid_pickup when the user asks to collab; reach for grid_collab. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
       inputSchema: {
         entity_id: z.string().describe("The source app to copy: a canonical UUID or <grid-slug>/<entity-slug>."),
         grid: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
@@ -172,9 +173,10 @@ export function registerTools(server, ctx) {
     "grid_pull",
     {
       title: "Pull an app to edit in place",
-      description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so, and offer the two real options: (1) make your own separate copy (a fork) with grid_pickup, or (2) GET push access to the SAME entity with the CLI command `grid collab <entity>` — \"collab\" is a distinct access-control operation that grants permission only and fetches nothing, so once it is granted you run grid_pull again to get the code (and if the owner gates access, `grid collab` becomes a request they approve). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
+      description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so, and offer the two real options: (1) make your own separate copy (a fork) with grid_pickup, or (2) GET push access to the SAME entity with grid_collab (or the CLI `grid collab <entity>`) — \"collab\" is a distinct access-control operation that grants permission only and fetches nothing, so once it is granted you run grid_pull again to get the code (and if the owner gates access, grid_collab becomes a request they approve). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
         entity_id: z.string().optional().describe("The entity id to pull. Defaults to this session's last anonymous drop."),
+        grid: z.string().optional().describe("Grid to resolve a bare slug in. Required only when you belong to more than one grid."),
         claim_token: z.string().optional().describe("Anonymous drop only: its owner token — claims that drop into your account (ownership transfer)."),
         claim_url: z.string().optional().describe("Alternative to claim_token for an anonymous drop — the claim_url; the token is read from it."),
       },
@@ -185,6 +187,9 @@ export function registerTools(server, ctx) {
         url: z.string().optional().describe("Its public URL."),
         owner_is_you: z.boolean().optional().describe("True if you own it."),
         can_edit: z.boolean().optional().describe("True if you can plug/update it (owner or collaborator). False = view-only."),
+        access: z.string().optional().describe("Access level when can_edit is false (e.g. 'view_only')."),
+        error: z.object({ code: z.string() }).optional().describe("Error envelope when the grid slug is wrong or inaccessible. code is the server error code (e.g. ORG_NOT_ACCESSIBLE)."),
+        needs_grid_create: z.boolean().optional().describe("True when the account has no grid yet — route to grid_create_grid before retrying."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
@@ -197,6 +202,42 @@ export function registerTools(server, ctx) {
     },
   );
 
+  // grid_collab — GET PUSH ACCESS to the SAME live entity you do NOT own (#253).
+  // The THIRD adopt/access verb, distinct from grid_pickup (fork) and grid_pull
+  // (continue). Pure API (POST /entities/:id/collab; a policy 403 → a request via
+  // POST /:id/collab-requests), no CLI or filesystem — so it ships on BOTH
+  // editions, exactly like grid_pickup/grid_pull. Registered BEFORE the
+  // edition!=="local" gate for that reason.
+  reg(
+    "grid_collab",
+    {
+      title: "Get push access to an app you don't own",
+      description: "Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, not a copy. This grants PERMISSION ONLY and fetches nothing: after it succeeds, run grid_pull to get the code, then grid_plug (with its target_entity_id) updates the SHARED entity in place (the team sees the new version and can roll it back). This is NOT a fork — it never mints a new entity and never carries forked_from lineage; if you want your OWN separate copy instead, that is grid_pickup. If the owner GATES who may join, this does NOT dead-end: it sends the owner a request for access on your behalf, and once they approve you run grid_collab again to join. Use this — not grid_pickup — whenever the user asks to \"collab\" on, \"join\", or \"get push/write access to\" an app they don't own. Requires sign-in. Calls the API directly (both editions).",
+      inputSchema: {
+        entity_id: z.string().describe("The app to get push access to: a canonical UUID or <grid-slug>/<entity-slug>."),
+        grid: z.string().optional().describe("Grid to resolve a bare slug in. Required only when a bare slug is ambiguous across grids you belong to."),
+      },
+      outputSchema: {
+        entity_id: z.string().optional().describe("The SAME entity you now collaborate on — pass it to grid_pull, then to grid_plug as target_entity_id. Never a new/forked entity."),
+        slug: z.string().optional().describe("Its slug."),
+        grid: z.string().nullable().optional().describe("Its grid."),
+        url: z.string().optional().describe("Its public URL."),
+        owner_is_you: z.boolean().optional().describe("True if you already own it (nothing to grant)."),
+        can_edit: z.boolean().optional().describe("True once you have push access (owner or collaborator). False = still view-only."),
+        access_requested: z.boolean().optional().describe("True when the owner gates access and a request was sent on your behalf."),
+        request_pending: z.boolean().optional().describe("True when a request is awaiting the owner's decision — join with grid_collab again once approved."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runCollab(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
   // grid_create_grid — create a grid for the signed-in user (POST /api/v2/grids,
   // the same call as the CLI `grid create grid <slug>`). Exists so a first-time
   // user with NO grid is never sent to the console: grid_plug returns
@@ -411,6 +452,7 @@ export function registerTools(server, ctx) {
           is_active: z.boolean(),
         })).optional().describe("Alias of grids (legacy picker alias)."),
         via: z.string().optional().describe("Recovery marker: 'cli-fallback' when a signed-in create was published through the bundled CloudGrid CLI."),
+        needs_grid_create: z.boolean().optional().describe("Zero-grid ask: the account has no grid yet — suggest a slug, confirm with the user, call grid_create_grid, then re-call grid_plug with grid: <slug>."),
       },
       // destructiveHint (M3): a re-plug with target_entity_id REPLACES what is
       // live at a public URL in place. Versions + grid rollback exist, but the
@@ -1206,13 +1248,12 @@ export function registerTools(server, ctx) {
   // source + cloudgrid.yaml and links the folder, so the next `grid plug` updates
   // the SAME entity in place. Wraps `grid pull` (NOT `grid pickup` — pickup now
   // makes a separate copy). Push access required; a view-only entity can't be
-  // pulled — use grid_pickup to fork a copy, or the CLI `grid collab` to GET
-  // push access to the same entity (grants permission only — pull again once
-  // granted). `grid collab` is CLI-only; there is no grid_collab MCP tool.
+  // pulled — use grid_pickup to fork a copy, or grid_collab to GET push access
+  // to the same entity (grants permission only — pull again once granted).
   regTool(
     "grid_edit_existing_app",
     "Pull app source to edit locally",
-    "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy (a fork) instead, use grid_pickup. To GET push access to an entity you can currently only view, that is a different operation — the CLI `grid collab <entity>`, which grants permission only; run the pull again once it is granted.",
+    "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy (a fork) instead, use grid_pickup. To GET push access to an entity you can currently only view, that is a different operation — grid_collab (CLI equivalent: `grid collab <entity>`), which grants permission only; run the pull again once it is granted.",
     {
       name: z.string().describe("Entity slug or id to pull."),
       target_dir: z.string().optional().describe("Directory to pull into (relative to cwd). Defaults to the entity name."),

package/src/tools.js

@@ -35,6 +35,7 @@ export {
   runPlug,
   runPickup,
   runPull,
+  runCollab,
   runCreateGrid,
   scanInlineSecrets,
   secretBlockMessage,