MCP setup and tools

Q: Where does an MCP agent run tests?

It pushes edits first, then calls grain_exec so tests run in the workspace sandbox rather than the local checkout.

Grain exposes eleven MCP tools over stdio so a coding agent can create, inspect, edit, publish, run and share workspace artifacts. Initialization writes the recognized agent config, while the agent calls tools with the grain_ prefix.

Updated 2026-09-04Facts verified 2026-09-04By the Grain team

Configure the stdio server

The initialization command recognizes .mcp.json for Claude Code, .codex/config.toml for Codex and .cursor/mcp.json for Cursor. Existing recognized files are updated; when none exists, .mcp.json is created. The server command has no flags.

grain mcp

Expected behavior is a long-running stdio process that responds to MCP requests. It does not print a share URL by itself. Extra arguments fail with Usage: grain mcp.

Available tools

Tool	Inputs	Use
`grain_list`	Optional `folder`, `query`	Read the folder tree and visible workspaces before selecting or creating one.
`grain_new`	Required `name`; optional `template`, `folder`	Create a hidden new workspace and return a checkout path. Templates are empty, HTML, Next.js or React with Vite.
`grain_checkout`	Optional `workspace`	Materialize or reuse the temporary local editing copy for an existing workspace.
`grain_push`	Optional `workspace`, `reload`	Publish completed edits. Reload defaults to true; force is not available through MCP.
`grain_pull`	Optional `workspace`	Recover remote drift or intentionally receive remote changes while preserving local work.
`grain_checkpoint`	Optional `workspace`, `message`	Record a durable history revision after a successful push.
`grain_exec`	Optional `workspace`; required `command` array	Run a bounded foreground command inside the workspace runtime.
`grain_open`	Optional `workspace`	Open an existing ready workspace. Do not open a new workspace before its first successful push.
`grain_share`	Optional `workspace`, `action`, `mode`, `password`, `shareId`, `regenerateSlug`, `name`, `path`	Create, list, update or revoke shares and return both public and canonical URLs.
`grain_upgrade`	Optional `workspace`, `target`	Enable a React with Vite or Next.js runtime for a clean, pushed HTML workspace.
`grain_release`	Optional `workspace`	Remove only a clean, validated checkout after wanted work is safely pushed or preserved.

Safe agent workflow

Call grain_list when the person refers to an existing workspace by name or asks for a folder placement. Use grain_new only when the person explicitly asks to create a workspace.
For an existing workspace, call grain_checkout before editing. The returned local path is an editing copy, not the runtime.
Edit files with ordinary file tools. Do not install, build or test at the checkout path.
Call grain_push before any runtime check so the workspace receives the edits. On remote drift, call grain_pull, review the local result and retry the push.
Call grain_exec with an argv array to install, build, test or inspect inside the runtime. Persistent development servers are not supported by this tool.
After a successful push, call grain_checkpoint to preserve a named revision and grain_share to return an audience-facing URL.
Call grain_release only when the checkout is clean and all wanted work is pushed or otherwise preserved.

Expected results and failures

Situation	Result	Recovery
Successful tool call	A text rendering plus structured envelope with `ok: true`	Read returned ids, paths and URLs rather than inferring them.
Invalid input	An error tool result with the CLI error envelope	Correct the named field or enum and retry.
Remote drift on push	Nothing uploads and the result says the remote workspace changed	Pull, inspect preserved local changes, then push again.
Static workspace receives exec	The result says the HTML workspace has no compute runtime	Upgrade the clean, pushed workspace if an app runtime is actually needed.
Open before first push	The new workspace is not ready to view	Finish editing and push successfully before opening.
Dirty release	The checkout remains in place	Push wanted work or otherwise preserve it before releasing.

Sharing through MCP

The share tool defaults to the create action. It can create a public or password share, target a site path, reuse the existing share, update its visible state, regenerate its slug, list shares or revoke one. A successful create returns a shareUrl shaped like https://<slug>.share.rungrain.com and a canonical workspace URL.

Frequently asked questions

Which MCP tools does Grain provide?

List, new, checkout, push, pull, checkpoint, exec, open, share, upgrade and release, each rendered with the configured grain_ prefix.

Can an MCP agent force a push?

No. The MCP push tool intentionally omits force. Pull and review remote drift before retrying.

Where does an MCP agent run tests?

It pushes edits first, then calls grain_exec so tests run in the workspace sandbox rather than the local checkout.

Does the MCP server for Grain support persistent development servers?

No. The exec tool is for bounded foreground commands. The workspace runtime serves the published app.

Give your agent a publishing surface

Initialize a folder, confirm the generated MCP config and let the agent publish its first artifact.

Free forever. No card. Bring your own agent.

Sources · facts verified 2026-09-04

Grain product and agent support · 2026-09-04