# 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**.

```bash
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:

```bash
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:

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

Hosts configured with JSON:

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

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

```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.