> Documentation index: https://docs.beetl.io/llms.txt

# MCP and programmatic access

> Connect Claude, Cursor or your own agent to Beetl over MCP.

Source: https://docs.beetl.io/mcp/
Last updated: 2026-11-10

Beetl runs an MCP server, so an AI client such as Claude, Cursor or an agent you build can work with
your tenant directly. The client calls the same tools the in-product assistant uses. It acts as you,
inside your tenant, with the scope of the API key you give it.

## What a client can do

With a `read` key, a client can:

* run SQL against your datasets with `execute_query` and page through the result
* read the catalog of datasets and pipelines, including a pipeline's working and deployed definitions
* inspect pipeline runs and preview a pipeline's working definition without writing anything
* trace where a dataset, pipeline or report gets its data with `get_lineage`
* read automations and their runs, including findings and rendered PDFs
* read apps, their input queries and their runs (apps cannot be changed over MCP)
* read reports, their documents and the shared report templates
* read file processors, their documents, the records extracted from them and the source text
* search and read the platform reference docs, including the SQL dialect

A `write` key adds the tools that build, update and deploy pipelines, and the tools that create,
update, run, pause, resume and delete automations. It also adds the tools that create and update
reports, tag their documents, save report templates and run a report with `render_report`, which
writes PDFs to your storage.

Queries over MCP are read-only, so SQL cannot insert, update or delete data whatever the client
sends. Neither scope writes to a system you connected. See
[The agent trust boundary](https://docs.beetl.io/concepts/agent-trust-boundary) for what each write tool changes.

## Choose a scope

| Scope   | Give it to a client that should                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `read`  | Answer questions from your data, explain pipelines and check on runs, automations, apps, reports and extracted documents. |
| `write` | Also author and deploy pipelines, manage automations, and create and run reports on your behalf.                          |

Give a client a `read` key unless it must change things. A `read` key only lists and only calls read
tools.

> **A write key deploys without asking.**
> In chat, a deploy waits for you to confirm it. Over MCP, a `write` key deploys directly, and the
> deploy starts a run that writes the pipeline's destination dataset. `render_report` also runs
> without asking and writes PDFs to your storage. Treat a `write` key like a deploy credential.

## Protocol

|                   |                                                                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Endpoint          | `POST https://app.beetl.io/mcp`                                                                                                    |
| Transport         | Streamable HTTP with JSON-RPC 2.0. Send single or batched requests; each is answered with a JSON body.                             |
| Protocol versions | `2025-11-25` and `2025-06-18`. `initialize` answers with the version you asked for when Beetl supports it, otherwise `2025-11-25`. |
| Methods           | `initialize`, `ping`, `tools/list`, `tools/call`                                                                                   |
| Capabilities      | `tools`                                                                                                                            |
| Authentication    | `X-API-Key` header on every request                                                                                                |
| Sessions          | Stateless. Each request stands on its own, with no session header.                                                                 |

`tools/list` returns the tools your key's scope allows, each with an input and an output schema. A
successful call returns text content plus `structuredContent` that matches the output schema. A
failed call returns `isError: true` with a message.

To push data in from your own code instead, use a [Webhook](https://docs.beetl.io/sources/webhook). It is the only other
public endpoint, and its request reference is at [Ingest](https://docs.beetl.io/mcp/rest/ingest).

## In this section

| Page                                   | What it covers                                                                |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| [MCP setup](https://docs.beetl.io/mcp/setup)                | Create a key, pick a scope, wire it into Claude or Cursor.                    |
| [Tool reference](https://docs.beetl.io/mcp/tool-reference)  | Every tool an MCP client can call, with its scope and arguments.              |
| [Webhook ingest API](https://docs.beetl.io/mcp/rest/ingest) | The request a webhook connection accepts: `POST /api/ingest/{connection_id}`. |