Developer Guide

Grain is an agent-agnostic workspace for artifacts: pages, reports, walkthroughs, dashboards, internal apps and bounded jobs. An agent authors files, Grain keeps the workspace and its history, and a runtime is available when the artifact needs code execution.

Choose an interface

You need to…	Use	What it is	Start here
Create and share a file-based artifact	CLI or MCP	Local tools backed by the Grain desktop app and workspace service	Install → First artifact
Let a coding agent work with Grain	MCP	A local stdio Model Context Protocol server started by grain mcp	MCP setup
Let a remote MCP client such as Claude or ChatGPT find, create, edit and share grains	Remote MCP	A hosted MCP server at api.rungrain.com/mcp, signed in with OAuth	Remote MCP
Script workspace SQL, registered commands or a remote shell	HTTP API	The supported HTTPS contract at api.rungrain.com	HTTP API
Add Grain’s built-in workflow to Claude Code or Codex	Native plugin	A local plugin payload bundled with the desktop app	Integrations
Build an app instead of a static page	CLI/MCP plus an app runtime	A workspace promoted to a Next.js or React/Vite runtime	Runtime

These are different surfaces. The local MCP server is JSON-RPC over stdio and is not a REST endpoint. The HTTP API is not an MCP server; the hosted MCP server is Remote MCP. There is no released public Grain SDK or generic plugin SDK in the current package boundary.

What a workspace gives you

1. A checkout is the local editing copy returned by grain checkout or grain new --checkout.
2. A workspace is the durable remote home for the files, history and optional app data.
3. A sandbox is runtime compute used by an app or command; it is not the same thing as the durable artifact.
4. A share is an explicit delivery choice. Work remains private until you create a public or password share.

For static work, the shortest path is grain init → edit → grain push → grain checkpoint → grain share --public. For MCP, use the corresponding grain_new/grain_artifact, grain_push, grain_checkpoint, and explicit share tools. For an app, push first, promote it, poll until runtimeReady: true, then run or test through the runtime.

Current, legacy and internal

• Current/released: the Grain desktop app for macOS, Windows and Linux, its bundled grain CLI, the local stdio MCP server, 33 MCP tools, native Claude Code/Codex plugin payloads, and the published HTTP API described in the OpenAPI document.
• Legacy: old morph names, old morph_* or permissive grain_share registrations, and standalone skill/config entries left by earlier desktop setup. Re-register grain and use the explicit share operations.
• Internal: repository routes for control-plane UI, billing, organizations, content synchronization and development infrastructure are not automatically public APIs. Use only the HTTP operations listed in HTTP API.
• Unreleased/source-only: default-branch changes can be newer than the desktop release or deployed website. This guide describes the current supported contract; check the release boundary in Data and privacy when a version matters.

A complete first session

1. Install the app-managed CLI and run grain login.
2. Publish a complete HTML artifact and verify its workspace URL and checkpoint.
3. Keep it private while editing; use sharing and persistence guidance when it is ready.
4. If an agent should operate Grain, configure MCP or a native integration.
5. If the artifact needs a database, commands or compute, follow runtime guidance, including push-before-exec and operation polling.
6. For service-to-service automation, use the external HTTP API and its downloadable OpenAPI contract.