Integrations

Grain integrations run locally on the Mac that has the Grain app. There are two supported choices:

• Project MCP configuration: grain init writes a grain mcp stdio entry to a project file. This works with Claude Code, Codex, Cursor and other clients that support stdio MCP.
• Native plugin: the Grain app provides a local marketplace payload for Claude Code and Codex. The vendor’s native plugin manager installs it into the agent.

Both choices launch the same local grain mcp server. They do not create a hosted MCP URL. MCP Setup explains the protocol and tool contract; this page focuses on client registration.

Prerequisites

1. Install the Grain Mac app and install its CLI from Settings → CLI.
2. Confirm the shell can find grain and run grain login. Login is separate from MCP registration.
3. Open the client in the project folder where the agent should work.

The production plugin launcher uses the managed wrapper at ~/.local/bin/grain and runs:

/bin/sh -c 'exec "$HOME/.local/bin/grain" mcp'

If that wrapper is missing or the app moved, repeat Settings → CLI setup. Reinstalling an agent plugin does not repair the wrapper or revoke CLI credentials.

Project-level MCP configuration

Run this from the project root:

grain init

grain init preserves unrelated configuration. It updates recognized files that already exist; if none exists, it creates .mcp.json. Use grain init --no-agent-config to create/link a workspace without writing agent files, or grain init --dry-run to inspect planned writes without mutation.

The entries it writes are:

.mcp.json (used by Claude Code and compatible clients):

{
  "mcpServers": {
    "grain": { "command": "grain", "args": ["mcp"] }
  }
}

.codex/config.toml:

[mcp_servers.grain]
command = "grain"
args = ["mcp"]

.cursor/mcp.json:

{
  "mcpServers": {
    "grain": { "type": "stdio", "command": "grain", "args": ["mcp"] }
  }
}

Start a new agent session after changing project configuration. Ask the agent to list or inspect Grain tools, then try: “Create a short private welcome document in Grain.” Seeing a server entry is not proof of authentication; the task should return a workspace URL and a successful artifact result.

grain init also manages GRAIN.md and a pointer in an existing AGENTS.md or CLAUDE.md. It does not create AGENTS.md or CLAUDE.md, and it preserves user-owned instruction files. See MCP recovery when an agent has stale instructions.

Claude Code native plugin

Open Settings → Integrations in the Grain app to prepare the local marketplace, then run:

claude plugin marketplace add "$HOME/.grain/plugins/marketplace"
claude plugin install grain@grain-plugins --scope user
claude plugin list --json
claude plugin details grain@grain-plugins

The supported validation baseline is Claude Code 2.1.269 or later. After a Grain app update, refresh both the marketplace and installed plugin:

claude plugin marketplace update grain-plugins
claude plugin update grain@grain-plugins --scope user
claude plugin list --json

To remove it:

claude plugin uninstall grain@grain-plugins --scope user

Codex native plugin

Prepare the marketplace in Settings → Integrations, then run:

codex plugin marketplace add "$HOME/.grain/plugins/marketplace"
codex plugin add grain@grain-plugins
codex plugin list --json

The supported validation baseline is Codex CLI 0.154.0 or later. Codex refresh uses remove/add:

codex plugin remove grain@grain-plugins
codex plugin add grain@grain-plugins
codex plugin list --json

Start a new session after install or update. grain logout is separate from plugin removal. The optional “Use Grain by default” preference is also separate: installing the plugin does not silently change where an agent saves artifacts.

Duplicate and legacy registrations

An older user-level MCP entry can create duplicate tools. Inspect and remove only the selected old provider entry with the vendor command, for example:

claude mcp remove grain --scope user
codex mcp remove grain

Project entries created by grain init are independent and may still be active. Review them before deleting anything. Do not use a production plugin to connect a development checkout; development checkouts use their own manual absolute launcher.