Connect your AI tool

Grain is a place where AI agents build and keep their work: documents, dashboards and apps, each called a grain, stored in a workspace that stays online after the conversation ends. To let an AI tool work in Grain, you connect it to one of Grain's two MCP servers.

• Hosted server, at https://api.rungrain.com/mcp. It works from Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code and any other MCP client, on any computer, and you sign in through your browser. The AI can find, read, create and edit your grains, turn off share links, and run commands in app grains. Start here, unless you need the local server's extras.
• Local server, on a Mac with the Grain app. It works on grains as folders on your Mac, so your coding agent can edit them with its own tools, and it can also create share links, take screenshots and open grains in the app. Choose it if you're on a Mac and want Claude Code or Codex to do those things. See Local server on a Mac.

Hosted server

Server URL: https://api.rungrain.com/mcp

To add it to Claude on the web, desktop or mobile, use Add Grain to Claude. For other clients, find yours below.

When you connect, you choose what the AI can reach, either every grain in one organization or a single grain, and what it may do there. Depending on what you allow, it gets these tools:

A single-grain connection also always has workspace_info, which names the grain and links to it.

Every grain in a result includes a https://rungrain.com/w/… link to open it. App grains have a Linux computer: the AI works in /project/workspace, the app's source code is in /project/workspace/app, and the computer pauses when idle and keeps its files and installed packages. Remote MCP documents each tool, the limits and every error code.

You need a Grain account. If you don't have one, the sign-in page lets you create one with Google, GitHub or email. The free plan needs no card. Reading and editing HTML grains doesn't use a computer. Commands run on an app grain's computer, so they count toward the plan of the organization that owns it; see Pricing.

Quick setup for coding agents

add-mcp is an open-source installer. It finds the coding agents on your computer (Claude Code, Codex, Cursor, VS Code, Gemini CLI, Windsurf, Zed and others) and writes the server into each one's own config file. It changes the config of every agent it finds, so if you only want one, use that agent's steps below instead. It needs Node.js 18 or later.

npx add-mcp https://api.rungrain.com/mcp --name grain-remote --global

Drop --global to write project config files in the current folder instead. It only adds the server; you still sign in from each agent, the way its section below describes (in Claude Code, run /mcp, select grain-remote and choose Authenticate).

It can't add Grain to Claude on the web or ChatGPT, because those connectors live in your online account. Use the steps below for those.

What happens when you sign in

Every client uses the same Grain sign-in page:

1. Your browser opens a Connect to Grain page. Sign in, or create an account.
2. Under Access, choose All grains in an organization (the default), One existing grain, or One new app workspace, which creates an empty app grain for the AI to work in.
3. Under Permissions, untick anything you don't want to allow. When commands are allowed, the page shows which organization is billed for them.
4. Choose Approve. The browser returns you to your client.

The page shows where the client's details come from and where you'll be sent back to. Claude (including Claude Code), ChatGPT and VS Code publish their details on their own sites, so they show no badge. Other clients, such as Cursor, are marked Unverified app. Only approve a connection that you started yourself.

You need the builder or owner role in the organization. A new account is the owner of its own organization, so this works out of the box.

To check the connection, ask the AI: "List my Grain grains." It calls search_grains and replies with names and links.

To see or end your connections later, open Connected apps and choose Disconnect. That works for every client.

Claude (claude.ai, Claude Desktop and mobile)

Add Grain to Claude

1. Open the link. It fills in the name Grain and the URL https://api.rungrain.com/mcp. Check the URL, then choose Add.
2. Choose Connect next to Grain, then sign in.
3. In a chat, open the + menu, go to Connectors, and turn Grain on.

To do it by hand, open Customize → Connectors, choose + → Add custom connector, and paste https://api.rungrain.com/mcp. A connector you add works in claude.ai, Claude Desktop and the mobile apps.

Pro and Max plans work as described. The Free plan allows one custom connector. On Team and Enterprise plans, an owner first adds Grain for the organization under Organization settings → Connectors (owner link). Members then find it under Customize → Connectors and choose Connect.

To change what Grain allows later, disconnect Grain in Customize → Connectors, then connect again and choose again.

Claude Code

claude mcp add --transport http --scope user grain-remote https://api.rungrain.com/mcp

Then start Claude Code, run /mcp, select grain-remote, and choose Authenticate. If you're on a Mac with the Grain app, you can add the local server as well. --scope user makes it available in every project. Leave it out to add Grain to the current project only.

ChatGPT

ChatGPT connects through developer mode, which needs a Plus, Pro, Business, Enterprise or Edu plan and works on chatgpt.com. A workspace admin can turn it off.

