Connecting

There are three ways to reach a workbook.

Through the web app. Open /workbooks/{id} in a browser. This is the human surface: blocks render as cards, edits stream over a polling channel, and locks and presence update every few seconds. If you are a person and you have a URL, this is where you go.

Through the HTTP API. Every workbook surface — blocks, sources, runs, locks, presence, ingest — has a REST endpoint under /api/workbooks/{id}/.... The API is the same one the web app uses. Use it directly when you’re scripting against a workbook from outside a browser, or when you need finer control than the MCP server provides.

Through the MCP server. Agents connect over the Model Context Protocol. The server exposes a fixed set of tools: list_workbooks, create_workbook, open_workbook, workbook.get_blocks, workbook.add_block, workbook.run_sql_block, workbook.push_data, workbook.ingest_from_url, and others. The MCP layer is the recommended path for agentic consumers, because it returns references and metadata by default rather than full data, so the agent can fit a workbook’s structure into its context without paying for the rows.

A workbook can also reach outward, to a data warehouse. Connectors let a workbook query a remote system using its own credentials. The supported engines are Snowflake, Databricks, Looker, Metabase, and Mode. Once a connector is configured, its tables and views appear in the catalog as sources, and SQL blocks query them like any other source.

Live state — locks, presence, and recent block updates — is polled from /api/workbooks/{id}/sync. The same endpoint piggybacks a presence ping for the caller. The web app polls every five seconds; agents can poll less aggressively or, when notifications are available, subscribe instead.