Overview

The Bauplan MCP Server implements the Model Context Protocol (MCP) to expose Bauplan lakehouse operations to AI assistants (for example Claude Code, Claude Desktop, Cursor). It provides a lightweight local or hosted bridge that lets assistants query tables, inspect schemas, manage branches, run pipelines, and perform common data-lakehouse tasks programmatically.

This server is intended for developer workflows where an AI assistant needs structured access to a Bauplan catalog and execution surface. Use it to let an assistant explore data, propose or run pipelines, and orchestrate branch-based data work without exposing unnecessary permissions or requiring the assistant to have direct, low-level access to your lakehouse.

Features

Authentication tied to Bauplan API keys or local profiles
Table discovery: list tables in namespaces and branches
Schema inspection: read and display table schemas and sample rows
Branch management: create, list, and inspect branches
Pipeline control: list, run, and get status for pipelines
Multiple transport modes: stdio, Server-Sent Events (SSE), and Streamable HTTP
Integrations-ready: add to Claude Desktop / Code, Cursor, or other MCP-capable clients
Optional hosted deployment for Bauplan customers (contact Bauplan team)

Installation / Configuration

Prerequisites:

Python (recommended inside a virtual environment or via uv)
A Bauplan API key or configured Bauplan profile
An MCP-capable assistant (Claude, Cursor, etc.)

Quick start (using uv):

# install and sync dependencies (if using uv)
uv sync

# run the server (Streamable HTTP transport)
uv run python main.py --transport streamable-http

Default endpoint (streamable-http): http://localhost:8000/mcp

Add the server to Claude Code:

claude mcp add -t http mcp-bauplan http://localhost:8000/mcp

Add the server to Claude Desktop (example entry for claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-bauplan": {
      "command": "/path/to/bauplan-mcp-server/.venv/bin/python3",
      "args": [
        "/path/to/bauplan-mcp-server/main.py",
        "--transport",
        "stdio"
      ],
      "workingDirectory": "/path/to/bauplan-mcp-server/"
    }
  }
}

Notes:

Server-side deployment is available for existing Bauplan customers — contact your Bauplan account team to enable hosted MCP.
Avoid using an Admin Bauplan API key for AI-driven interactions. The server will refuse writes to main, but using least-privilege keys is recommended.

Configuration Options

Common CLI flags:

Option	Default	Description
–transport	stdio	Transport: stdio, sse, streamable-http
–host	127.0.0.1	Host to bind to (ignored for stdio)
–port	8000	Port to bind to (ignored for stdio)
–profile	None	Bauplan profile to use for authentication

Authentication precedence:

If a Bauplan API key header is sent from the client (header key: Bauplan), that key is used for the session.
If --profile is passed to the server, that profile is used.
Otherwise, the default local Bauplan profile is used.

This allows shared MCP hosts while letting clients supply per-session keys when appropriate.

Available Tools / Resources

The MCP server exposes a set of tools (MCP methods) that are typically available to the assistant. Typical tool set includes:

list_tables: list tables under a namespace/branch
get_schema: return table schema and column metadata
sample_rows: retrieve example rows for quick inspection
list_branches: enumerate branches for a repository/catalog
create_branch: create a new branch (feature branches for data work)
list_pipelines: list available pipelines for the repo/branch
run_pipeline: execute a named pipeline and return run status
get_pipeline_status: poll pipeline execution state

For manual testing, use the MCP Inspector:

npx @modelcontextprotocol/inspector

Configure the inspector for Streamable HTTP:

Transport Type: Streamable HTTP
URL: http://localhost:8000/mcp
Session Token: as provided by the inspector

Resources:

GitHub repo: https://github.com/BauplanLabs/bauplan-mcp-server
Walkthrough video: https://www.loom.com/share/651e2bd7ad4442928f539859a621c562
Blog with context and background: https://www.bauplanlabs.com/post/bauplans-mcp-server

Use Cases

Schema exploration: Ask an assistant to list tables in a branch and display the schema and sample rows for a given table to quickly understand data shape before writing queries.
- Example: “List tables in branch feature/etl-123 and show schema for purchases.daily_events.”
Branch-based experimentation: Create a feature branch, run a pipeline against synthetic or updated data, and inspect pipeline results without touching main.
- Example: “Create branch ai-suggested-joins from dev, run nightly-aggregation pipeline, and report status.”
Data debugging: When an assistant identifies bad records, you can have it query problematic partitions or columns to surface offending rows and propose fixes.
Orchestration from assistant: Trigger a pipeline run from the assistant and receive progress updates or final logs via the MCP run/poll tools.

Best Practices & Security

Use least-privilege Bauplan API keys for AI-driven flows; do not share admin keys.
Prefer branch-based workflows for assistant-driven changes, keeping main protected.
When hosting MCP for teams, consider per-client API key delegation (client supplies Bauplan header) for traceability.

For more examples and integration tips, see the repo README and the linked walkthrough video.

Bauplan MCP Server: Query, Schema, Branching, Pipelines