Lakebase MCP

Lakebase MCP服务器

生产准备就绪 模型上下文协议（MCP） 服务器 copula湖基 --Rancher上的托管PostgreSQL服务，具有自动缩放、分支和Unity Catalog治理功能。

该服务器使AI代理（Claude、GPT、Copilot等）能够完全控制Lakebase数据库：查询、模式探索、计算管理、分支、迁移、增量同步、数据质量分析和功能服务——所有这些都是通过标准MCP接口实现的。

______________________________________________________________________

关键能力

• 46工具 跨越13个类别——查询、模式、项目、分支、计算、迁移、同步、同步表、端点、监控、质量、功能存储、统一通信治理
• 4个提示模板 --用于探索、迁移、同步和自动缩放调整的指导性工作流程
• 1个会话资源 — memo://insights 用于在分析过程中积累观测值
• 交互式UI仪表板 --5页React+FastAPI应用程序，带有工具浏览器、治理矩阵、连接向导和定价计算器
• 自动缩放感知 --指数回退重试，用于扩展到零、读取副本路由、计算生命周期管理
• 安全第一 --写保护、危险功能阻止、生产分支保护、只读事务执行
• 双输出 --每个工具的markdown表（人性化）或JSON（程序化）
• 完全异步 --基于FastMCP构建 psycopg 3.x异步连接池
• 查询成本归属 --SQL注释标记(/* lakebase_mcp:tool_name */) + application_name 对于pg_stat活动
• 运输灵活性 --可流式传输的http（默认，生产）或stdio(--transport stdio 克劳德桌面）

______________________________________________________________________

工具参考（46个工具）

查询工具（3）

架构发现工具（4）

项目管理工具（7）

分支工具（3）

计算管理工具（6）

迁移工具（2）

同步工具（2）

同步表工具（4）

端点管理工具（4）

监控工具（3）

数据质量工具（1）

功能存储工具（2）

克劳德代码中的用法：

Use the lakebase_explore_database prompt to guide your exploration of my database.

Python MCP客户端中的用法：

prompt = await session.get_prompt("lakebase_autoscaling_tuning")
print(prompt.messages[0].content.text)

______________________________________________________________________

自动缩放感知设计

此服务器专为Lakebase自动缩放计算而构建：

缩放到零重试

当计算暂停时，第一次连接尝试失败。服务器以指数回退重试：

• 尝试次数：5次（可通过以下方式配置 LAKEBASE_S2Z_RETRY_ATTEMPTS)
• 延迟：0.5秒->1.0秒->2.0秒->4.0秒->8.0秒（上限为 LAKEBASE_S2Z_MAX_DELAY)
• 捕捉： OperationalError, ConnectionException, ConnectionRefusedError, OSError

读取副本路由

• lakebase_read_query 电话 execute_readonly() 哪个更喜欢副本池
• lakebase_execute_query 始终使用主池
• 如果副本不可用，则自动回退到主副本

连接健康状况

• 结账前健康检查(AsyncConnectionPool.check_connection)
• 最大生存期：300秒--回收陈旧连接
• 最大空闲时间：60s--空闲连接被清除
• 重新连接超时：30s

自动缩放感知错误消息

______________________________________________________________________

查询成本归属

灵感来自雪花 QUERY_TAG 模式，Lakebase MCP为成本跟踪和可观察性提供了两层查询属性：

1.应用程序级标记

所有连接包括 application_name=lakebase_mcp 在连接字符串中。这出现在：

• pg_stat_activity.application_name --在活动查询中识别MCP会话
• PostgreSQL日志——在日志分析中过滤MCP流量

2.工具级SQL注释

每个查询前面都有一个SQL注释，用于标识发起工具：

/* lakebase_mcp:lakebase_read_query */ SELECT * FROM users LIMIT 10;

这出现在：

• pg_stat_statements --按工具划分的总成本
• 查询日志——跟踪单个工具调用

______________________________________________________________________

安全控制

______________________________________________________________________

精细治理

服务器提供 双层治理 用于控制AI代理可以做什么——匹配并超越Snowflake MCP的访问控制能力。

建筑

Request: lakebase_execute_query("DROP TABLE users")

Layer 1 — Tool Access Control
  Is "lakebase_execute_query" permitted? → check tool profile/allow/deny

Layer 2 — SQL Statement Governance
  Parse "DROP TABLE users" via sqlglot → SQLStatementType.DROP
  Is DROP in allowed types? → check SQL profile/allow/deny

Both layers must PASS for execution to proceed.

SQL语句配置文件

服务器使用以下方式对SQL进行分类 sqlglot AST解析 （不是正则表达式）来准确处理CTE、子查询、多语句SQL和Postgres特定的语法。

工具访问配置文件

快速入门示例

