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 work in both editions, and CLI-wrapping tools available only in the local edition.

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

Note

Several tools were renamed to match the CLI verbs (e.g. grid_deploy → grid_plug, grid_copy_app → grid_fork, grid_claim_anonymous_deploy → grid_pickup, grid_download_source → grid_download, grid_fetch → grid_get_template, grid_source → grid_get_app_source, grid_set_sharing → grid_visibility). The old names stay registered as deprecated aliases so existing callers keep working — always prefer the new names shown below. grid_remix is new.

Agent-orientation tools

These front-load how to build on CloudGrid, then load specifics on demand. Available in both editions.

Tool	What it does
grid_start	Returns the CloudGrid operating playbook and an index of available workflows. An assistant calls this first to orient, then follows the workflow → template → build → deploy → share loop.
grid_get_template	Retrieve a specific corpus entry by {kind, name}, where kind is one of workflow, template, example, rule, troubleshooting, or doc. For example, grid_get_template({kind: "doc", name: "cloudgrid-yaml"}) pulls the manifest reference.
grid_report	Send a consent-gated bug report to the CloudGrid team after a failed build/deploy. Only sent with the user’s explicit agreement; the full conversation is never included unless the user opts in.
grid_note	Optionally record a one-paragraph summary of what was built this session and why, for CloudGrid QA. Call it before a deploy, or in a session that ends without one — a successful deploy posts the session’s QA record on that same call, so pass session_note on grid_plug instead. Read-only, no side effects.

Direct-API tools (both editions)

These call the API directly, so they work in the hosted web edition as well as locally.

Tool	What it does
grid_plug	Deploy or publish an app, website, game, or single HTML page and get a live URL — the one create / re-plug verb (POST /api/v2/plug). No target_entity_id → create a new entity; with it (or grid+slug) → update the same entity in place (same URL). Source via inline html (a single page), a path folder (local edition), or inline artifact_files. Deploying a folder that already carries a cloudgrid.yaml returns needs_confirmation first — re-call with confirm_new_app: true to create it as a new app, or pass target_entity_id to update the existing one. Accepts optional user_request and session_note fields, recorded for CloudGrid quality review; they never change the deploy. This is the only deploy/publish tool — there is no separate update or redeploy tool. deploy/publish/ship/make live all route here. (grid_deploy is kept as a deprecated alias; the CLI verb grid plug is unchanged.)
grid_get_app_source	Fetch the current HTML of a published inspiration by URL or id, so an assistant can edit an existing page and re-plug it in place. Returns the HTML plus edition metadata (kind, whether it is a single editable file, and whether you can re-plug it).
grid_pickup	Pick up (adopt) an entity into the signed-in account’s active grid — an ownership transfer that keeps the same public URL (POST /api/v2/entities/:id/pickup). Use it to take over an entity you have access to, or to keep an anonymous drop you created: pass the drop’s claim_token and it becomes owned and stops expiring. Requires sign-in; works on both editions. Claiming an anonymous drop is just grid_pickup with claim_token — mirrors the CLI’s grid pickup --claim-token; there is no standalone claim tool. (Renamed from grid_claim_anonymous_deploy, kept as a deprecated alias.) On the local edition, grid_edit_existing_app additionally downloads the source and links the folder for editing.
grid_fork	Fork an entity: start a NEW entity from an existing one, carrying the source bytes, with lineage recorded (POST /api/v2/runtimes/:id/fork, falls back to inspirations). Lands in the source’s home grid (cross-grid only for system templates or forkable:'public' sources — for a general cross-grid copy use grid_remix). Requires sign-in. (Renamed from grid_copy_app, kept as a deprecated alias.)
grid_remix	Remix an app: make your own copy of any app you can see (link / public / authenticated, or a grid you belong to) into any grid you can build in — cross-grid allowed (POST /api/v2/runtimes/:id/remix). Mints a new entity with lineage back to the source, without the source’s secrets (set your own before you plug). Distinct from grid_fork (same-grid, byte-carrying). Requires sign-in.
grid_download	Download an entity’s source — signed, time-limited (about 15 minutes) read URLs, one per service tarball (GET /api/v2/runtimes/:id/source). No entity is created and nothing changes (unlike grid_pickup/grid_fork/grid_remix). Requires sign-in. (Renamed from grid_download_source, kept as a deprecated alias.)
grid_visibility	Change who can see an inspiration: private, space, authenticated, org, or link. Defaults its target to the thing published this session, so “make it private” needs no id. Requires sign-in. (grid_set_sharing is kept as a deprecated alias.)
grid_list_grids	List the signed-in user’s grids, each with slug, name, role, and provisioning status. Requires sign-in.
grid_login	Start a CLI-free sign-in. Returns a URL to open; then call grid_login_status to finish.
grid_login_status	Finish a sign-in started by grid_login. Polls once and saves the session on success.

CLI-wrapping tools (local edition only)

These wrap the grid CLI, so they need a local machine and the CLI’s stored credentials. Each maps to the CLI command shown.

Tool	Wraps	Notes
grid_create_project	grid new	Scaffold an app or agent folder (cloudgrid.yaml + a starter service); no server entity until you plug.
grid_view_logs	grid logs	Snapshot of recent logs (does not stream). Read-only.
grid_share	grid visibility set	Set visibility, defaulting to link.
grid_feedback	grid feedback list	Read the feedback feed. Read-only.
grid_whoami	grid whoami	Show the signed-in user and active grid. Read-only.
grid_switch_grid	grid use	Switch the active grid.
grid_logout	grid logout	Sign out and clear credentials. Destructive.
grid_status	grid status	Grid dashboard or entity detail. Read-only.
grid_info	grid info	Entity metadata. Read-only.
grid_get	grid get	List grids, entities, or spaces. Read-only.
grid_describe_grid	grid describe grid	Grid detail. Read-only.
grid_edit_existing_app	grid pickup	Download an entity’s source and bind the folder.
grid_rename	grid rename	Rename an entity’s display name.
grid_take_offline	grid unplug	Take an entity off the grid. Destructive.
grid_delete	grid delete entity	Archive an inspiration. Destructive.
grid_rollback_deploy	grid rollback	Roll back to a previous version.
grid_list_versions	grid versions	List published versions. Read-only.
grid_set_env	grid env	Get, set, or list environment variables.
grid_set_secret	grid secrets	Set or list secret names. Never returns values.
grid_scaffold	grid scaffold	Generate starter files.
grid_diagnose	grid doctor	Run local diagnostics. Read-only.
grid_get_url	grid open --print	Return the public URL (does not open a browser). Read-only.

Note

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, defaults its target to the session’s last publish, and is the one the web edition gets.

Documentation search server

Separate from the build/deploy tools above, CloudGrid runs a public documentation-search MCP server — no account and no CLI required. Connect it to give an assistant read-only access to these docs. It exposes two tools:

Tool	What it does
grid_search_docs	Search the CloudGrid documentation — guides, CLI reference, MCP setup, skills. Returns the most relevant chunks with title, snippet, and source path. Takes a query string.
grid_quickstart	Return the CloudGrid quickstart guide — the canonical scaffold → deploy → feedback loop.

Note

These two were previously named search_cloudgrid_documentation and cloudgrid_quickstart_guide. Those names remain registered as deprecated aliases (same behavior) for backward compatibility and will be removed in a future major version — use the grid_* names.