MCP and programmatic access
Connect Claude, Cursor or your own agent to Beetl over MCP.
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_queryand 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 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. It is the only other public endpoint, and its request reference is at Ingest.
In this section
| Page | What it covers |
|---|---|
| MCP setup | Create a key, pick a scope, wire it into Claude or Cursor. |
| Tool reference | Every tool an MCP client can call, with its scope and arguments. |
| Webhook ingest API | The request a webhook connection accepts: POST /api/ingest/{connection_id}. |
Last updated on