只读代理 （限制性最强——非常适合编码助理）：

export LAKEBASE_SQL_PROFILE=read_only
export LAKEBASE_TOOL_PROFILE=read_only
export LAKEBASE_TOOL_DENIED=lakebase_execute_query  # force read_query only

分析师代理 （SELECT+INSERT用于暂存）：

export LAKEBASE_SQL_PROFILE=analyst
export LAKEBASE_TOOL_PROFILE=analyst

开发商代理 （完全CRUD，无管理员）：

export LAKEBASE_SQL_PROFILE=developer
export LAKEBASE_TOOL_PROFILE=developer

传统模式 （向后兼容——无治理环境变量）：

export LAKEBASE_ALLOW_WRITE=false  # same behavior as before

YAML配置（可选）

对于复杂的策略，请使用YAML文件而不是env-vars：

export LAKEBASE_GOVERNANCE_CONFIG=/path/to/governance.yaml

看 governance.yaml.example 以获取完整参考。

治理环境变量

______________________________________________________________________

Unity目录集成

Lakebase MCP在三个层面上与Unity Catalog治理集成：

第一级：权限反思

代理可以在尝试操作之前查询自己的UC权限：

> What can I access in the hls_amer_catalog?

Agent calls: lakebase_governance_summary(catalog="hls_amer_catalog")

Result:
  SQL Governance: read_only (SELECT, SHOW, DESCRIBE, EXPLAIN)
  Tool Access: all read-only tools
  UC Privileges: SELECT, USE_CATALOG, USE_SCHEMA
  Recommended profile: read_only or analyst

第二级：联合目录

Lakebase数据库注册为 国外目录 在Unity目录中：

• 模式和表出现在目录资源管理器中
• UC授权（SELECT、MODIFY等）控制元数据访问
• 凭证自动售货尊重UC权限
• 可以应用行过滤器和列掩码

第三级：三层访问控制

Agent Request → MCP Tool Governance → SQL Statement Governance → UC Permission Check
                (tool_guard.py)        (sql_guard.py)             (PostgreSQL + UC grants)

Layer 1: Is the tool allowed?        (LAKEBASE_TOOL_PROFILE)
Layer 2: Is the SQL type allowed?    (LAKEBASE_SQL_PROFILE)
Layer 3: Does UC permit this object? (Unity Catalog grants)

所有三层都必须允许操作成功。

______________________________________________________________________

UI仪表板

一个功能齐全的React+FastAPI web应用程序，用于探索、配置和估算Lakebase MCP服务器的成本。已部署为copula应用程序。

第（5）页

定价计算器

定价页面提供了三个维度的交互式成本估算：

• 代币成本计算器 --选择Claude模型（Opus/Sonet/Haiku），调整每个会话的工具调用，请参阅每个调用和每个会话的成本。包括型号推荐横幅（例如，“切换到Sonnet可节省40%”）
• 计算成本估算师 --选择CU大小（0.5-32）、地区和使用模式（始终与比例为零）。计算每月DBU成本
• 存储成本估算师 --输入数据库大小和分支。强调分支是免费的（写时复制）
• 月度总估算 --结合令牌+计算+存储，可调整会话/月
• 竞争比较 --并排的Lakebase vs Snowflake MCP vs Teradata MCP：计算成本、会话成本、工具数量、治理层和关键差异化因素
• 成本优化技巧 -可操作的建议（即时缓存、模型选择、缩放为零、批量API）

构建和部署

# Build frontend
python ui/build.py

# Deploy to Databricks Apps
python ui/deploy_to_databricks.py --app-name lakebase-mcp-ui

# Hard redeploy (delete and recreate)
python ui/deploy_to_databricks.py --app-name lakebase-mcp-ui --hard-redeploy

UI测试（44个测试）

cd ui/frontend
npx vitest run

______________________________________________________________________

快速开始

先决条件

• Python 3.11+
• 紫外线 （推荐）或pip
• 启用了Lakebase的copula工作区
• Rancher CLI已通过身份验证(databricks auth login)

1.克隆和安装

git clone https://github.com/suryasai87/lakebase-mcp.git
cd lakebase-mcp
uv sync

2.配置环境

创建一个 .env 文件或导出这些环境变量：

# Required — Lakebase connection
export LAKEBASE_HOST="ep-your-endpoint.database.us-east-1.cloud.databricks.com"
export LAKEBASE_DATABASE="databricks_postgres"

# Optional — Databricks workspace (for compute/project/branching tools)
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"

# Optional — Read replica
export LAKEBASE_REPLICA_HOST=""

# Optional — Safety (defaults shown)
export LAKEBASE_ALLOW_WRITE="false"
export LAKEBASE_MAX_ROWS="1000"
export LAKEBASE_QUERY_TIMEOUT="30"

