# Grist — how to use (mcp.ai)

Connect your Grist account and use 30 tools for productivity straight from your AI agent. Connect with your own API key. Grist is a relational spreadsheet platform that combines the flexibility of a spreadsheet with the robustness of a database, allowing users to create custom applications tailored to their data needs.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_grist?ms=1787291340000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `grist_add_records`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/grist`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/grist/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/grist/add/records` — Add one or more records to a Grist table. First use GRIST_LIST_WORKSPACES to get docId, GRIST_LIST_TABLES to get tableId, and GRIST_LIST_COLUMNS to get column IDs for the fields mapping.
  - body: { docId: string, noparse?: boolean, records: object[], tableId: string }
- `POST https://api.mcp.ai/api/grist/create/document` — Creates a new Grist document in a specified workspace. Use this tool when you need to add a new spreadsheet document to a workspace. Requires a valid workspace ID (obtainable via GRIST_LIST_WORKSPACES
  - body: { name: string, isPinned?: boolean, workspaceId: integer }
- `POST https://api.mcp.ai/api/grist/create/scim/user` — Tool to create a new SCIM user. Use when provisioning new user accounts via SCIM. Run after gathering all required user details.
  - body: { name: object, emails: object[], locale?: string, photos?: object[], schemas?: string[], userName: string, displayName?: string, preferredLanguage?: string }
- `POST https://api.mcp.ai/api/grist/create/table` — Tool to create tables in a document. Use after confirming the document ID. Creates one or more tables with specified columns in the given document.
  - body: { docId: string, tables: object[] }
- `POST https://api.mcp.ai/api/grist/create/webhook` — Tool to create a new webhook for a specified document. Use when you need to register webhook endpoints for document events in Grist. Run after confirming document ID.
  - body: { docId: string, webhooks: object[] }
- `POST https://api.mcp.ai/api/grist/delete/attachment` — Remove unused attachments from a Grist document to free up storage space. IMPORTANT: This action removes ALL attachments that are not currently referenced by any cell in the document. It does NOT dele
  - body: { doc_id: string, expired_only?: boolean }
- `POST https://api.mcp.ai/api/grist/delete/column` — Tool to delete a column from a Grist document table. Use after confirming document, table, and column IDs.
  - body: { col_id: string, doc_id: string, table_id: string }
- `POST https://api.mcp.ai/api/grist/delete/records` — Tool to delete records from a specified Grist table. Use when you need to remove specific rows by their IDs. Use after confirming the row IDs exist.
  - body: { doc_id: string, row_ids: integer[], table_id: string }
- `POST https://api.mcp.ai/api/grist/delete/scim/user` — Delete a user from the Grist organization by their numeric user ID. Use GRIST_GET_USERS first to find the user's ID. Falls back to org access API if SCIM is not enabled. Note: Cannot delete your own a
  - body: { user_id: integer }
- `POST https://api.mcp.ai/api/grist/delete/webhook` — Permanently removes a webhook from a Grist document. Use this tool when you need to stop receiving notifications for document changes. First use GRIST_LIST_WEBHOOKS to find the webhook_id you want to 
  - body: { doc_id: string, webhook_id: string }
- `POST https://api.mcp.ai/api/grist/download/all/attachments/archive` — Download all attachments from a Grist document as a single archive file (.zip or .tar). Use this to bulk-download attachments. Ensure the document has attachments before calling (check with GRIST_LIST
  - body: { doc_id: string, format?: string }
- `POST https://api.mcp.ai/api/grist/download/attachment` — Download a file attachment from a Grist document. Returns the file content as a downloadable file. Use GRIST_LIST_ATTACHMENTS first to get valid attachment IDs.
  - body: { docId: string, attachmentId: integer }
- `POST https://api.mcp.ai/api/grist/fetch/document/metadata` — Tool to fetch metadata for a specified Grist document. Use after obtaining the document ID.
  - body: { doc_id: string }
- `POST https://api.mcp.ai/api/grist/fetch/table/metadata` — Tool to retrieve metadata for a specified table in a Grist document. Use when you need to inspect table schema details before data operations.
  - body: { doc_id: string, header?: string, table_id: string }
- `POST https://api.mcp.ai/api/grist/get/org/access` — Retrieves the list of users who have access to a Grist organization along with their access roles (owners, editors, viewers). Use this to find user IDs, emails, or check access permissions within an o
  - body: { org_id?: integer|string }
- `POST https://api.mcp.ai/api/grist/get/users` — Tool to retrieve a list of users via SCIM v2. Use when you need to page through and filter enterprise users in Grist.
  - body: { count?: integer, filter?: string, startIndex?: integer }
- `POST https://api.mcp.ai/api/grist/list/attachments` — Tool to list all attachments in a Grist document. Use after confirming the document ID to retrieve attachment metadata.
  - body: { sort?: string, docId: string, limit?: integer, X-Sort?: string, filter?: string, X-Limit?: integer }
- `POST https://api.mcp.ai/api/grist/list/columns` — Tool to list all columns in a specified Grist table. Use after selecting the document and table to inspect column metadata.
  - body: { doc_id: string, hidden?: boolean, table_id: string }
- `POST https://api.mcp.ai/api/grist/list/organizations` — Tool to list all organizations accessible to the authenticated user. Use when you need to select a Grist organization for subsequent operations.
- `POST https://api.mcp.ai/api/grist/list/records` — Tool to retrieve records from a specified table within a Grist document. Use when you need to fetch rows by applying optional filters, sorting, limits, or hidden columns. Example: list records where p
  - body: { sort?: string, docId: string, limit?: integer, filter?: string, hidden?: boolean, tableId: string }
- `POST https://api.mcp.ai/api/grist/list/tables` — Tool to list all tables within a specified document. Use after obtaining the document ID to retrieve its tables.
  - body: { docId: string }
- `POST https://api.mcp.ai/api/grist/list/webhooks` — List all webhooks configured for a Grist document. Returns webhook configuration details (URL, event types, table binding) and delivery status information. Use this to inspect, audit, or manage webhoo
  - body: { doc_id: string }
- `POST https://api.mcp.ai/api/grist/list/workspaces` — Tool to list all workspaces and documents accessible to the authenticated user on the current site. Use when you need to select a workspace or document for subsequent operations.
- `POST https://api.mcp.ai/api/grist/run/sql/query` — Tool to execute a read-only SQL SELECT query on a Grist document. Use after confirming the document ID and preparing a valid SQL SELECT statement.
  - body: { sql: string, args?: integer|string[], docId: string, timeout?: integer }
- `POST https://api.mcp.ai/api/grist/update/column/metadata` — Updates metadata (label, type, description, formula, etc.) for one or more columns in a Grist table. Use List Columns first to get valid column IDs. Warning: changing 'label' may rename the column ID 
  - body: { docId: string, columns: object[], tableId: string }
- `POST https://api.mcp.ai/api/grist/update/document/metadata` — Tool to update metadata for a specified Grist document. Use when you need to rename or pin/unpin a document after obtaining its ID.
  - body: { name?: string, doc_id: string, isPinned?: boolean }
- `POST https://api.mcp.ai/api/grist/update/records` — Update existing records in a Grist table by their row IDs. Use this tool to modify field values for one or more records in a specified document and table. First use GRIST_LIST_RECORDS to obtain the re
  - body: { docId: string, noparse?: boolean, records: object[], tableId: string }
- `POST https://api.mcp.ai/api/grist/update/table/metadata` — Update metadata properties for a table in a Grist document. Currently the main updatable property is 'onDemand' which controls lazy loading of table data. Use List Tables to find valid table IDs first
  - body: { docId: string, fields: object, tableId: string }
- `POST https://api.mcp.ai/api/grist/update/webhook` — Update an existing webhook configuration for a Grist document. Use to modify webhook settings such as URL, event types, enabled status, or target table. Requires valid document ID (from GRIST_LIST_WOR
  - body: { url?: string, memo?: string, name?: string, doc_id: string, enabled?: boolean, tableId?: string, eventTypes?: string[], webhook_id: string, isReadyColumn?: string }
- `POST https://api.mcp.ai/api/grist/upload/attachment` — Upload one or more file attachments to a Grist document. Returns attachment IDs that can be used to link files to records in Attachments-type columns. First use GRIST_LIST_WORKSPACES to get a valid do
  - body: { docId: string, files: object[] }

## Example prompts
- "What can I do in Grist?"
- "Show me a summary of my Grist account"

## More
- Page: https://mcp.ai/grist
- Agent spec (llms.txt): https://mcp.ai/grist/llms.txt
- Postman collection: https://mcp.ai/grist/postman.json