AI agents and MCP

Let an AI coding agent work with Groundfloor through the Groundfloor MCP and the gf CLI — and the rules it should follow.

AI coding agents, such as Claude Code, Cursor or Codex, can work with Groundfloor for you. The Groundfloor MCP lets an agent look at your workspace and read these docs; the agent then makes changes with the gf CLI. Every MCP tool only reads, except coderunner_cancel_deployment, which deletes a deployment. See The one MCP tool that deletes.

Set it up

An agent can't complete a browser sign-in, so a person runs gf login and gf workspaces use <workspace-id> first. The MCP and the CLI then use that session. An agent runs gf without a terminal, so gf deploy won't use that saved workspace on its own: the agent passes -w <workspace-id>, or you set GROUNDFLOOR_WORKSPACE_ID (why).

Add the MCP to your agent

Most agents read an MCP config like this, for example .mcp.json in your project:

.mcp.json

{
  "mcpServers": {
    "groundfloor": { "command": "npx", "args": ["-y", "@groundfloorcloud/mcp"] }
  }
}

Never put a token in this file. In Cursor on macOS, npx may fail to start; install it globally with npm install -g @groundfloorcloud/mcp and point the config at that install instead. The Shell starter kit already includes this config.

What the MCP offers

Tool	Gives the agent
`whoami`, `workspace_context`	Who's signed in, and what's in the workspace: Coderunners, apps, environments and more
`workspaces_list`	The workspaces you can access
`docs_list`, `docs_get`	These docs, by topic, such as `coderunner`, `shell`, `feature-flags`, `databases`
`suggest_cli`	The exact `gf` command for a goal: deploy, run, publish, logs, secrets, flags
`coderunner_list`, `coderunner_get_status`, `coderunner_process_log`, `coderunner_get_logs`	Your Coderunners, their status and their logs
`apps_list`, `apps_get`, `environments_list`, `secrets_list`, `flags_list`, `files_list`	What exists. Secret values are never returned
`domains_list`	A standalone app's custom domains, by `app_id` or by the app's main Coderunner as `coderunner_id`. Coderunners have no domains of their own
`dataplane_status`	The status of the workspace's data plane
`quota_get`, `billing_summary`	Your organization's plan usage and limits, and spend (Owners, Admins and Billing admins only)
`coderunner_cancel_deployment`	Deletes a deployment. The only tool that changes anything

The one MCP tool that deletes

coderunner_cancel_deployment does the same as gf coderunner cancel-deployment --deployment-id: it deletes one deployment of a Coderunner. If it's the live deployment, the Coderunner goes offline. The agent must pass a deployment_id, which it can read with coderunner_get_status; there is no default. The tool acts only on the workspace the MCP is set up with (your gf workspaces use default or GROUNDFLOOR_WORKSPACE_ID), never on one the agent names. Any workspace role that can deploy (Writer and above) can do this.

Don't auto-approve this tool. It is marked destructive, but in your agent's permission settings leave coderunner_cancel_deployment on "ask every time" even if you allow the other Groundfloor tools.
If your agent never needs to delete deployments, deny the tool outright.
Treat the other tools as safe to auto-approve: they only read.

The suggest_cli tool description says the MCP "does not execute mutations". That is not true for this tool.

Rules for agents

Give your agent these rules, or point it to this page. They prevent the most common mistakes.

Pick the path from the goal.

The user wants…	Do this	Don't
To run code: a function, job, schedule or service	`gf deploy`	Create an app for it
To publish a Shell app's UI	`gf apps init`, then `npm run release` and `gf apps publish`	Run `gf deploy` on the starter kit
To package an existing Service as a product	`gf apps create --kind standalone --primary-coderunner <id>`	—

Inspect before acting. Call workspace_context and docs_get, then run the command suggest_cli returns. Don't call coderunner_cancel_deployment unless the user asked you to delete a deployment.
Reuse what exists. If a Coderunner or app with that name already exists, deploy to it instead of creating another. Updating an existing Coderunner needs gf deploy --yes when there's no terminal, so check it's the right one first.
Never put secrets or .env files in code or uploads. Store them in Secrets and read them at runtime; see Configuration and secrets.
Use built-in features instead of building them. Feature toggles go in feature flags, not a Data Vault collection or .env. Data goes in the workspace's database, which already exists.
Report what you did. After deploying, give the Coderunner, version and deployment IDs and the Deployment URL. If a deployment fails, read its logs with gf coderunner logs.

When an agent gets `403`

Check who is calling before changing anyone's role:

Caller	Usual cause	Fix
A team member, with `gf token`	Their workspace role is too low	Writer to change data or deploy, Admin to create collections. See Team and roles
An app user, from a Shell app	Their role has no grant on that collection	Grant it on Site access. New collections are open only to `admin`
A Coderunner, with an M2M token	Reading secrets without Read secrets, or changing flags	Turn on Read secrets; change flags with the CLI. See M2M tokens

Don't fix an app user's 403 by giving them a team role; that grants far more than they need.

Next steps

gf CLI — every command.
Deploy and Shell apps — what the agent is building.

AI agents and MCP

On this page