Skip to content
Grain

Connect your agent

Grain speaks the Model Context Protocol, so agent clients such as Claude Desktop, Claude Code, Cursor, Copilot, Windsurf and Codex can run queries, list schemas, and describe tables against your own databases.

Connect with one command

After installing Grain, run:

grain connect

Grain lists the agents it supports, marks the ones it found, and connects only the ones you pick. To connect without prompts, name them: grain connect --agent claude-desktop --agent cursor. grain disconnect removes Grain from your agents.

Connect manually

Install Grain first. Every client then runs the same command, on macOS, Linux, and Windows:

grain --stdio

That is the whole setup contract. Everything below is how to hand that one command to a particular client. --stdio takes no value.

The bridge attaches to the shared Grain service when it is available. If the service cannot be reached, it reports isolated mode; queries still work, but their sessions do not appear in the editor.

Claude Code, Codex, VS Code, Cursor and Windsurf pick up the PATH the installer set, so grain is enough. Claude Desktop does not read your shell’s PATH, so it gets the full path; see its section.

Before you connect

  1. Have connections. Install the extension and add a connection profile, or supply profiles through GRAIN_CONNECTIONS, as described in Headless connections.
  2. Check that MCP is on. MCP is on by default. If you turned it off, turn grain.mcpEnabled back on in the Grain settings panel, or set "mcp": { "enabled": true } in ~/.grain/daemon.json. While MCP is off, the bridge refuses with a message instead of failing quietly.
  3. Leave safe mode on unless you intend agents to run mutating SQL.

Clients that take a command

Claude Code

claude mcp add grain -- grain --stdio

Cursor

Settings → MCP Servers → Add new MCP server. Type command, name grain, command grain --stdio.

Windsurf

Settings → Cascade → MCP Servers → Add Server, then paste the same JSON as Claude Desktop below into ~/.codeium/windsurf/mcp_config.json.

VS Code and Copilot

VS Code reads MCP servers from .vscode/mcp.json in the workspace, or from your user mcp.json via MCP: Open User Configuration in the command palette. Note the key is servers, not mcpServers:

{
  "servers": {
    "grain": {
      "type": "stdio",
      "command": "grain",
      "args": ["--stdio"]
    }
  }
}

Copilot Chat in agent mode picks the server up from the same file.

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.grain]
command = "grain"
args = ["--stdio"]

Clients that take only a config file

Claude Desktop has no command-line registration, so it is configured by file. It starts servers without your shell’s PATH, so the command is the full path to grain: /Users/you/.grain/bin/grain on macOS (run echo "$HOME/.grain/bin/grain" to print yours), C:\Users\you\.grain\bin\grain.cmd on Windows (double each backslash inside JSON).

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json. Paste that path into Win + R; create the file if it is not there.
{
  "mcpServers": {
    "grain": {
      "command": "/Users/you/.grain/bin/grain",
      "args": ["--stdio"]
    }
  }
}

Restart the client fully after editing. If the file already has an mcpServers object, add only the "grain" entry inside it.

Headless connections

By default the bridge attaches to the daemon your editor is already running, so agent queries land in the same result tabs as your own. GRAIN_EMBEDDED=1 forces an isolated daemon rather than attaching to a shared one, which is useful in CI. Save connection profiles through Grain and enter credentials through its one-time credential page.

Environment variables

Variable Effect
GRAIN_CONNECTIONS JSON array of connection profiles, for headless use
GRAIN_MCP_SAFE_MODE false allows mutating SQL. Defaults to true
GRAIN_MAX_ROWS Row cap for query tools. Defaults to 10000
GRAIN_HOME Which config directory is used, and so which daemon
GRAIN_EMBEDDED 1 forces an isolated daemon instead of attaching

Without installing

A machine that has Node.js 20 or newer can run Grain from npm instead, with no install step:

npx -y grain-tools --stdio

-y skips npm’s install prompt, which a client could never answer. Use this for evaluation and headless automation. It needs Node on every machine and can run in isolated mode when no shared service is available, so installed grain is the recommended desktop path.

Advanced HTTP connection

Direct HTTP is a separately gated rollout surface. Use it only when Grain settings explicitly offers a ready-made HTTP client configuration. It requires a bearer token and exposes a port and credential to the client, so stdio remains the normal setup.

The tools you get

Grain advertises 22 tools. A tool a profile does not permit is still advertised and still answers, with an explicit refusal naming the profile, so an agent can tell “not allowed here” from “does not exist”.

Group Tools
Query run_query, cancel_query
Schema list_schemas, list_tables, describe_table
Connections list_connectors, list_connections, test_connection, create_connection_draft, save_connection, delete_connection, request_connection_credentials
Result tabs get_tab_info, close_tab, list_sessions
Demo get_demo_dataset
Other tools render_chart, save_chart, list_charts, ledger_stats, verify_ledger
Telemetry record_ui_event

An agent attached through the packaged bridge runs under the agent profile: it may read, query, draft connections, and request the one-time password page. Only save_connection and delete_connection are refused.

Troubleshooting

Symptom Cause and fix
No tools appear in the client The client was not fully restarted, or cannot find grain. Use the full path for Claude Desktop
grain not found in a terminal Open a new terminal after installing, or add ~/.grain/bin to your PATH if you installed with GRAIN_NO_MODIFY_PATH=1
The bridge starts and then stops grain.mcpEnabled is off. Turn it on, or set mcp.enabled in ~/.grain/daemon.json
Agent queries are not in the grid The bridge found no shared daemon and started its own. The initialize response reports Grain isolation mode: shared or isolated
A tool answers with a refusal The profile refuses that tool’s resource class. The message names both

Identifiers

VS Code extension id
pattrnlabs.grain
npm package name
grain-tools
stdio command
grain --stdio
stdio command without installing (needs Node)
npx -y grain-tools --stdio

MCP Configuration

{
  "mcpServers": {
    "grain": {
      "command": "grain",
      "args": [
        "--stdio"
      ]
    }
  }
}
Documentation