# Claude Connector

A remote MCP server that lets Claude read and edit the spreadsheets stored in your
VisiGrid account. Nothing runs on your machine: the agent works against the same
documents the web app uses, so it keeps working when your laptop is closed.

```
https://mcp.visigrid.app/mcp
```

## This is not `vgrid mcp`

VisiGrid has two MCP servers and they solve different problems. Picking the wrong one
is the most common confusion, so:

| | **Claude Connector** (this page) | **[`vgrid mcp`](https://docs.visigrid.app/cli/mcp/)** |
|---|---|---|
| Operates on | Sheets in your VisiGrid account | A live VisiGrid window on your machine |
| Transport | Remote, over HTTPS | Local, over stdio |
| Requires the app running | No | Yes |
| Setup | Add a connector URL in Claude | `claude mcp add visigrid -- vgrid mcp` |
| Auth | OAuth sign-in | One-click pairing dialog |
| Edits appear | In the web app, and in your undo history when next opened | On screen immediately, in the app's undo history |

Use the connector when you want an agent working on cloud sheets. Use `vgrid mcp` when
you want an agent driving the spreadsheet in front of you.

Tool names match between the two, so a prompt written for one generally works on the
other.

## Setup

1. In Claude, add a custom connector with the URL `https://mcp.visigrid.app/mcp`.
2. Claude will send you to VisiGrid to sign in.
3. Approve the request. The consent screen names the app asking and what it will be
   allowed to do.

There is no API key to create or paste — the connector registers itself and obtains its
own credential through OAuth. A free VisiGrid account is enough.

## Tools

| Tool | What it does |
|---|---|
| `list_sheets` | The spreadsheets this connection can reach. Call first to learn `sheet_id` values. |
| `get_workbook` | A spreadsheet's tabs: names, cell counts, used range, frozen panes, and whether charts or conditional formatting are present. |
| `read_range` | Cells in an A1 rectangle, with values, formulas, formatting, and a revision. |
| `write_cells` | Set values and formulas. |
| `set_format` | Apply formatting without touching cell contents. |
| `add_tab` | Add an empty tab; returns its index. |
| `rename_tab` | Rename a tab. Refuses when formulas reference it — see below. |
| `create_spreadsheet` | A new, empty spreadsheet. |
| `import_spreadsheet` | A new spreadsheet from a Google Sheets link or an `.xlsx` file. |

`list_sheets`, `get_workbook`, and `read_range` are read-only. The rest write.

### Formulas are computed, not guessed

When an agent writes `=SUM(B1:B12)`, the formula is evaluated by VisiGrid's engine —
the same Rust engine the desktop app and CLI use — before the document is saved. The
result is a real number you can read back immediately, rather than text that sits inert
until someone opens the file in a spreadsheet program.

This also means the agent can check its own work: write a formula, read it back, see
whether the number makes sense.

### Imports keep their formatting

`import_spreadsheet` runs the same importer as the desktop app, so borders, merged
cells, number formats, frozen panes, conditional formatting, and data validation
survive. A Google Sheets link must be shared as *anyone with the link can view*.

## Concurrent edits

Every `read_range` returns a `revision`. Passing it back as `expected_revision` on a
write means the write is refused if the document changed in the meantime, rather than
overwriting whatever happened while the agent was thinking.

If a write is refused this way, re-read the range and decide again — the sheet has moved
on. Omit `expected_revision` only when you intend to overwrite regardless.

## What it will not do

These are deliberate, and worth knowing before you ask for something it declines.

**Nothing deletes a spreadsheet.** There is no delete tool. Removing a sheet is done by
a person, in the app.

**Renaming a tab is refused when formulas point at it.** VisiGrid re-binds sheet names
on every evaluation and does not rewrite references on rename, so `=Sheet2!A1` becomes
`#REF!` when `Sheet2` is renamed — unlike Excel and Google Sheets, which rewrite them.
Rather than break a workbook quietly, `rename_tab` counts the formulas that would break
and refuses. Update them first, or pass `force: true` to rename anyway. Renaming back
restores them. Renaming a tab nothing references always succeeds.

**No inserting or deleting rows and columns.** Doing this correctly means shifting
formula references, merged regions, chart data ranges, conditional-format ranges, and
validation ranges together. That logic lives in the engine and is not yet reachable from
the server, so rather than a version that gets references subtly wrong, the tools are
absent. They will appear when it is.

## Access and revocation

The connector reaches only spreadsheets owned by the account that authorised it. There
is no cross-account access.

To revoke it, delete its key under **Settings → API keys** in the VisiGrid web app,
where it appears named after the app that connected. Access stops immediately.

## Data

`read_range` returns only populated cells, so empty space is never transmitted. What the
agent sees is the cells it asked for — values, formulas, and formatting.

The MCP server itself is a stateless Cloudflare Worker. It stores no spreadsheet data
and no conversation content; it forwards authenticated requests and returns the
responses. Documents live in your VisiGrid account exactly as they do for the web app.