MCP tools reference

The MCP server exposes the grid as grid_* tools. They fall into three groups:

Agent-orientation tools that teach an assistant how to build on CloudGrid
Direct-API tools that call the platform API and work in both editions
CLI-wrapping tools available only in the local edition

A hosted-connector user (e.g. the claude.ai or ChatGPT integration) gets the shared tools only. A local user (npx @cloudgrid-io/mcp) gets all of them. The tables below are generated from the @cloudgrid-io/mcp tool registry — run node scripts/sync-tool-docs.mjs to regenerate, or --check to validate in CI.

Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) for clients that support them.

37 tools registered — 15 shared with the hosted edition, 22 local-only. Generated from @cloudgrid-io/mcp — do not edit by hand.

Agent-orientation tools

Available in both editions (hosted + local). These front-load how to build on CloudGrid.

Tool	Summary
`grid_note`	Optionally leave a one-paragraph summary of what you built this session and why.
`grid_start`	Orient before building with CloudGrid — the live runtime environment where the user’s apps run WITH the infrastructure they need (managed…
`grid_get_template`	Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundled corpus.
`grid_report`	Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user’s explicit consent.

Direct-API tools

Available in both editions. These call the platform API directly.

Tool	Summary
`grid_pickup`	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`	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 t…
`grid_collab`	Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, not a copy.
`grid_create_grid`	Create a new grid (workspace) for the signed-in user — they become its admin.
`grid_plug`	Plug an app, website, game, or single HTML page into CloudGrid — the live runtime that runs it and provides its infrastructure — and get …
`grid_get_app_source`	Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and re-plug the SAME URL when you no longer …
`grid_login`	Start a CLI-free CloudGrid sign-in.
`grid_login_status`	Finish a sign-in started by grid_login.
`grid_visibility`	Change who can see a CloudGrid inspiration OR runtime app/agent.
`grid_check_deploy`	Check whether an async runtime-app build has finished and the app is live.
`grid_list_grids`	List the signed-in user’s grids, each with slug, name, role, and provisioning status.

CLI-wrapping tools

Local edition only. These wrap grid CLI commands and need the CLI’s stored credentials.

Tool	Wraps	Summary
`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 an entity’s visibility and print its URL.
`grid_feedback`	`grid feedback`	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`	List CloudGrid grids, entities, or spaces.
`grid_describe_grid`	`grid describe`	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 plug` updates it IN…
`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_delete`	`grid delete`	Archive a CloudGrid inspiration.
`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`	Return the public URL for an entity.

Collab, pull, or pick up

grid_collab, grid_pull, and grid_pickup all act on an entity that already exists, and they are easy to confuse. They do three different things:

Tool	What it does	Same entity?
`grid_collab`	Gets you push access to the same live entity that someone else owns. Grants permission only and downloads nothing.	Yes
`grid_pull`	Continues an entity you already have access to, editing it in place.	Yes
`grid_pickup`	Makes your own copy: a new entity with its own identity and URL, lineage back to the source, and the source’s secrets scrubbed.	No, a separate copy

The order matters. grid_collab is the access step: it makes you a collaborator on the shared entity and fetches nothing, so after it succeeds you run grid_pull to get the code, and your next grid_plug updates that shared entity in place where the whole team sees the new version. grid_pull on its own assumes you were already the owner or already a collaborator. grid_pickup never touches the original: it mints a separate entity that is yours, so a change to your copy is invisible to the source and the other way round.

Reaching for grid_pickup when the user asked to collaborate is the mistake this distinction exists to prevent: your own private copy is not push access to the shared entity.

If the owner gates who may join, grid_collab does not fail with an error. It turns into a request for access sent to the owner, and once they approve you call grid_collab again to join. All three tools are available on both editions, local and hosted.