Connecting AI tools

Let Claude and other AI tools drive DreamSheets — the built-in MCP server, a step-by-step setup walkthrough, and the zero-config clipboard loop.

Beyond the built-in assistant, DreamSheets can be driven by external AI tools. There are two paths:

  • The MCP server — agentic tools that speak the Model Context Protocol (Claude Code, Claude Desktop, and a growing ecosystem) connect directly to the running app and work on your document while you watch.
  • The clipboard loop — zero configuration, works with any chat AI in a browser.

The MCP server

DreamSheets embeds an MCP server. When enabled, an MCP client can read the open document, build or modify it, and run SQL over it — through exactly the same operations the app itself uses. That gives outside agents the same two guarantees as the built-in assistant: every change is undoable, and you watch it happen live on the canvas.

Security posture, up front:

  • Off by default. Nothing listens until you enable it.
  • Localhost only — it binds to your machine, never the network (default port 8737).
  • Token-authenticated — every request needs a bearer token generated on your machine. The token persists across restarts so client configs keep working.
  • Honors the "Don't send cell data to AI" privacy setting: with it on, run_sql isn't offered to the client at all, and get_document returns the document's structure — tables, columns, formulas, tiles, charts — with every cell and tile value withheld. A connected agent can still build and edit tables and formulas by name; it has no tool that can read a value. (Clients fetch the tool list once per connection, so an agent already connected sees the change after it reconnects. The rule is that the tool list is the privacy statement: no tool is advertised that promises a value it won't deliver. Tools that only create stay available in that mode — create_external_query_table lands real data on your canvas but reports only a name, a shape and a row count back to the agent.

Connect in one click

  1. In DreamSheets, open AI → AI Settings… and find the MCP Server section.
  2. Click the button for your AI app. It turns the server on and adds DreamSheets to that app's own configuration: - Claude Desktop & Cowork — quit Claude completely (including its tray icon) before clicking, then open it afterwards. While it is open, Claude rewrites its config from memory and would drop the entry; the button refuses until Claude is closed. - Claude Code — then start a new Claude Code session. Needs the claude command installed. - Codex / ChatGPT — covers the Codex CLI, the Codex app and the IDE extension, which share one configuration. Start a new session.
  3. Ask for something: "In DreamSheets, add a Products table with 10 sample rows and a price chart." Watch the canvas.

DreamSheets has to be open while the AI app uses it. Clicking a button again is safe — it replaces the old entry.

Manual setup (other MCP clients)

Any client that supports HTTP MCP servers works with the URL and token under Manual setup in the same section (Copy Client Config copies them):

{
  "mcpServers": {
    "dreamsheets": {
      "type": "http",
      "url": "http://127.0.0.1:8737/mcp",
      "headers": { "Authorization": "Bearer dsmcp_…" }
    }
  }
}

For Claude Code by hand: claude mcp add --transport http dreamsheets http://127.0.0.1:8737/mcp --header "Authorization: Bearer <your token>".

Claude Desktop is the exception: it only starts local programs, so it can't use a URL entry. The one-click button handles this by registering DreamSheets itself (DreamSheets mcp-stdio) as the program, which passes messages to the running app. On Windows, the Microsoft Store build of Claude reads its config from %LOCALAPPDATA%\Packages\Claude_…\LocalCache\Roaming\Claude\claude_desktop_config.json, not the %APPDATA%\Claude file its own "Edit Config" button opens — the one-click button writes both, so prefer it over editing by hand.

What a connected client can do

ToolWhat it does
describe_formatReturns the document-format and formula-language guide, so an agent can teach itself how to author DreamSheets documents correctly
get_documentThe open document as JSON — tables with data, tiles, charts, formulas, all by name
import_documentCompile a document description into the app — merged into the current document as one undoable step, or as a new document. In the current document, a table, tile or chart with a name that already exists is updated in place by default (onNameConflict: "update"); pass "rename" to add a copy or "error" to stop
apply_actionsApply a batch of granular actions (set cells, replace values, add or delete tables/columns/charts/tiles, create query tables, …) — atomically, all-or-nothing, one undo step. Tables and columns can be given by name as get_document shows them; set_cell takes a rowIndex (the position in the rows you read) or a rowId; replace_values does find-and-replace in one call; delete_table / delete_column / delete_tile / delete_chart remove something created by mistake
run_sqlRead-only DuckDB SELECT over the document's tables (capped at 1,000 rows). With "Don't send cell data to AI" on it still runs, but answers with the row count and the result's column names and types only — no values
list_connectionsThe database connections you have configured, as id + name + kind, so an agent can pick one. Connection strings are never returned — they live in your OS credential store and don't leave the app
add_connectionSave a new connection for kinds that need no credentials: a Socrata open-data portal, or a CSV / DuckDB / SQLite file, which you approve in a dialog first. Kinds that need a password or key are refused — the agent is told to ask you to add them under File → Database Connections…
describe_connectionThe tables (or Socrata datasets) and columns one connection exposes — names only, so an agent can write SQL against it
create_external_query_tableRun SQL on one of those connections and land the result as a new table on the canvas, on the tab you name. The table records the connection, so Refresh works on it exactly like one you made yourself
save_documentFile → Save without the dialog: to the document's own file, or to a .dsheet path the agent gives for a document that has never been saved

A well-behaved agent typically calls describe_format first, get_document to see what's there, then builds with import_document or apply_actions — and if it makes a mess, Ctrl+Z takes it back out, one batch at a time.

create_external_query_table is the one tool that reaches outside the document: everything else works on data that is already in it. It runs on its own rather than inside an apply_actions batch, so it is its own undo step — the same way landing a dataset is its own step when you do it by hand. It returns the new table's name, columns, row count and tier; it never returns cell values, which is why it stays available even with "Don't send cell data to AI" on. If the result is too large to hold in memory it lands as a read-only dataset and the agent is told so, so it can send a narrower query instead of quietly working against data it can't read back.

An agent can also group cards into a titled section frame (add_section, inside apply_actions), so a tab it builds for you has the same visual structure as one you would lay out yourself.

The clipboard loop (no setup, no API key)

Works with any chat AI, including a plain browser subscription:

  1. AI → Copy Prompt for AI — puts three things on the clipboard: the authoring guide (so the model knows the format), your current document as JSON, and a stub for your request.
  2. Paste into any chat, add what you want done, and let it answer with a JSON document — only the parts it is adding or changing; anything it leaves out stays as it is.
  3. Copy the JSON, then in DreamSheets: AI → Import AI Output… and paste.

Using claude.ai regularly? Download the DreamSheets skill and upload it once in your Skills settings — it is this same guide packaged so Claude knows the format and the edit workflow in every chat, and you only paste the document. The chat model still can't open a .dsheet file directly (it is JSON plus parquet in a zip); Copy Document for AI is what it reads.

The import validates before applying and applies as one undoable step. Into the current document, a table, tile or chart whose name already exists is updated in place (choose "Add as a copy" or "Stop with an error" in the dialog if you want otherwise), and the result opens in the same review panel the built-in assistant uses, so you can accept or discard item by item. Validation errors are precise (tabs[0].tables[1] ("Sales"): …) — fix them yourself or paste the error back to the model and let it correct its own output. There's also AI → Copy Document for AI when you only want the document JSON without the guide.

Which path when

  • Claude Code / Claude Desktop / agentic tools → the MCP server. Interactive, iterative, and the agent can read results (including SQL) and self-correct.
  • A quick one-shot with whatever chat you have open → the clipboard loop.
  • In-app, hands-on-keyboard work → the built-in assistant.
← AI assistanceAI authoring guide →