@cloudgrid-io/mcp

An MCP server for CloudGrid. It exposes the CloudGrid actions as MCP tools.

It ships in two editions from one codebase:

• Local (stdio) — runs on your machine, full toolset including the CLI-wrapping tools. This README covers it. For Claude Code, Cursor, Claude Desktop.
• Web (hosted HTTP) — a lighter toolset (17 direct-API tools, no CLI wrappers) for web clients like claude.ai. See REMOTE.md.

The local edition wraps the grid CLI for authenticated operations (the CLI handles auth, grid context, and error formatting) and calls the API directly for the plug, login, and visibility tools.

CLI compatibility

The MCP uses an installed CLI only when it meets the platform floor (MIN_CLI_VERSION, currently 0.15.26 — kept in lockstep with the API's live cli_compat floor, which rejects older CLIs with HTTP 426). Below the floor it skips the local/global CLI and lazily fetches @cloudgrid-io/cli@latest via npx instead. A CI drift guard (npm run test:drift-guard) asserts every wrapped verb exists in the CLI help.

GRID_AUTH_STALE is out of scope

Strict-OIDC (org-owned) grids can return GRID_AUTH_STALE when the caller's session predates an SSO policy change. The MCP does not target such grids and does not handle this code: if a GRID_AUTH_STALE response is ever seen, point the user at Console SSO to re-authenticate — the MCP will not silently retry.

Prerequisite

Install and log in to the CLI:

npm install -g @cloudgrid-io/cli
grid login

The server reads no credentials directly. It runs grid, which uses its own stored credentials at ~/.cloudgrid/credentials.

Run

npx -y @cloudgrid-io/mcp

Or from a clone:

cd mcp
npm install
npm start

It speaks MCP over stdio. Point any MCP client at the cloudgrid-mcp command.

One CloudGrid server per client

Run EITHER this local (stdio) server — standalone or via the Claude Code plugin, which bundles it — OR the hosted connector (mcp.cloudgrid.io) in a given client. Never both: each grid_* tool appears twice, the two servers hold separate sign-in state (the local edition shares the CLI's ~/.cloudgrid/credentials; the connector holds an OAuth session), and they can disagree about whether you are signed in — the model may then act on whichever answered last. How to tell: duplicate grid_* entries in the client's tool list, or two CloudGrid servers in its MCP/connector settings. Which to keep: the local edition wherever you build runtime apps from folders (it has path + the CLI); the connector in chat-only clients where you publish single pages.

QA session log (optional)

Set CLOUDGRID_QA_SLACK_WEBHOOK to an internal / private Slack incoming-webhook URL to receive a per-session QA log (log-<Client>-<transport>-mcp.txt) when a local (stdio) session goes live, fails, or is abandoned. The log carries the user's first message (when the host forwards it) and identity details, so the target channel MUST be internal. The hosted edition never posts a session log at all (its servers carry no webhook); a hosted grid_note is filed with the CloudGrid API instead — see "Privacy Policy" below. Unset → the feature is fully dark (nothing captured, nothing posted). CLOUDGRID_QA_IDLE_MS overrides the abandoned-idle window (default 900000 = 15 min).

Tools

38 tools registered (15 shared across both editions, 23 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.

Direct-API tools (both editions)

| Tool | Wraps | Summary | |---|---|---| | 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 | Leave a one-paragraph summary of what you built this session and why, for the local edition's optional QA session log... | | grid_plug | API | Plug an app, website, game, or HTML page into CloudGrid at a live public URL. | | grid_get_app_source | API | Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and re-plug the SAME URL... | | grid_visibility | API | Change who can see a CloudGrid inspiration OR runtime app/agent. | | grid_check_deploy | API | Check whether an async runtime-app build has finished and the app is live. | | grid_list_grids | API | List the signed-in user's grids, each with slug, name, role, and provisioning status. | | grid_start | API | A short orientation for building with CloudGrid: the account this session is signed in as and its active grid, how to... | | grid_get_template | corpus | Load a specific CloudGrid workflow, template, example, rule, troubleshooting note, or reference doc by name — determi... | | grid_report | API | Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. | | grid_hello | API | Create a minimal hello page and plug it into the user's grid, returning the live URL. | | grid_delete | grid delete entity | Archive a CloudGrid inspiration. |

The direct-API tools call the platform without the CLI, so they also work in the web edition. grid_login writes the same ~/.cloudgrid/credentials the CLI uses, so the two share one identity.

CLI-wrapping tools (local edition only)

| Tool | Wraps | Summary | |---|---|---| | grid_login | API | Start a CLI-free CloudGrid sign-in. | | grid_login_status | API | Finish a sign-in started by grid_login. | | grid_create_project | grid new | Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. | | grid_view_logs | grid logs | Tail recent logs for an entity. | | grid_share | grid visibility set | Set an entity's visibility and print its URL. | | grid_feedback | grid feedback list | List recent feedback events for the active grid. | | grid_whoami | grid whoami | Show the signed-in user and active grid. | | grid_switch_grid | grid use | Switch the active grid. | | grid_logout | grid logout | Sign out and clear local credentials. | | grid_status | grid status | Grid dashboard, entity detail, or deploy snapshot. | | grid_info | grid info | Show metadata for a CloudGrid entity. | | grid_get | grid get <grids|entities|spaces> --json | List CloudGrid grids, entities, or spaces. | | grid_describe_grid | grid describe grid <slug> --json | Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. | | grid_edit_existing_app | grid pull | Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next grid... | | grid_rename|grid rename| Rename a CloudGrid entity's display name (slug stays the same). | |grid_take_offline|grid unplug| Take an entity off the grid. | |grid_rollback_deploy|grid rollback| Rollback an entity to a previous version. | |grid_list_versions|grid versions| List published versions for an entity. | |grid_set_env|grid env| Manage environment variables for an entity. | |grid_set_secret|grid secrets| Set or list secret names for an entity. | |grid_scaffold|grid scaffold| Scaffold service folders declared in cloudgrid.yaml (idempotent). | |grid_diagnose|grid doctor| Run CloudGrid diagnostics on the local environment. | |grid_get_url|grid open --print` | Return the public URL for an entity. |

grid_share and grid_visibility overlap on purpose: grid_share wraps the CLI and defaults to link; grid_visibility is direct API, takes an explicit scope, and defaults its target to the session's last drop — it is the one the web edition gets.

All tools carry MCP annotations (readOnlyHint, destructiveHint, openWorldHint) for clients that support them.

Test

A smoke test spawns the server with a real MCP client, lists the tools, and calls the read-only grid_feedback tool end to end:

cd mcp
npm install
npm run smoke

It needs a logged-in CLI on $PATH.

Live smoke scripts

Three more scripts run against the live API on demand. They are not part of CI. A new plug needs sign-in, so none of them creates an anonymous drop. Each one skips a step, and says why, when the variables that step needs are missing. Tokens come only from the environment and are never printed.

| Script | Without secrets | With secrets | |---|---|---| | npm run smoke:drop | A signed-out create with anon: true returns needs_auth and publishes nothing. | CLOUDGRID_TOKEN (and CLOUDGRID_SMOKE_GRID if the account has several grids): a signed-in create publishes an owned page and its URL serves. | | npm run smoke:redrop | Same signed-out check, through the web edition. | CLOUDGRID_SMOKE_REDROP_ENTITY_ID + CLOUDGRID_SMOKE_REDROP_OWNER_TOKEN (or CLOUDGRID_SMOKE_REDROP_OWNER_TOKEN_FILE) for an existing anonymous drop: the edit updates it in place, with no sign-in. The owner token is re-minted on every edit; a token file is rewritten with the fresh one. | | npm run smoke:claim | Skips. | CLOUDGRID_TOKEN: a signed-in plug. Add CLOUDGRID_SMOKE_CLAIM_ENTITY_ID + CLOUDGRID_SMOKE_CLAIM_TOKEN for an existing anonymous drop: grid_pull claims it into the account. A drop can be claimed once. |

The signed-out check is refused inside the server before any publish request is sent, so it is safe to run at any time.

Design

• Shells out with execFile and an argument array, so there is no shell and no injection surface.
• grid_view_logs never uses --follow; a streaming call would never return.
• Stateless. Each call is one CLI invocation.

Privacy Policy

Full policy: https://cloudgrid.io/privacy

What this MCP server does with your data

Authentication. grid_login opens a browser-based Google sign-in flow via CloudGrid's API (/auth/login). The returned JWT is stored at ~/.cloudgrid/credentials with 0600 permissions — the CLI and the MCP share one credential file by design (auth.js:7-8). The web edition has no sign-in tool: the AI tool's connector signs in with OAuth, and this server issues its own short-lived access token, with the CloudGrid session sealed inside it, so the session is never handed to the AI tool.

Deploying. grid_plug uploads your app files (HTML, source, assets) to https://api.cloudgrid.io/api/v2/plug. Before upload, inline sources are scanned for known API-key patterns (OpenRouter, Anthropic, OpenAI, Google, GitHub, AWS, Slack, Stripe); a match blocks the deploy. This is not a guarantee — a determined model can obfuscate a key past the scan — but it stops the good-faith "embed it so it works" path. Auth headers (Bearer JWT, grid slug) are attached to identify the caller.

Error reporting. grid_report sends an error report to https://api.cloudgrid.io/api/v2/errors. The tool description instructs the model to call it only with the user's explicit consent, and setting CLOUDGRID_TELEMETRY=off disables it unconditionally — but there is no programmatic consent check in the report handler itself. The payload includes an error summary, diagnostic metadata (platform, Node version, transport), a flag recording whether the user agreed to share the conversation (deploy.js:544), and a context object the model supplies — which by its declared shape (register.js:964-975) can carry the failing inputs (for example the HTML or args) and the original request. The transcript itself is not sent by this tool. The report scrub is two-layer: values AND the message field are scanned for known secret shapes (API key prefixes such as sk-ant-, sk-proj-, AKIA…; JWTs; PEM private-key blocks; Bearer tokens; basic-auth URL credentials) and matches are replaced with [REDACTED]. Arbitrary or unknown-shape secrets that do not match a known pattern still transit unredacted. The client-side scrub (scrubReportContext + scrubSecretValues in deploy.js) runs before the POST; the server endpoint applies a server-side key-name filter on top. To keep a secret out of a report, do not place it in the message or context you send, or set CLOUDGRID_TELEMETRY=off to disable reporting entirely.

Version check. At startup the local edition makes one request to https://registry.npmjs.org/@cloudgrid-io/mcp/latest to detect a stale .mcpb install, which never auto-updates. It sends no account data and no user content. The hosted edition does not do this.

QA session log. When CLOUDGRID_QA_SLACK_WEBHOOK is set (unset by default, fully dark otherwise), the local (stdio) server posts a per-session QA log to an internal Slack channel on deploy, error, idle timeout, or process shutdown. The log includes: session metadata (user ID, email, grid slug, client name), the user's first message (scrubbed, capped at 2 000 chars), a per-tool-call trail with allowlisted arg keys only, and an optional narrative set via grid_note or grid_plug's session_note (capped at 4 000 chars). The first message is captured from the CLOUDGRID_USER_REQUEST environment variable (forwarded by Claude Code) or grid_plug's user_request argument (local edition only). The hosted edition sends nothing on its own: its grid_plug has no user_request or session_note, and there is no post on a plug, on idle, or on close. The one hosted post is grid_note, which the user asks for: it POSTs the note to the CloudGrid API (/api/v2/feedback) under the user's own sign-in, with the grid slug and the client name — no email address, no tool-call trail, nothing else from the conversation; signed out, it returns needs_auth and sends nothing. grid_report (both editions) sends a failure report to the CloudGrid API only after the user agrees: the message and context the model passes plus the client name and platform, and the conversation only when they explicitly agree to that. Free-text values (the first message, the narrative, tool arguments, and error messages) pass through a scrubber that redacts JWTs, PEM keys, Bearer tokens, and known provider API-key formats. Identity fields (_keyResult values and the header block) and structured result data bypass the text scrubber.

No other data collection by this server. The server does not track usage analytics or transmit data beyond the flows listed above and the authenticated CloudGrid API calls the individual tools make (e.g. /grids, /pickup, /deploys, /inspirations/{id}/source). CLI-wrapping tools shell out to the CloudGrid grid CLI, which shares the same ~/.cloudgrid/credentials file and does not send additional telemetry through this server. They prefer the CLI bundled in the .mcpb or a compatible grid already on your PATH; if neither is present or new enough, they fall back to npx -y @cloudgrid-io/cli@latest (cli.js:411-424), which downloads and runs the CLI from the npm registry (registry.npmjs.org) on first use — software installation, and the second flow that can reach npm (the startup version check above is the first). Platform-level data handling is covered by the linked privacy policy.