Grain

A fast SQL workspace for VS Code and MCP-enabled AI agents.

Run SQL in VS Code, manage database profiles securely, inspect results in a high-performance grid, and expose safe, visible database tools to Claude, Cursor, Copilot, and other Model Context Protocol clients.

Why Grain?

Grain is built for the workflow where humans and agents both need real database context:

• Query from the editor: open a .sql file, press Cmd+Enter or Ctrl+Enter, and inspect results without leaving VS Code.
• Manage real connection profiles: create, test, select, and migrate database connections from the Grain panel.
• Give agents safe, visible access: expose read-only MCP tools for running queries, listing schemas and tables, describing columns, and inspecting shared result tabs. Agent queries are restricted to read-only SQL by default, and an agent attached through the packaged bridge cannot change your saved connections or ask for your stored credentials.
• Stay local-first: there is no hosted Grain service and no bundled AI model. Credentials are never kept in a configuration file; the service picks an operating system credential helper, the OS keychain, VS Code's Secret Storage, or — only when none is available — a local file protected by filesystem permissions, in that order of preference.

Highlights

• Connection manager with dynamic connector forms, active profile selection, legacy settings migration, and per-connection password actions.
• Tabbed result grid powered by AG Grid with sorting, filtering, column type display, adjustable density, TSV copy, and full export to CSV, TSV, or JSON that re-runs the query to fetch every row.
• Daemon-backed execution so heavy queries do not block the editor and results can be shared across VS Code, browser, and MCP surfaces.
• MCP server for Claude Desktop, Cursor, Copilot, and other MCP clients, with safe mode enabled by default for read-only operation.
• Multi-surface sessions so agent-triggered and editor-triggered work can be inspected through the same local daemon without tab ID collisions.
• Transparent telemetry that follows your VS Code telemetry setting and can be turned off at any time. Crash reports carry redacted stack traces, with file paths reduced to their extension and usernames removed. It never sends SQL text, results, credentials, hostnames, database names, schema/table/column names, workspace names, or raw driver error messages. The separately controlled replay capability masks every rendered character and input.

Supported Databases

Grain ships connector metadata and setup forms for:

Trino/Presto and PostgreSQL are bundled into the extension build. Native and cloud-provider connectors are lazy-loaded and may require their driver runtime in the active environment; Grain reports guided missing-driver errors instead of failing silently.

Quick Start: VS Code

1. Install Grain from the VS Code Marketplace or OpenVSX.
2. Run Grain: Manage Connections from the Command Palette.
3. Add a connection profile, set its password, test it, and make it active.
4. Open a .sql file and press Cmd+Enter on macOS or Ctrl+Enter on Windows/Linux.

Results open in the Grain panel at the bottom of the editor. To force a new tab, run Grain: Run Query in New Tab.

Migrating from Legacy Settings

If you previously configured sqlPreview.host, sqlPreview.port, sqlPreview.user, sqlPreview.catalog, sqlPreview.schema, or sqlPreview.databasePath, open Grain: Show Welcome Guide or Grain: Manage Connections. Grain can import those settings into a named connection profile and keep passwords in VS Code Secret Storage.

Quick Start: MCP Agents

One command

npx -y grain-tools --stdio

That is the command every MCP client is given, on every platform. There is no second setup path.

1. Run Grain: Manage Connections and confirm your active connection.
2. Open the Grain settings panel and enable the MCP server (grain.mcpEnabled). This is required and ships off — the daemon serves no MCP surface until you turn it on.
3. Keep safe mode enabled unless you explicitly want agents to run mutating SQL.
4. Give your client the command:
   • Claude Code: claude mcp add grain -- npx -y grain-tools --stdio
   • Cursor: Settings → MCP Servers → Add new MCP server, type command, command npx -y grain-tools --stdio
   • VS Code: open the Extensions view, search @mcp Grain, and install it into your user profile or the current workspace — the gallery entry carries the command
   • Claude Desktop and other file-configured clients: see the setup guide, which transcribes the same command into that client's config file

This bridges to the daemon the VS Code extension is already running, so agent queries and sessions show up in the results grid alongside anything you run from the editor. It works with every MCP client — including ones that cannot send custom HTTP headers, such as Claude Desktop — and it needs no credential in your config, because the bridge reads the daemon's access token itself.

-y is not decoration: an MCP client starts the server with no terminal attached, so npm's install prompt would have nobody to answer it.

Enabling grain.mcpEnabled in the Grain settings panel is required for this stdio bridge too. Launching the bridge without it produces a clear refusal rather than a silent failure. If you want to refuse MCP everywhere, including this bridge, set "mcp": { "enabled": false } in ~/.grain/daemon.json.

Advanced: HTTP

The daemon requires an authorization token on every non-public route, so an HTTP client must send it. Use this when your client supports custom headers (Cursor and VS Code do):