# Optional — Scale-to-zero retry (defaults shown)
export LAKEBASE_S2Z_RETRY_ATTEMPTS="5"
export LAKEBASE_S2Z_RETRY_DELAY="0.5"

# Optional — Pool lifecycle (defaults shown)
export LAKEBASE_POOL_MAX_LIFETIME="300"
export LAKEBASE_POOL_MAX_IDLE="60"

3.本地运行

# Default: Streamable HTTP (production, stateless, horizontal scaling)
uv run lakebase-mcp

# Alternative: stdio transport (for Claude Desktop direct integration)
uv run lakebase-mcp --transport stdio

服务器启动于 http://localhost:8000/mcp 默认情况下使用Streamable HTTP传输。

4.连接AI代理

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "lakebase": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

克劳德代码(.claude/mcp.json)

{
  "mcpServers": {
    "lakebase": {
      "type": "streamable_http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

任何MCP客户端（Python）

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("http://localhost:8000/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # List all 46 tools
        tools = await session.list_tools()

        # Run a query
        result = await session.call_tool(
            "lakebase_read_query",
            arguments={"sql": "SELECT current_database(), version()"}
        )
        print(result.content[0].text)

______________________________________________________________________

部署到ViewModel

选项A:copula应用程序（推荐）

1. 创建应用程序

databricks apps create lakebase-mcp-server --profile DEFAULT

1. 设置秘密 用于Lakebase连接

databricks apps set-secret lakebase-mcp-server LAKEBASE_HOST \
  "ep-your-endpoint.database.us-east-1.cloud.databricks.com" --profile DEFAULT

databricks apps set-secret lakebase-mcp-server LAKEBASE_DATABASE \
  "databricks_postgres" --profile DEFAULT

1. 同步和部署

DATABRICKS_USERNAME=$(databricks current-user me --profile DEFAULT | jq -r .userName)

databricks sync . "/Users/$DATABRICKS_USERNAME/lakebase-mcp-server" --profile DEFAULT

databricks apps deploy lakebase-mcp-server \
  --source-code-path "/Workspace/Users/$DATABRICKS_USERNAME/lakebase-mcp-server" \
  --profile DEFAULT

1. 访问MCP端点

https://lakebase-mcp-server-.aws.databricksapps.com/mcp

选项B:Unity目录MCP目录注册

部署后，在UC MCP目录中注册服务器，以便所有工作区用户都可以发现它：

uv run python deploy/register_mcp_catalog.py

编辑 deploy/register_mcp_catalog.py 在运行之前设置实际的应用程序URL。

______________________________________________________________________

建筑

lakebase-mcp/
├── server/
│   ├── main.py              # FastMCP server, lifespan, tool registration, governance wiring
│   ├── config.py            # Environment-based configuration (19 vars)
│   ├── db.py                # Async connection pool (S2Z retry + replica routing + query tagging)
│   ├── auth.py              # Databricks SDK auth (OBO + standard) + UC permissions
│   ├── governance/
│   │   ├── sql_guard.py     # sqlglot-based SQL statement classification (17 types)
│   │   ├── tool_guard.py    # Per-tool access control (16 categories, 4 profiles)
│   │   └── policy.py        # Unified policy engine (env vars + YAML)
│   ├── tools/
│   │   ├── query.py         # 3 tools: read, execute, explain
│   │   ├── schema.py        # 4 tools: schemas, tables, describe, tree
│   │   ├── instance.py      # 7 tools: projects, describe, connection string, create/delete project, credentials
│   │   ├── branching.py     # 3 tools: create, list, delete branches
│   │   ├── compute.py       # 6 tools: autoscaling, S2Z, metrics, replicas
│   │   ├── migration.py     # 2 tools: prepare, complete
│   │   ├── sync.py          # 2 tools: create sync, list syncs
│   │   ├── synced_tables.py # 4 tools: list, create, delete, status for synced tables
│   │   ├── endpoints.py    # 4 tools: list, create, update, delete endpoints
│   │   ├── monitoring.py   # 3 tools: replication status, WAL stats, CDC monitor
│   │   ├── quality.py       # 1 tool: profile table
│   │   ├── feature_store.py # 2 tools: lookup, list feature tables
│   │   └── uc_governance.py # 4 tools: UC permissions, access check, governance summary, catalog grants
│   ├── resources/
│   │   └── insights.py      # memo://insights resource + append tool
│   ├── prompts/
│   │   └── templates.py     # 4 prompt templates
│   └── utils/
│       ├── errors.py        # Autoscaling-aware error handling
│       ├── formatting.py    # Markdown/JSON response formatting
│       └── pagination.py    # Cursor-based pagination
├── ui/
│   ├── backend/
│   │   ├── app.py           # FastAPI app serving React SPA + API
│   │   └── routers/
│   │       └── metadata.py  # 12 API endpoints (tools, governance, pricing)
│   ├── frontend/
│   │   ├── src/
│   │   │   ├── App.jsx      # Router with 5 animated pages
│   │   │   ├── components/
│   │   │   │   └── Layout.jsx  # Sidebar navigation, app bar
│   │   │   ├── pages/
│   │   │   │   ├── Home.jsx              # Dashboard with stats and quick links
│   │   │   │   ├── ToolExplorer.jsx      # Tool browser with search and filters
│   │   │   │   ├── ConnectionWizard.jsx  # MCP client connection setup
│   │   │   │   ├── GovernanceDashboard.jsx # Access control matrices
│   │   │   │   └── PricingCalculator.jsx # Cost estimators and comparison
│   │   │   └── hooks/
│   │   │       └── useApi.js  # Shared fetch hook
│   │   └── __tests__/       # 44 Vitest tests (7 suites)
│   ├── build.py             # Frontend build script
│   ├── deploy_to_databricks.py  # Staging-based deployment
│   └── app.yaml             # Databricks App config for UI
├── tests/
│   ├── test_unit/           # 39+ unit tests (no connection needed)
│   ├── test_integration/    # Live connection tests
│   └── test_e2e/            # Full MCP protocol tests
├── deploy/
│   └── register_mcp_catalog.py  # Unity Catalog registration
├── eval/
│   └── evaluation.xml       # 10 evaluation Q&A pairs
├── app.yaml                 # Databricks App configuration (MCP server)
├── pyproject.toml           # Project metadata (v0.2.0)
├── requirements.txt         # Pip-compatible requirements (includes sqlglot for SQL governance)
└── TESTING_SCENARIOS.md     # Comprehensive test scenarios for all 46 tools

______________________________________________________________________

运行测试

# Unit tests (no Lakebase connection needed)
uv run pytest tests/test_unit/ -v

# Integration tests (requires LAKEBASE_LIVE_TEST=true + connection)
LAKEBASE_LIVE_TEST=true uv run pytest tests/test_integration/ -v

# E2E tests (requires running MCP server)
LAKEBASE_E2E_TEST=true MCP_SERVER_URL=http://localhost:8000/mcp \
  uv run pytest tests/test_e2e/ -v

______________________________________________________________________

配置参考

______________________________________________________________________

对话示例

探索数据库

你：我的Lakebase数据库中有哪些表？给我看看最大的那个。 代理: *呼叫 lakebase_list_schemas -> lakebase_list_tables -> lakebase_describe_table* 您的数据库有3个模式（公共、分析、暂存），总共有24个表。最大的是 public.transactions 约240万行。..

调整自动缩放

你：我的开发数据库太贵了。你能把刻度调到零吗？ 代理: *呼叫 lakebase_get_compute_status -> lakebase_get_compute_metrics -> lakebase_configure_scale_to_zero* 完成。您的开发分支现在会在60秒不活动后挂起，并在下一次查询时在约200毫秒后唤醒。根据您的指标，计算有78%的时间处于空闲状态——这应该会大大降低成本。

安全架构迁移

你：添加a last_login 将列添加到用户表中，但请先对其进行测试。 代理: *呼叫 lakebase_prepare_migration -> lakebase_describe_table （在分支上）-> lakebase_complete_migration(apply=true)* 迁移已应用。这 last_login 时间戳列现在已投入生产 users 桌子。我首先在一个分支上测试了它，以验证没有现有的查询被破坏。

设置功能服务

你：将customer_features表从Delta Lake同步到Lakebase以进行实时服务。 代理: *呼叫 lakebase_create_sync 方向=delta_to_lakebase，频率=连续* 已创建连续同步管道。这 analytics.ml.customer_features Delta表将把更改流式传输到Lakebase。使用 lakebase_lookup_features 用于亚毫秒级查找。

配置文件数据质量

你：检查订单表的数据质量。 代理: *呼叫 lakebase_profile_table 其中table_name=“public.orders”* |列|类型|空值%|不同值|最小值|最大值|平均值| |--------|------|--------|----------|-----|-----|-----| |order_id |整数|0%|50000|1|50000|25000.5| |金额|数字|2.3%|4521|0.99|9999.99 |142.87| |状态|文本|0%|5||||

______________________________________________________________________

认证

服务器支持多种身份验证模式：

Unity目录权限在数据库层强制执行——服务器不会绕过访问控制。

______________________________________________________________________

已知限制和路线图

通过将MCP实现与最新的copula Lakebase API（2026年4月）进行比较，发现了以下差距：

全面差距分析并提出建议： 汇流——Lakebase MCP服务器

______________________________________________________________________

许可证

Apache 2.0