MCP server

What the server exposes

35MCP tools

8prompts

18resources

v5.14streamable-http

These numbers are read back from the source on every build of this page, so they cannot drift from what the server actually exposes.

Name: io.github.nic01asFr/gristcoder
Transport: streamable-http — 2025-03-26, on /mcp
Image: ghcr.io/nic01asfr/grist-coder

Claude Code

claude mcp add grist-coder --transport http http://localhost:8742/mcp \
  --header "Authorization: Bearer <clé Grist>" \
  --header "X-Grist-Site: https://<instance>"

Claude Desktop

{
  "mcpServers": {
    "grist-coder": {
      "type": "http",
      "url": "http://localhost:8742/mcp",
      "headers": {
        "Authorization": "Bearer <clé Grist>",
        "X-Grist-Site": "https://<instance>"
      }
    }
  }
}

The promise

What it changes

A Grist document already holds the data, the permissions and the sharing. What it lacks to be an application — screens, logic, triggers — is built here through conversation, and stays stored inside the document.

The application lives in the documentHTML/React interfaces are stored in a table of the document and rendered by the widget. There is no second hosting to maintain: the application travels with the file, is shared like it, is backed up like it.
Publishing cuts the cordA published artefact is frozen into the document with its npm imports bundled. It outlives the server that wrote it — publishing in fact refuses any artefact that would still point back at it.
Tooling follows the workNot every tool is exposed at once. Six phases reveal what is relevant when it becomes relevant, which keeps code from being written before the schema has been read.
End users never see the AIThey open an application and use it. The model, the code and the back-and-forth stay on the builder's side.
Your server, your secretsA Helm chart deploys one server per user on SSPCloud Onyxia. Everyone keeps their own key, and nobody holds anyone else's documents.

In pictures

What it looks like

The widget on open: the document's artefacts as clickable tiles.

A map artefact and its code side by side: the preview refreshes as you type.

Features

What you can do

The four layers of an application

Data (tables and formulas), interface (artefacts and Grist pages), logic (SQL, UserActions, upsert), integrations (webhooks to the outside). All four are built from the same conversation, without switching tools halfway through.

When a spreadsheet is no longer enough, but full development is out of reach.

An IDE inside the document

The widget is a split screen: editor on the left, live preview on the right. Writing is incremental — read the code, replace a fragment, look. Render errors come back with line numbers instead of a silent failure.

To fix an interface without ever leaving Grist.

Standalone publishing

Publishing freezes the artefact into a section of the document and bundles its npm imports. The result is an ordinary widget: it no longer knows the server, and keeps working if the server disappears.

To ship something that no longer depends on you.

An agent embedded in the widget

Close to 2,800 lines of JavaScript run an agent loop inside the widget itself, so the document can build itself without an external MCP client. Model configuration is served by the server, and the key never leaves it.

When there is no MCP client in front of you, just a browser.

Guided dialogue

Rather than guessing, the assistant asks in the widget: a choice, a form, a confirmation, an external data import. The answer returns to the conversation and construction resumes where it stopped.

For decisions a model should not make alone. In beta.

One deployment per user

The Helm chart installs a personal server, guarded by a token and locked to its owner on first contact. An embedded OAuth 2.1 connector makes the server its own identity provider, which avoids pasting an API key into a client.

To go online without going through a multi-tenant service.

Getting started

How it goes

1
You add the widget
Coder installs as a custom widget on a page of the document. It registers with the server and opens a session.
2
You describe what you want
The assistant qualifies the need before touching anything. At that stage it does not even have access to the writing tools.
3
Schema first
Tables, columns, relationships. Interface tools only appear once the data is in place.
4
The interface builds in front of you
Code is written in the editor and the preview refreshes. What is wrong gets patched, not rewritten.
5
You publish
The artefact is frozen into the document. It no longer needs the server, and the end user only sees an application.

Use cases

When it matters

A spreadsheet that outgrew itself

The file runs a real process, but every new request turns into one more column and one more tab.

Without a proper interface, it piles up until nobody dares touch it.

A team with no developer available

The need is clear and the queue is long. Here, the person who knows the domain builds and fixes it themselves.

A tool delivered six months late describes a job that has changed since.

Data that must not leave

Self-hosted server, one deployment per user, keys held server-side. The document does not travel to a third party to get tooling.

A shared service would mean handing the document to someone else.

Going online

Hosted, and guarded

The server is not local-only. Deployed online it exposes the same MCP surface, with guards that do not rely on the client behaving.

A door before anything else

An application token closes /mcp, /register and the outbound proxy, compared in constant time. Left empty locally, there is no guard and nothing changes.

First in locks the door

The first Grist account to register becomes the server's owner; any other account is refused. An unresolved fallback identity never pins anything — it would lock the server to nobody.

The server is its own identity provider

A full OAuth 2.1 connector: discovery, dynamic client registration, authorization, token, PKCE S256. The Grist key is given once at consent and stays on the server; the client only ever receives an opaque token that expires and can be revoked.

Secrets do not leak through errors

The key used to leak through the request URL in error messages. Everything returned to a client now goes through token scrubbing.

The outbound proxy is closed by default

Model calls only reach explicitly allowlisted hosts. With an empty list the endpoint is disabled, so there is no pivot toward an internal service.

The model key never reaches the browser

The widget asks the server what it knows about the model and gets a base URL, a name and a boolean — never the key. Idle sessions are purged, and real-time fan-out is routed per user.

Changelog

5.14

Know-how corpus queryable by the assistant, with no open session required.

5.13

Embedded OAuth 2.1 connector: the server becomes its own identity provider, and the token it issues can be revoked.

5.12

Security audit: tokens scrubbed from errors, outbound proxy restricted to an allowlist, memory leaks closed.

5.9

Standalone artefact publishing, and a browser round-trip that gets past the application firewall.