{
  "mcpServers": {
    "grain": {
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

PORT is not a fixed number. The daemon asks the operating system for a free port and writes the address it got to ~/.grain/endpoint.json, so that two accounts on one machine, two editors, or a container never compete for the same one. Read the current port from that file, or copy the whole snippet — port and token already filled in — from the Grain settings panel, which is the intended route.

Because the port changes when the daemon restarts, a hand-written HTTP config goes stale. The stdio setup above needs no port at all and is the recommended path for that reason.

To pin a port deliberately — a deployed host, or a client that cannot be reconfigured — start the daemon with --port <number>, or set GRAIN_PORT. A pinned port is used exactly as given and never reassigned.

The token also lives at ~/.grain/auth-token; treat it like a password, since it authorizes access to your connections and query results.

Upgrading from 0.6.x? Three things changed. A bare {"url": "http://localhost:8414/mcp"} config no longer connects — switch to the stdio config above (recommended) or add the Authorization header. 8414 is also no longer the port: the daemon takes a free one and publishes it, so an HTTP config that names any fixed port needs either the current port from ~/.grain/endpoint.json or an explicit --port to pin one. The stdio config avoids the question entirely. And grain.mcpEnabled now genuinely gates the surface: with it off, /mcp returns 404, because the route is not registered rather than being registered and refused. Previously the setting only decided whether the daemon started eagerly, so HTTP MCP answered whether or not you had enabled it.

Standalone / stdio Server with its own connections

For CI jobs or any client that should not share the editor's daemon, the same command carries its own connection profiles through the environment:

GRAIN_CONNECTIONS='[{"id":"analytics","name":"Analytics","type":"postgres","host":"localhost","port":5432,"user":"analyst","database":"warehouse","password":"YOUR_PASSWORD"}]' \
  npx -y grain-tools --stdio

The same variable goes in an env block for a file-configured client; see the setup guide.

--stdio first looks for a shared daemon — for example, one started by the VS Code extension — and, if it finds one, bridges to it, so the agent's queries and sessions still appear in the VS Code grid exactly like the HTTP form above. It resolves the address in one order: an explicit --port/--host, then GRAIN_MCP_PORT, GRAIN_PORT or MCP_PORT, and otherwise the address the daemon published in ~/.grain/endpoint.json. There is no fallback port to guess at: if nothing is pinned and nothing is published, there is no daemon to attach to. If no shared daemon is reachable, it falls back to starting its own embedded, isolated daemon exactly as before. Pass --embedded or set GRAIN_EMBEDDED=1 to force the isolated daemon unconditionally, which is recommended for CI and other headless runs that shouldn't depend on (or interfere with) a locally running instance. The MCP initialize response explicitly reports Grain isolation mode: shared or isolated in its standard instructions field. Agents can use that protocol signal to tell whether their query sessions are visible in the user's editor; stderr is not required for detection.

The extension and the daemon now agree on the address by publication rather than by both guessing the same default: the daemon writes where it actually bound, and the extension reads it. The endpoint-mismatch warning still fires when a pinned port disagrees with a running daemon's published one. It remains detection, not automatic correction: align the settings or remove the custom port.

Two accounts on one machine, two editors, and a container each get their own daemon and their own address, because the address lives in each config directory rather than being one number for the whole machine. Setting GRAIN_HOME selects which config directory — and therefore which daemon — a client uses.

The MCP server exposes tools for:

Safe mode is on by default and restricts agents to read-only statements such as SELECT, SHOW, DESCRIBE, EXPLAIN, WITH, and connector-specific metadata queries.

See the full MCP client setup guide and daemon URL reference for advanced configuration.

Configuration

Most users should use Grain: Manage Connections instead of editing settings JSON by hand.

Legacy connection settings such as sqlPreview.host, sqlPreview.port, sqlPreview.user, sqlPreview.catalog, sqlPreview.schema, and sqlPreview.databasePath remain available for migration and backward compatibility.

Passwords and Secrets

Passwords entered through the VS Code connection manager are stored per connection in VS Code Secret Storage, backed by the operating system keychain. They are not written to settings.json or sent to the webview.

Use these commands when needed:

• Grain: Set Connection Password
• Grain: Clear Connection Password
• Grain: Manage Connections

Managed Machines

On most machines Grain runs as one background service the system keeps alive. On a machine whose policy forbids that, Grain starts on demand instead. The practical difference is that the first request after a pause takes a moment longer; nothing else changes.

Telemetry

Grain telemetry is enabled by default when VS Code telemetry is enabled, and you can turn it off at any time with grain.telemetry.enabled. Events are anonymous and allowlisted, and are used to improve setup, connector reliability, query workflows, MCP adoption, and product quality.

When something crashes, Grain sends a redacted stack trace so the failure can be diagnosed without asking you for logs. Before anything leaves your machine, file paths are reduced to their extension (<path>/*.sql) and usernames are removed; paths that point at code keep only the part from node_modules/ or the build directory onward. If redaction fails for any reason, the report is dropped rather than sent.

Grain never sends SQL text, query results, credentials, hostnames, database/schema/table/column names, workspace names, environment variables, process arguments, or raw driver error messages. A driver's error message can embed table names, column names, and literal data values, so crash reports carry the error's type and its stack — not the message text.

Session replay is separately feature-flagged and disabled by default. When it is enabled, it covers only the VS Code results webview and masks every rendered character and input; it does not record SQL, results, or other displayed content.

Use Grain: Show Telemetry Status to inspect the effective telemetry state.

Architecture

Grain uses a local daemon model:

VS Code extension / MCP client / browser surface
        |
        v
Grain daemon on localhost
        |
        v
Database connector
        |
        v
Your database

The daemon owns connection profiles, query execution, result tabs, MCP transports, and browser/VS Code projections. That lets editor sessions and agent sessions share the same local state while keeping credentials and execution on your machine.

Release Notes

See Changelog.md for the full release history.

Contributing

Contributions are welcome, especially new connector support, reliability improvements, and documentation fixes. See CONTRIBUTING.md for setup instructions and development workflow.

Found a bug? Open an issue on GitHub.

License

MIT (c) 2026 Mehul Fadnavis