vgrid mcp — AI agents

VisiGrid is a first-party MCP (Model Context Protocol) server. Any local MCP host — Claude Code, Claude Desktop, Codex CLI, Cursor, and others — can read and edit a live VisiGrid window: cells change on screen as the agent works, every batch lands in your undo history as a single step, and nothing gets access until you click Allow.

claude mcp add visigrid -- vgrid mcp

That’s the entire setup. Requires VisiGrid v0.14+ running (the session server starts with the app).

First use: pairing

The first time an agent touches your spreadsheet, VisiGrid shows an approval dialog naming the client (e.g. “Claude Code”). One click grants a credential that persists across restarts — no tokens, no environment variables, no copy-paste.

Manage access from the terminal:

vgrid pair --list                    # who has access
vgrid pair --revoke "Claude Code"    # takes effect on the next connection
vgrid pair --name "My Script"        # pair ahead of time, interactively

Re-pairing under the same name rotates the credential. Setting VISIGRID_SESSION_TOKEN overrides pairing entirely (useful for CI). To turn the control socket off for a session, launch with --no-session-server.

Tools

Tool	What it does
list_sessions	Running VisiGrid windows with workbook titles and session IDs
get_workbook	Title, sheet count, active sheet, revision — the orientation call
read_range	A1-style cell or range → display values plus a map of formula cells
write_cells	Batch of values, formulas, and clears — one undo step, one recalc
set_format	Bold/italic/underline and number formats over a range

Mutating tools accept dry_run: true to preview without applying, and expected_revision for optimistic concurrency — if you’ve edited the sheet since the agent last read it, the write fails with revision_mismatch instead of clobbering your changes.

Safety model

• Consent-gated: the socket is inert until you approve a client; approval is per-client and revocable.
• Visible: agent edits render immediately in the window you’re looking at. There is no headless back door to an open workbook.
• Undoable: each write_cells batch is one Ctrl+Z away from gone.
• Validated: writes are checked against the real grid bounds and sheet list before anything is applied — a batch either fully applies or fully rejects with a structured error.
• Bounded: format operations cap at 250,000 cells per call; reads cap at 65,536 cells per request. Rate limits and a single-writer lease apply to all clients.

Other MCP hosts

Any agent that runs on your machine and speaks MCP over stdio works — Claude Code, Claude Desktop, Codex CLI, Cursor, Zed, and others. (Hosted agents like ChatGPT can’t reach a local window; their connectors are remote-only.)

Codex CLI:

codex mcp add visigrid --command vgrid --args mcp

Hosts configured with JSON:

{ "mcpServers": { "visigrid": { "command": "vgrid", "args": ["mcp"] } } }

Hosts configured with TOML (e.g. ~/.codex/config.toml):

[mcp_servers.visigrid]
command = "vgrid"
args = ["mcp"]

Target a specific window with vgrid mcp --session <id> (IDs from vgrid sessions), or let agents pass a session argument per call. With a single window open, no selection is needed.

Troubleshooting

Symptom	Fix
“No running VisiGrid sessions”	Start VisiGrid — the session server starts with the app (v0.14+)
“N sessions running”	Pass --session <id>, or let the agent call list_sessions and choose
“pairing rejected: timed out”	The approval dialog waited 2 minutes — approve it and ask the agent to retry
“auth_failed” after revoking	Expected: the next tool call triggers a fresh pairing dialog

How it compares

Excel MCP servers exist, but they’re third-party: file-manipulation servers that edit .xlsx blobs headlessly, or COM-automation bridges that are Windows-only. VisiGrid’s MCP server is built into the CLI that ships with the app, works on Linux, macOS, and Windows, and is wired into the app’s own consent, undo, and concurrency machinery — because an agent editing your spreadsheet should be a feature, not a workaround.