Remote MCP

Grain runs a remote MCP server at https://api.rungrain.com/mcp. When you connect an MCP client to it, you choose one Grain workspace, and the client can run shell commands and write files in that workspace's computer.

The workspace persists between sessions. It pauses when idle and resumes on the next call with its files and installed packages intact. You don't need the Grain Mac app or the grain CLI, and you don't need an API key: the client signs you in through your browser.

This is a different server from the local grain mcp server described in MCP Setup. The local server creates, saves and shares grains from your Mac. The remote server gives an agent a computer to work in, scoped to one workspace.

Connect Claude Code

1. Add the server:

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

2. Start Claude Code, run /mcp, select grain and choose Authenticate. A browser window opens.

3. Sign in to Grain.

4. Choose Create a new workspace (and give it a name), or Use an existing workspace. The page shows which organization the usage is billed to.

5. Choose Approve. The browser returns you to Claude Code, and the exec, write_file and workspace_info tools become available.

To check the connection, ask Claude to call workspace_info. It returns the workspace name, its organization and a link to open it in Grain.

Connect another MCP client

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect. Give it the server URL:

https://api.rungrain.com/mcp

The client finds everything else itself. An unauthenticated request gets a 401 pointing to https://api.rungrain.com/.well-known/oauth-protected-resource/mcp, which names Grain's authorization server. Its metadata is at https://api.rungrain.com/.well-known/oauth-authorization-server. Clients register themselves (dynamic client registration) and sign in with the authorization code flow and PKCE. The sign-in page is the same one described above.

Because self-registered clients can't be verified, the sign-in page marks them Unverified app. It also shows where you'll be sent back to. Only approve a connection you started yourself.

The server only accepts POST requests. Clients that only speak the older HTTP+SSE transport won't work.

Tools

exec

Runs a shell command in the workspace with bash -lc, as the node user.

The result has exit_code, stdout, stderr, timed_out, truncated and duration_ms. stdout and stderr are each capped at 1 MiB, and truncated is true when output was cut. For large output, redirect it to a file and read it in parts.

A connection can run at most two commands at the same time. Long commands send progress updates every 20 seconds if the client asks for them.

write_file

Creates or replaces a UTF-8 text file.

It returns the file's path and size in bytes. To read or list files, use exec with cat, ls or head.

workspace_info

Takes no input. Returns workspace_id, name, organization_name and url, the link to open the workspace in Grain.

Where files live

Everything the agent does happens in /project/workspace. Keep anything you want to keep there. If the workspace has an app, its source is in /project/workspace/app.

A new workspace created during sign-in uses the empty template, a Vite-style runtime. You can open it in Grain from the link workspace_info returns. See Runtime for how app workspaces work.

Billing

Commands run on the workspace's computer, so usage is billed to the organization that owns the workspace, the same as any other runtime use. If that organization can't run workspaces right now, tools return billing_blocked.

Permissions and security

• A connection reaches exactly one workspace: the one you chose when you approved it. It can't see or change your other workspaces.
• It acts as you. You need builder access (the builder or owner role) in the workspace's organization, and Grain checks that on every request. If you lose that access, the connection stops working right away.
• The client holds an access token that lasts one hour and a refresh token that lasts 30 days from its last use. Refresh tokens rotate each time they're used. You don't handle any of these yourself.
• HTML workspaces have no computer, so they can't be connected. They don't appear in the workspace list during sign-in.

Disconnect

Remove the server from your client. In Claude Code:

claude mcp remove grain

That stops your client from using the connection. Grain supports standard OAuth token revocation, so a client that revokes its tokens ends the connection right away. If it doesn't, its refresh token expires 30 days after it was last used. Grain doesn't yet have a page that lists or revokes connections. Removing someone's builder access, or deleting the workspace, cuts off their connections immediately.

To connect to a different workspace, clear the client's authentication for grain (in Claude Code, from /mcp) and sign in again. You'll pick a workspace again.

Troubleshooting

HTTP errors come back on the request. Tool errors come back as a failed tool result with an error_code.

If the sign-in page says You need builder access to a Grain organization to connect a workspace, your account isn't a builder or owner in any organization. Ask an owner to change your role, or sign in with a different account using Switch account.