Connect your agent

Bauplan is driven entirely by code, which makes it a natural fit for AI agents. The whole lakehouse is programmable through a CLI and a Python SDK.

Git-for-data branching is what makes it safe to hand that control to an agent. The agent creates an isolated data branch then follows the Write-Audit-Publish pattern: it writes changes in the branch, validates those changes with expectations, and publishes those changes to a final branch when the checks pass.

There are three ways to use Bauplan with an assistant: skills for structured workflows, an MCP server for live access, and reading the documentation and an agent instructions file into the assistant context. Each approach can be used individually or mixed as desired in the same session.

Prerequisites

A Bauplan API key;
An AI assistant. Skills need one that supports plugins, such as Claude Code, Codex, or Cursor. The MCP server needs one that supports MCP.
The Bauplan CLI installed and configured with your key (optional if you use the MCP server);

Skills

Bauplan Skills are reusable, declarative workflow templates that guide an LLM through multi-step data engineering tasks using Bauplan. Each skill encodes the intent, constraints, and expected sequence of a workflow that is otherwise easy to get wrong, while still operating on the same Bauplan primitives: branches, runs, checks, and merges.

Skills are available at github.com/BauplanLabs/bauplan-skills and can be used in Claude Code, Codex, Cursor, and all major harnesses and IDEs. We recommend installing them from this repository so you can easily update to the latest version.

Claude Code

Install Bauplan Skills in Claude Code by following the instructions in this video, or by running:

claude plugin marketplace add BauplanLabs/bauplan-skills
claude plugin install bauplan@bauplan-skills

To update to the latest version, run:

claude plugin update bauplan@bauplan-skills

Codex

Install Bauplan Skills in Codex by following the instructions in this video, or by running:

codex plugin marketplace add BauplanLabs/bauplan-skills
codex plugin add bauplan@bauplan-skills

To update to the latest version, run:

codex plugin marketplace upgrade bauplan-skills

Cursor

Install Bauplan Skills in Cursor by following the instructions in this video, or by going to Settings > Customize > Plugins > Add > From GitHub Repository, entering https://github.com/BauplanLabs/bauplan-skills, and clicking Add.

To update to the latest version, click Refresh.

Available skills

Once installed, the following skills are available:

Skill	Description
bauplan-data-pipeline	Create a new pipeline project from scratch with proper setup, model definitions, source validation, and execution on a development branch.
bauplan-safe-ingestion	Ingest data from S3 using the Write-Audit-Publish pattern: the agent loads data on an isolated branch, validates it, and merges only after quality checks pass.
bauplan-explore-data	Structured, read-only investigation of lakehouse data through schema inspection, sampling, profiling, and join discovery. Produces a `summary.md` report.
bauplan-data-assessment	Evaluate whether lakehouse data can answer a business question. Maps concepts to tables, profiles quality, and delivers a feasibility verdict.
bauplan-data-quality-checks	Generate quality check code as pipeline expectations with `@bauplan.expectation` and ingestion validation functions covering completeness, uniqueness, validity, freshness, consistency, and volume.
bauplan-debug-and-fix-pipeline	Structured diagnostics for failed jobs: pins the failure, collects evidence, identifies root cause, and applies a minimal fix with checkpoint reports.
bauplan-migrate-to-typed-sdk	Migrate existing Bauplan projects from the old SDK style (0.1.x or 0.2.x) to the typed SDK (0.3 and later).
bauplan-data-semantics	Read and draft table and column documentation stored in Iceberg. Check what a column means before querying it, diagnose results that look plausible but are wrong, and draft docs for columns whose meaning isn't clear from name and type.

MCP server

The Bauplan MCP Server is a Model Context Protocol integration that gives AI assistants direct access to your Bauplan lakehouse. It works with any MCP-capable assistant, from chat apps like Claude Desktop and the ChatGPT app to coding agents like Claude Code, Cursor, and Codex.

To connect to the Bauplan MCP server, point your assistant at Bauplan's hosted MCP endpoint https://mcp.use1.aprod.bauplanlabs.com/mcp and authenticate with your Bauplan API key.

What an assistant can do

Through the MCP server, an assistant can:

Inspect tables and schemas, and run queries;
Manage branches, commits, namespaces, and tags;
Create, import, and revert tables;
Run Bauplan projects and pipelines;
Track, inspect, and cancel jobs.

Watch our demo to see an AI assistant debug a data pipeline.

Resources

The code behind the Bauplan MCP server is public and available at https://github.com/BauplanLabs/bauplan-mcp-server.

Using an MCP server is a good way to let non-technical stakeholders interact with the data without intermediaries. We have addressed such a scenario in a dedicated blog post where we show how one can integrate the Bauplan MCP server with Linear and Claude Code to query data and file requests to the data team.

Docs and repository context

Bauplan is largely self-documenting: an assistant can run bauplan --help to find CLI commands and read the SDK's type signatures to call it correctly. This approach works with any assistant because it does not need a plugin or server; however, it's sometimes useful to provide explicit guidelines beyond the API contract of the SDK/CLI. For that, give the assistant two things:

The documentation in Markdown: all our docs are in markdown so the agent can read them with ease and use the best practices we recommend.
AGENTS.md: additional rules and best practices you may want to enforce on top of the official docs.

Feeding documentation to LLMs

Bauplan's documentation is published in formats meant to be read by models, not just people:

llms.txt is a single-page index of the documentation following the llms.txt convention, small enough to fit in a single context window.
Markdown version of any page: append .md to any documentation URL to get a plain Markdown version. For example, /concepts/tables becomes /concepts/tables.md. This is useful for pasting a specific page into an assistant as context.
Accept: text/markdown: an agent that sends this header gets the Markdown version of a page back from its normal URL, without knowing the .md convention.
The full CLI and SDK reference as Markdown: the entire API reference is available as two self-contained Markdown files, reference/cli.md and reference/bauplan.md. Feeding these two files to an agent gives it the complete, authoritative syntax of every command and SDK method in one shot, which sharply reduces hallucinated flags and arguments when it generates code.

Repository context

An agent instructions file at your project root tells the assistant how to work with Bauplan before it writes any code: how to authenticate, the branch-based workflow, CLI and SDK conventions, and the safety rules to follow. We maintain a agents instructions file as a general starting point, which you can edit to match your team's conventions. Add it to your project with:

curl -o AGENTS.md https://raw.githubusercontent.com/BauplanLabs/bauplan-skills/main/CLAUDE.md

note

Depending on the AI coding tool of your choice, this file might follow a different naming convention. For instance, Codex, Cursor, and many other assistants read AGENTS.md. Claude Code reads CLAUDE.md by default but uses AGENTS.md as a fallback.

Next steps

Your agent is connected. Try asking it:

Create a new branch under my username and give me a quick summary of the data available on it.

Learn more

The Bauplan blog covers running AI and agents safely on your data, alongside technical deep-dives on the platform. The team also publishes peer-reviewed research on the data systems behind Bauplan and their application to AI and agentic workflows. Find our latest results on Google Scholar.

For long-form talks and demos, see our YouTube channel.