Advanced Configurations

Python Setup

You can run the MCP server also using a standard Python virtual environment:

python -m venv venv && source venv/bin/activate
pip install -e .

Bauplan Credentials

The Beta release covers the local development use case. Authentication to your Bauplan lakehouse happens as follows:

• if you do not specify a Bauplan profile as a flag (see below CLI options), the default one on the machine running the server will be used at every interaction with the lakehouse.
• if you specify a profile as a flag, this profile will be used instead when instantiating a Bauplan client.
• if you specify a header in your assistant - key=Bauplan, value=your_api_key (e.g. in Claude code claude mcp add -H "Bauplan: <your-bauplan-api-key>" ...) -, your_api_key will be used instead when instantiating a Bauplan client. This is convenient for quick tests, and opens up the possibility of hosting the catalog on a shared infrastructure, delegating to clients the Bauplan API key management.

CLI Options

The server supports the following CLI options, mostly useful for specifying alternative transport options:

Option	Default	Description	Used With
--transport	stdio	Transport protocol: stdio, sse, or streamable-http	All commands
--host	127.0.0.1	Host to bind to (localhost by default)	sse, streamable-http only
--port	8000	Port to bind to	sse, streamable-http only
--profile	None	Bauplan profile to use	All commands

Note: The --host and --port options are ignored when using stdio transport since it communicates through stdin/stdout.

Claude Desktop

To add the Bauplan MCP server to Claude Desktop, follow the guide to get to your claude_desktop_config.json file.

Automatic Configuration Generation

Use the provided script to generate the configuration with the correct paths:

uv run scripts/generate-config.py

This will output a JSON configuration with all paths properly set to your installation directory. Copy the output and add it to your claude_desktop_config.json file.

Manual Configuration

Alternatively, you can manually add this configuration (modify the paths as needed):

{
  "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/"
    }
  }
}

Quit and restart Claude Desktop. Now all Bauplan tools are available to your assistant, as this video demonstrates.

MCP Inspector

Start the MCP Inspector if you wish to manually test the server (Node is required):

npx @modelcontextprotocol/inspector

Now, configure the inspector with the proper variables, e.g. for Streamable HTTP:

• Transport Type: Streamable HTTP
• URL: http://localhost:8000/mcp
• Session Token: Use the token from inspector output