1. In ChatGPT, open Settings → Security and login and turn on Developer mode.
2. Go to chatgpt.com/plugins and choose +.
3. Name it Grain, set the MCP server URL to https://api.rungrain.com/mcp, choose OAuth, and choose Create. Then sign in.
4. In a chat, open the + menu, choose Developer mode, and select Grain.

ChatGPT asks you to confirm each tool call that can change something.

Codex

This works in the Codex CLI, the IDE extension and the ChatGPT desktop app, which share one config.

codex mcp add grain-remote --url https://api.rungrain.com/mcp

Codex notices that Grain uses OAuth and opens your browser to sign in. To sign in again later, run codex mcp login grain-remote. The entry it writes to ~/.codex/config.toml is:

[mcp_servers.grain-remote]
url = "https://api.rungrain.com/mcp"

Cursor

Add Grain to Cursor

The link asks Cursor to add the server, and you confirm it there. Then open Cursor's MCP settings and choose Needs login next to grain-remote. To add it by hand, put this in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "grain-remote": { "url": "https://api.rungrain.com/mcp" }
  }
}

VS Code (GitHub Copilot)

Install in VS Code · Install in VS Code Insiders

VS Code asks you to sign in when the server first starts. You can also run MCP: Add Server, choose HTTP, and enter the URL, or add it to .vscode/mcp.json. VS Code uses a servers key here, not mcpServers:

{
  "servers": {
    "grain-remote": { "type": "http", "url": "https://api.rungrain.com/mcp" }
  }
}

If the browser sign-in doesn't return to VS Code, choose Cancel and then the option to try a different way.

Gemini CLI

gemini mcp add --transport http grain-remote https://api.rungrain.com/mcp

Then run /mcp auth grain-remote in Gemini CLI to sign in.

Windsurf

Add this to Windsurf's mcp_config.json. Windsurf uses the key serverUrl, not url:

{
  "mcpServers": {
    "grain-remote": { "serverUrl": "https://api.rungrain.com/mcp" }
  }
}

Zed

Use Settings → AI → MCP Servers → Add Remote Server, or add this to Zed's settings.json:

{
  "context_servers": {
    "grain-remote": { "url": "https://api.rungrain.com/mcp" }
  }
}

Zed signs you in on first use.

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect with the URL https://api.rungrain.com/mcp. It finds the sign-in details itself: see Remote MCP.

If a client can only start local commands, bridge it with mcp-remote, which needs Node.js 18 or later:

{
  "mcpServers": {
    "grain-remote": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.rungrain.com/mcp"] }
  }
}

Things to ask

Once Grain is connected, try:

1. "Find my grain about the Q3 plan and summarize it."
2. "Make a one-page HTML report in Grain from this table, with a chart and a short summary. Give me the link."
3. "In my grain Weekly metrics, update the numbers from this spreadsheet and save it as a new revision titled Week 39."
4. "Which share links are active on my grain Customer demo? Turn off the public one."
5. "In my app grain Team rota, run the tests in /project/workspace/app and fix what fails."

What the hosted server can't do yet

• It can't create or change share links, only list and turn them off. Share from the Grain app or the local server.
• create_grain makes HTML grains only. To get a new app grain, choose One new app workspace when you sign in.
• update_grain saves files to HTML grains. For an app grain, the AI edits files with commands instead.
• It has no screenshot tool, and it can't open grains in the Grain app.
• It accepts POST requests only. Clients that only speak the older HTTP+SSE transport can't connect.
• A connection made before these tools existed keeps its original three tools (exec, write_file and workspace_info in one app workspace). Disconnect and connect again to get the rest.

Local server on a Mac

The local server runs on your Mac through the Grain app. It has 32 tools for creating, editing, saving and sharing grains, and it can reach every organization you belong to. It needs the Grain Mac app.

1. Download Grain for macOS and open it.

2. In Grain, open Settings → Integrations. Under Grain CLI, copy the commands and run them in a terminal. They link the grain command into ~/.local/bin and sign you in.

3. In a terminal, run:

   grain setup

   This signs you in through your browser if you aren't signed in already, installs the Grain plugin into Claude Code or Codex (whichever you have), checks that the MCP server starts, and opens Grain.

4. Start a new Claude Code or Codex session and ask it to create a short private document in Grain.

For Cursor and other clients, run grain init in a project folder. It adds a grain mcp entry to whichever of .mcp.json, .cursor/mcp.json and .codex/config.toml the project already has, and creates .mcp.json if it has none. Cursor doesn't read .mcp.json, so in a new project create .cursor/mcp.json containing {} before running grain init. Install, Integrations and MCP Setup cover each step and every tool.

You can use both servers at once. The names in this guide (grain-remote for the hosted server, grain for the local one) keep them apart.

Troubleshooting

Remote MCP lists every error code. For the local server, see Troubleshooting.