A Grist MCP for agents that read, write and query the document
Connect one Grist API key and the site host it belongs to, and 35 nodes land on the canvas: list sites and workspaces, create documents and tables, discover a user-defined schema before writing to it, read and upsert rows, and run read-only SQL for the joins and aggregates the record filter cannot express. An AI assistant can look up a row, add what it learned, and report back without anyone opening the Grist UI.
What the Grist MCP connector does
The Grist connector for Mattering Automations is 35 nodes on Grist's REST API: the whole site to workspace to document to table to column and record spine, access and sharing at all three levels, a snapshot lister, and a read-only SQL node. It is a deliberately scoped core rather than a sweep of everything Grist publishes. Grist documents 143 operations across its main API and its SCIM specification, and this build covers the ones a workflow actually moves data through. Attachments, webhook management, file downloads, document engine operations, template and widget catalogues, API key management and the whole SCIM surface are not included, so nothing on this page should be read as full API coverage.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. An agent can discover a table's real columns with Grist: List Columns, read matching rows with Grist: List Records, write results back with Grist: Add Or Update Records, and confirm the write, all without a Grist tab being open.
One structural choice shapes every Grist workflow here, and it is worth stating rather than discovering. Records are built on Grist's row-oriented /records API, not the parallel column-oriented /data one. That means a row comes back as one self-contained object, {"id": 1, "fields": {...}}, which is what a loop node, a template reference and a database row all want. The column-oriented shape returns parallel arrays per column, so row two is index one of every array, and a template pointing at a position silently addresses a different row the moment a filter or sort changes. The row shape also carries per-record formula errors, so a workflow can tell a broken formula from an empty cell, and it is the only one of the two with an upsert, which is the idempotent write a retried automation needs.
The safety modeling is stated rather than implied. Of the 35 nodes, 14 read and 21 act, and five are flagged destructive: Grist: Remove Document, Grist: Remove Workspace, Grist: Add Or Update Columns, Grist: Delete Column and Grist: Delete Records. What recovery actually looks like differs sharply between them, and the difference is the most important thing on this page. Removing a document or a workspace moves it to trash, which Grist keeps for 30 days and then purges automatically, taking the backups with it, so the automatic purge is itself a point of no return. Setting permanent to true skips trash entirely. Deleted rows and deleted columns have no per-item undo at all: there is no row trash, no column trash and no undo endpoint. Grist does write automatic document snapshots, and Grist: List Snapshots reports which restore points exist, but restoring one is a whole-document rollback performed in the Grist UI that discards every other change made since that snapshot. Snapshot retention is by plan on Grist's pricing page: 30 days on Free, 3 years on Pro and 5 years on Business.
One connection, three surfaces
- Visual automations. Drag Grist nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every Grist node, ready to drop on the canvas
35 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 14
Grist: Get Document
Describe a document's metadata: name, pinned state, this key's access level, and the workspace and site it lives in. Contents are read with Grist: List Records or Grist: Run SQL Query.
Grist: Get Site
Describe one organisation (team site or personal area): its name, subdomain, owner, this key's access level, and timestamps.
Grist: Get Site Usage
Usage summary across every non-deleted document in the site: how many documents are approaching, in a grace period for, or past their data limit, plus total attachment bytes. Grist documents this as accessible to site OWNERS only, so a key with editor access gets a 403 here while every other read still works. Useful as a scheduled quota alarm.
Grist: Get Workspace
Describe one workspace: its name, this key's access level, the documents it contains, and the organisation it belongs to.
Grist: List Columns
List a table's columns with their ids, labels, types, formulas and widget options. Grist schemas are defined by the user, so this is how an automation discovers what it is allowed to write before it writes it.
Grist: List Document Access
List everyone with access to a document, showing their direct role, the role inherited from the workspace, and maxInheritedRole.
Grist: List Records
Read rows from a table, one self-contained object per record: {"id": 1, "fields": {...}}. Supports exact value filtering, multi-column sorting and a row limit. There is no cursor and no offset - Grist does not paginate this endpoint - so for large tables either raise the limit or use Grist: Run SQL Query with LIMIT and OFFSET. Records with formula errors carry an extra 'errors' object naming the failing columns. Grist rejects requests with HTTP 429 once ten authorized requests are in flight for one document (all plans). Free plans are metered at 3,000 API calls per month shared across every document on the site, and may additionally be rate limited to 5 requests per second per document; Pro and Business raise the allowance to 40,000 and 60,000 calls per document per day. Grist counts MCP tool calls against the same allowance as REST calls.
Grist: List Site Access
List everyone with access to the site, with their id, name, email and role (owners / editors / viewers).
Grist: List Sites
List every organisation the API key can reach: each team site plus the personal area. This is where the site ids and subdomains used by the org-scoped nodes come from, and it is the call Grist's own documentation uses to check an API key works. The response is a bare array, so downstream references read data[].id and data[].name.
Grist: List Snapshots
List the automatic backups Grist has kept of a document, most recent first, each with a snapshotId, a lastModified timestamp and a docId that opens that version. This is the recovery surface behind every destructive node in this connector: it tells an automation which restore points exist. Restoring one is a whole-document rollback and is done in the Grist UI, not through this API.
Grist: List Tables
List the tables in a document. Table ids are what every record and column node needs. Set expand to 'column' to get each table's full column metadata in the same call, which is the cheapest way to learn a user-defined schema before writing to it. Documents are limited to 500 tables.
Grist: List Workspace Access
List everyone with access to a workspace, showing both their direct role and the role they inherit from the site, plus maxInheritedRole - the ceiling on what site membership alone grants here.
Grist: List Workspaces
List every workspace in a site WITH the documents inside each one, in a single call. This is the tree the rest of the connector hangs off: workspace ids come from data[].id and document ids from data[].docs[].id. The response is a bare array. Pass 'current' as the site to mean the site this connection's host addresses.
Grist: Run SQL Query
Run a read-only SQL SELECT against a document. Every Grist document is a SQLite database, and this runs the query against it directly with defensive measures: a single SELECT statement, no trailing semicolon, WITH clauses allowed, and anything that would modify the database rejected. This is the escape hatch for everything Grist: List Records cannot express - joins across tables, aggregates, ranges, LIKE matching, and LIMIT/OFFSET paging. Use args for parameters rather than string concatenation. The POST form is shipped rather than the GET form because only POST accepts parameters and a timeout.
Action nodes 21
Grist: Add Columns
Add columns to a table, including formula columns and references to other tables. Additive: existing columns are untouched.
Grist: Add Or Update Columns
Upsert columns: each entry updates the column with that id, or creates it if it does not exist. Marked destructive for one reason - replaceall. With replaceall true, every column NOT listed in the body is REMOVED from the table, along with its data, so the node's blast radius is whatever the table happens to contain at that moment. It defaults to false, which makes the node a plain upsert. There is no per-row undo. The only recovery is a whole-document rollback to an automatic snapshot, done in the Grist UI, which also discards every other change made since that snapshot (snapshots are retained 30 days on Free, 3 years on Pro, 5 years on Business).
Grist: Add Or Update Records
Upsert rows: each entry names a 'require' object that identifies an existing row by column values, and a 'fields' object of values to write. A match is updated, no match creates a row combining both objects. This is the idempotent write - the right node for a workflow that may retry. Columns not mentioned are left alone, so unlike some vendors' PUT this does not blank omitted fields. One hazard: allow_empty_require lets an empty 'require' match and update EVERY row in the table, which is off by default.
Grist: Add Records
Add rows to a table. The response returns the new row ids so a later step can update or delete exactly what this step created. Not idempotent: running it twice adds the rows twice, so a retried workflow should either dedupe upstream or use Grist: Add Or Update Records instead. Request bodies are capped at 1MB, so large batches must be split.
Grist: Add Tables
Add one or more tables to a document, each with its columns. Additive: existing tables are untouched. Note this connector ships no delete-table node, so cleanup of a table created here is done in the Grist UI.
Grist: Create Document
Create an empty document in a workspace. The response body is the new document id as a bare string, so downstream steps reference data directly. Add structure afterwards with Grist: Add Tables, then rows with Grist: Add Records.
Grist: Create Workspace
Create an empty workspace in a site. The response body is the new workspace id as a bare integer, so downstream steps reference data directly rather than a field of it.
Grist: Delete Column
Delete one column from a table, and with it every value that column held. There is no per-column undo and no column trash. There is no per-row undo. The only recovery is a whole-document rollback to an automatic snapshot, done in the Grist UI, which also discards every other change made since that snapshot (snapshots are retained 30 days on Free, 3 years on Pro, 5 years on Business). Formulas in other columns that referenced this one will start erroring.
Grist: Delete Records
Delete rows from a table by row id. There is no row-level trash and no undo endpoint. There is no per-row undo. The only recovery is a whole-document rollback to an automatic snapshot, done in the Grist UI, which also discards every other change made since that snapshot (snapshots are retained 30 days on Free, 3 years on Pro, 5 years on Business). The request body is a bare JSON array of row ids, which is unusual for this API - every other write wraps its payload in an object.
Grist: Modify Document Access
Share a document with people by email, change their role, or remove them, and optionally lower the ceiling on what workspace membership inherits here. This is the node that turns a generated document into a shared one.
Grist: Modify Site Access
Grant, change or remove site-level access by email address. Reversible by sending the previous roles back, but note the one irreversible-in-practice case: setting the API key owner's own entry to null removes this connection's access, after which only another owner can restore it.
Grist: Modify Workspace Access
Grant, change or remove workspace access by email, and optionally lower the ceiling on what site membership inherits into this workspace. Reversible by sending the previous values back.
Grist: Move Document
Move a document into another workspace. Reversible by moving it back. Returns an empty body on success.
Grist: Remove Document
Move a document to trash. Trashed items can be restored for 30 days, after which the trash purges automatically and the backups go with it. Restore it with Grist: Restore Document From Trash, which brings the snapshot history back with it. Setting permanent to true skips trash and deletes the document and every backup of it forever. This node is the connector's only document delete: Grist's separate hard-delete endpoint does exactly what permanent=true does here.
Grist: Remove Workspace
Move a workspace, and everything in it, to trash. Trashed items can be restored for 30 days, after which the trash purges automatically and the backups go with it. Setting permanent to true skips trash and deletes the workspace and its documents forever, snapshot history included. This node is the connector's only workspace delete: Grist's separate hard-delete endpoint does exactly what permanent=true does here.
Grist: Rename Workspace
Rename a workspace. Name is the only property Grist documents as modifiable here; documents are moved with Grist: Move Document rather than by editing the workspace.
Grist: Restore Document From Trash
Restore a document that was moved to trash, together with its snapshot history. Only works while the document is still in trash - after 30 days it is purged and this returns an error.
Grist: Update Columns
Update existing columns: change a label, type, formula or widget options, or rename a column by setting colId. Partial - properties you do not send are left alone. Changing a column's type can convert its stored values, so the previous values are only recoverable by a whole-document snapshot rollback.
Grist: Update Document
Update a document's metadata - its name and whether it is pinned. This never touches the document's contents; rows and columns are changed with the record and column nodes.
Grist: Update Records
Update existing rows by id. Partial: only the columns you send change, and columns you omit keep their values, so this cannot silently blank a field. Idempotent - sending the same update twice leaves the same result.
Grist: Update Tables
Update table metadata: rename a table by setting a new tableId, or switch on-demand loading on and off. Renaming changes the id every other node addresses the table by, so re-point any saved configuration afterwards.
Connecting Grist takes one credential
Grist authenticates with an API key sent as an Authorization Bearer header, created on the Developer page of your Grist account settings. The credential carries a second, non-secret field: the site host. Grist runs one deployment per team subdomain, a personal site at docs.getgrist.com, and any number of self-hosted grist-core or Grist Enterprise installs, all on the same https://host/api shape with unversioned paths, and a key minted on one deployment is meaningless on another. So the host is part of the credential rather than a per-node field, and one connection addresses one Grist site. A user with two team sites creates two connections. Know the blast radius before you create the key: Grist states that an API key is owned by a single user and has the same permissions as that user, and there are no scopes on an API key. Grist also ships an OAuth flow with real scopes for connected apps, which this connector does not use yet. Plan gating to check first: node access is not gated, but Grist's quotas are, and two matter here. The free tier caps rows per document at 5,000, which a sync workflow reaches quickly, and free team sites are capped at 10 members and become read-only until they are back under the limit. Snapshot retention is 30 days on Free against 3 years on Pro and 5 years on Business, which changes what the recovery advice above is worth on your plan. Grist meters API calls on the free tier at 3,000 calls per month, shared across every document on the site, and free plans may additionally be rate limited to 5 requests per second per document. Pro and Business raise the allowance to 40,000 and 60,000 calls per document per day. Grist counts MCP tool calls against the same allowance as REST calls.
Open your Grist account settings and go to the Developer page. Create an API key and copy it. You can revoke and recreate it there at any time.
Note the site host this key belongs to: docs.getgrist.com for a personal site, your team subdomain for a team site, or your own domain for a self-hosted Grist. Hostname only, over https.
In Mattering Automations, open Connectors, click Add Connector, choose Grist, and create a credential with the key and the host.
Click Test Connection. Mattering calls the site list endpoint, which is the same call Grist's own API guide uses to check a key, and the result names the sites the key can see. That is the check that catches a valid key pointed at the wrong deployment, which would otherwise show up much later as nodes returning empty lists.
All 35 Grist nodes appear in the canvas palette. Run Grist: List Sites, then Grist: List Workspaces, which returns each workspace with the documents inside it in a single call. Those are the ids every other node picks from.
Common uses for the Grist MCP
A sync into Grist that survives being retried
Grist: Add Or Update Records is the idempotent write. Each entry names a require object that identifies an existing row by column values and a fields object of values to write: a match updates, no match creates a row combining both. Columns you do not mention are left alone, so unlike some vendors' replace-style writes this cannot blank a field you forgot to send. That is what makes a nightly sync safe to rerun after a partial failure. One hazard is on the node and worth repeating: allow_empty_require lets an empty require match and update every row in the table, and it is off by default for that reason. Grist: Add Records is the non-idempotent alternative, and it returns the new row ids so a later step can update exactly what it created.
Let an agent learn the schema before it writes
Grist schemas are defined by whoever built the document, so an agent that guesses column names writes nothing useful. Grist: List Tables with expand set to column returns every table with its full column metadata in one call, and Grist: List Columns does the same for a single table, including types, labels and formulas. The pattern that works is discovery first: read the columns, map your payload onto the real ids, then write. It also prevents the quieter failure, where a column type postfix is part of the type string, so a reference column is Ref:Orders rather than a bare Ref.
SQL for everything the record filter cannot express
Grist: Run SQL Query runs a read-only SELECT straight against the document, which is a SQLite database underneath. This is the escape hatch for joins across tables, aggregates, ranges, LIKE matching and paging, none of which the record filter can do: the filter is exact membership matching only, with no operators and no text search. It is also the answer to pagination, because Grist does not paginate. Record reads take a limit with no cursor and no offset, so a large table is walked with LIMIT and OFFSET in SQL rather than by following a cursor field that does not exist. Use args for parameters rather than string concatenation. The node is genuinely read-only: a single SELECT, WITH clauses allowed, and anything that would modify the database is rejected.
Provision a document and share it in one run
Grist: Create Workspace, Grist: Create Document, Grist: Add Tables and Grist: Add Columns build the structure, Grist: Add Records fills it, and Grist: Modify Document Access shares it with people by email and sets the ceiling on what workspace membership inherits. That is a client onboarding, a project kickoff or a per-customer report as one automation rather than a checklist. Two response shapes to know while wiring it: creating a workspace returns the new id as a bare integer and creating a document returns the new id as a bare string, so downstream steps reference the value directly rather than a field of it.
Access reviews and a quota alarm on a schedule
Grist: List Site Access, Grist: List Workspace Access and Grist: List Document Access each return who has access, their direct role and the role they inherit, plus the maxInheritedRole ceiling. A scheduled sweep can write all three levels into a Mattering database and open a task when someone appears where they should not be. Grist: Get Site Usage is the quota alarm: it reports how many documents are approaching, in a grace period for, or past their data limit, plus total attachment bytes. It is owner-only by Grist's own documentation, so a key with editor access gets a 403 there while every other read still works, which is the connector reporting a permission fact rather than a broken node.
Know your restore points before anything irreversible runs
Grist: List Snapshots returns the automatic backups Grist has kept of a document, newest first, each with a snapshot id and a timestamp. Put it in front of a bulk rewrite and the run records which restore points existed at that moment, which is the difference between a recoverable mistake and an archaeology project. Be clear about what it buys you, because the honest version is narrower than it sounds: restoring a snapshot is done in the Grist UI, not through this API, and it rolls the whole document back, discarding every other change made since. For a document or a workspace, Grist: Remove Document and Grist: Remove Workspace go to trash for 30 days and Grist: Restore Document From Trash brings a document back with its snapshot history intact.
Example: A nightly sync into Grist that can be rerun safely
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a nightly schedule fires, and a database or HTTP node pulls the records that changed since the last run.
Grist: List Columns reads the target table's real column ids and types, so the mapping step writes against the schema as it is today rather than as it was when the workflow was built.
Grist: List Snapshots records which restore points exist before anything writes, and the result is stored with the run.
Grist: Add Or Update Records upserts the changed rows in batches, with require naming the business key. Request bodies are capped at 1MB, so batches are split to fit rather than sent whole. Because the write is an upsert, a rerun after a partial failure converges rather than duplicating.
Grist: Run SQL Query counts the rows that now match the expected state, and a condition compares it against the number the source said it sent. A match continues, a mismatch stops the run and opens a task.
Grist: List Records reads back a sample for the run record, and the totals land in a Mattering database next to last night's.
Grist MCP questions, answered
What Grist operations are supported?
35 nodes: 14 read and 21 act. Sites (list, get, usage, list access, modify access), workspaces (list with their documents, get, create, rename, remove, list access, modify access), documents (get, create, update, move, remove, restore from trash, list access, modify access, list snapshots), tables (list, add, update), columns (list, add, update, add or update, delete), records (list, add, update, add or update, delete) and a read-only SQL query node. Deliberately not included, because being specific matters more than a bigger number: attachments, webhook management, file downloads in sqlite, xlsx or csv form, document engine operations such as applying raw user actions, change proposals and forms, the template and widget catalogues, session and API key management, user administration and the whole SCIM v2 surface. Grist documents 143 operations in total, so this is a scoped core rather than complete coverage.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively. The difference from running a tool locally in one person's client is where the work lives: these nodes also run on a schedule or a trigger with nobody present, chain with every other connector in the same workflow, hold the Grist key in a shared workspace credential store rather than in an individual's config, and carry destructive flags you can gate on.
Why does the credential ask for a host as well as a key?
Because a Grist API key belongs to one deployment. Grist runs a personal site at docs.getgrist.com, a subdomain per team site, and any number of self-hosted installs, all on the same https://host/api shape, and a key minted on one is not valid on another. Putting the host on the credential rather than on every node means one connection addresses one Grist site and no node has to name an address. A pasted document URL is trimmed back to its origin, a bare hostname gets https added, and a plain http host is refused outright, because a Grist API key carries the whole account's permissions and must not travel unencrypted. If you work across two team sites, create two connections.
Does Grist publish its own MCP server?
Yes. Grist hosts one at docs.getgrist.com/api/mcp, and a self-hosted Grist can enable the same thing on its own host. Grist documents it as available to all users at no extra cost, on hosted Grist and on the full edition of self-hosted Grist, across all plans. If what you want is an assistant working with a Grist document while you sit in front of it, use the vendor's server. This connector is the operations side: the same 35 nodes run as scheduled canvas steps with nobody present, chain with every other connector in one workflow, and hold the credential once in a shared workspace store rather than in each person's client config. One thing worth knowing either way: Grist counts MCP tool calls against the same monthly API allowance as REST calls, so the free tier's 3,000 calls a month are shared between them.
Does it work with self-hosted Grist?
Yes. Grist is open source, grist-core is published under the Apache 2.0 licence, and self-hosting is documented, so the same 35 nodes work against your own install: put your domain in the credential's host field and mint the API key on that instance's Developer page. Grist Enterprise is a separate paid product, so features specific to it are not included by self-hosting alone. A self-hosted instance is also the cleanest way to work without the hosted tiers' API metering.
Can an AI agent delete rows I cannot get back?
Read this one carefully, because the answer differs by node. Grist: Delete Records and Grist: Delete Column have no per-item undo: there is no row trash, no column trash and no undo endpoint. The data does survive in an automatic document snapshot, and Grist: List Snapshots will show you which ones exist, but the only way to get it back is a whole-document rollback performed in the Grist UI, which discards every other change made since that snapshot. Grist: Remove Document and Grist: Remove Workspace are gentler: they go to trash, restorable for 30 days, after which the trash purges automatically and takes the backups with it, and setting permanent to true skips trash entirely. Grist: Add Or Update Columns is flagged for one setting, replaceall, which removes every column not listed in the body along with its data and is off by default. All five are flagged destructive so you can gate them behind a condition or an approval step, and the comfortable surface to hand an agent is the read nodes plus the upsert.
How do I page through a table with a lot of rows?
With SQL, because Grist does not paginate. No endpoint in this connector returns a cursor or accepts an offset: record reads take a limit and everything else returns the complete collection in one response. So for a large table either raise the limit, narrow the read with the filter and sort parameters, or use Grist: Run SQL Query with LIMIT and OFFSET, which is the only paging mechanism available. This is a property of Grist's API rather than a gap in the node set, and it is stated here so nobody goes looking for the cursor field.
What rate limits should I design around?
Two limits apply on every plan and will shape a workflow. Grist rejects requests with HTTP 429 once ten authorized requests are in flight for one document, so a fan-out with more than ten parallel branches against the same document sees 429s that have nothing to do with quota, and the connector adds no retry of its own: put the backoff in the automation. Request bodies are capped at 1MB, which is the practical batch size for record writes. Beyond that, grist meters API calls on the free tier at 3,000 calls per month, shared across every document on the site, and free plans may additionally be rate limited to 5 requests per second per document. Pro and Business raise the allowance to 40,000 and 60,000 calls per document per day. Grist counts MCP tool calls against the same allowance as REST calls. Check the plan page for your own account before designing a high-frequency sync.
Does it write with the /records API or the /data API?
Records, in every case. Grist documents each record operation twice, once row-oriented under /records and once column-oriented under /data, and this connector builds on the row-oriented one for three reasons. A workflow iterates over rows, and the column shape returns parallel arrays that cannot be iterated without a transpose. Template references into the column shape are positional, so a filter or sort change silently repoints them at a different row. And the row shape carries per-record formula errors, naming the columns whose formula raised, where the column shape flattens them into bare nulls so a workflow cannot tell empty from broken. The row API is also the only one of the two with an upsert. Shipping both would put two nodes doing the same write into one palette, and the cost of picking wrong is writing to the wrong row.
What happens if the key's owner loses access to something?
The key inherits its owner's permissions exactly, with no scopes, so a node fails wherever that person would. Grist: Get Site Usage is the clearest case: Grist documents it as accessible to site owners only, so an editor's key gets a 403 there while every other read works normally. There is one sharp edge worth knowing on the access nodes: Grist: Modify Site Access can set the key owner's own entry to null, which removes this connection's access, after which only another owner can restore it. That is why the access nodes are worth keeping out of an agent's reach even though they are reversible in principle.
Put Grist to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. Grist is a product of its respective owner; Mattering is an independent platform.