Lakebase MCP Server

Lakebase MCP服务器

可重复使用 模型上下文协议 （MCP）服务器 copula湖基 （PostgreSQL兼容数据库）。将其部署为copula应用程序，为AI代理提供对您的操作数据的完全读/写/DDL访问权限。

它做什么

• 暴露 33个MCP工具 具有用于模式检查、CRUD、通用SQL、DDL、事务、查询分析、性能监控、基础设施管理、分支管理、自动扩展配置、数据质量分析、安全迁移、查询调优和跨数据库搜索的安全注释
• 2 MCP资源 用于表和模式发现
• 3个MCP提示 用于数据库探索、模式设计和查询优化
• MCP工具注释 (readOnlyHint, destructiveHint, idempotentHint)在客户端安全UI的每个工具上
• 支持两者 已配置 和 自动缩放 具有自动令牌刷新功能的Lakebase实例
• 多实例切换 --从UI浏览并切换工作区中的所有Lakebase实例
• 作为一个 外部MCP服务器 Rancher多代理监控器（MAS）中的代理
• 包括a 网页用户界面 使用数据库浏览器、SQL编辑器、工具游乐场、实例/数据库切换器和文档
• 提供 REST API （29+个端点）用于自定义集成

建筑

AI Agent (MAS / Claude Code / etc.)
    |
    | MCP Protocol (StreamableHTTP)
    v
Lakebase MCP Server (Databricks App)
    |-- /          Web UI (explorer, SQL editor, tool playground, docs)
    |-- /mcp/      MCP endpoint (stateless StreamableHTTP)
    |-- /db/{db}/mcp/  MCP endpoint scoped to a specific database
    |-- /api/*     REST API (29+ endpoints)
    |-- /health    Health check
    |
    | psycopg2 (PostgreSQL wire protocol + auto token refresh)
    v
Lakebase Instance(s) (Provisioned or Autoscaling)

连接模式

服务器根据环境变量自动检测其连接模式。无需更改代码。

预置湖基（默认）

使用标准的copula Apps数据库资源。平台自动注入 PGHOST, PGPORT, PGDATABASE，以及 PGUSER 环境变量。

# app.yaml
command:
  - python
  - mcp_server.py

resources:
  - name: database
    database:
      instance_name: my-instance      # your provisioned Lakebase instance
      database_name: my_database       # your database name
      permission: CAN_CONNECT_AND_CREATE

自动缩放湖基

集 LAKEBASE_PROJECT 作为环境变量。服务器自动执行以下操作：

1. 发现指定分支上的终结点
2. 通过copula SDK生成OAuth凭据
3. 每50分钟刷新一次代币（在1小时到期之前）

# app.yaml
command:
  - python
  - mcp_server.py

env:
  - name: LAKEBASE_PROJECT_NAME
    value: "My Project"            # human-readable label shown in the web UI
  - name: LAKEBASE_PROJECT
    value: "b10eb92b-dc0e-4ccf-ba26-0653c5e7ebec"  # project UUID (from Lakebase project URL)
  - name: LAKEBASE_BRANCH
    value: "br-cool-haze-d2hbxj2m"  # branch ID (not display name — find it in branch overview)
  - name: LAKEBASE_DATABASE
    value: "my_db"                 # optional, default: databricks_postgres

查找值：

• LAKEBASE_PROJECT_NAME：任何人类可读的标签（例如。 "Manufacturing EPL", "Supply Chain Demo")
• LAKEBASE_PROJECT：在ViewModel中→ 湖基→ 单击您的项目→ UUID位于页面URL中
• LAKEBASE_BRANCH：在ViewModel中→ 湖基→ 你的项目→ 单击分支→ ID 字段（看起来像 br-cool-haze-d2hbxj2m).这是 不 显示名称（例如。 production)

不 resources 自动缩放所需的块——服务器在内部处理端点发现和身份验证。

在模式之间切换

要切换模式，请更新 app.yaml 并重新部署。服务器在启动时自动检测模式。

部署

先决条件

• 使用工作区配置文件配置了copula CLI
• 已创建Lakebase实例（已配置或自动缩放）

步骤1：创建应用程序

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

步骤2：配置 app.yaml

编辑 app/app.yaml 使用您的Lakebase实例详细信息（请参见 连接模式 上文）。如果希望平台为多个实例自动注入凭据，可以配置多个数据库资源：

command:
  - python
  - mcp_server.py

resources:
  - name: database
    database:
      instance_name: my-instance
      database_name: my_database
      permission: CAN_CONNECT_AND_CREATE
  # Optional: add more databases for auto-configured access
  - name: database-2
    database:
      instance_name: another-instance
      database_name: another_db
      permission: CAN_CONNECT_AND_CREATE

步骤3：同步和部署

# Sync local code to workspace
databricks sync ./app /Workspace/Users//lakebase-mcp-server/app \
  --profile=
 --watch=false

# Deploy the app
databricks apps deploy lakebase-mcp-server \
  --source-code-path /Workspace/Users//lakebase-mcp-server/app \
  --profile=

步骤4：授予应用程序权限

# Required for MAS MCP proxy to access the app
databricks api patch /api/2.0/permissions/apps/lakebase-mcp-server \
  --json '{"access_control_list":[{"group_name":"users","permission_level":"CAN_USE"}]}' \
  --profile=

步骤5：授予应用程序SP访问Lakebase实例的权限

该应用程序作为服务主体（SP）运行。您需要在它将连接到的每个Lakebase实例上授予此SP访问权限。有两个部分： 创建角色 和 配置安全标签 用于OAuth身份验证。

5a：获取应用程序的服务主体信息

databricks apps get lakebase-mcp-server --profile=

从输出中，注意：

• service_principal_client_id --例如。 ecbb98b7-7186-43cf-ab8d-ac56bffc0f8e （用作PostgreSQL角色名称）
• service_principal_id --例如。 70866217708507 （数字ID，用于安全标签）

5b：对于应用程序将连接到的每个Lakebase实例

重要提示： UI中的实例切换器始终通过生成的OAuth令牌进行连接，即使对于中列出的实例也是如此 app.yaml 资源。这 resources: block只处理应用程序的启动连接；确实如此 不 自动为基于令牌的切换器连接设置角色/安全标签。您必须在应用程序需要切换到的每个实例上运行下面的SQL。

5c：对于每个实例（包括 app.yaml)

如果你想让应用程序切换到Lakebase实例 不 在 app.yaml （通过UI实例切换器），您必须手动创建每个角色、安全标签和授权：

获取正确SQL（预先填充SP值）的最简单方法是调用内置帮助程序：

curl -H "Authorization: Bearer " https:///api/setup-role-sql

复制 sql 从响应中提取字段，并在Lakebase SQL编辑器中运行它。或者，手动构建它：

# Replace these with your values
SP_CLIENT_ID="ecbb98b7-7186-43cf-ab8d-ac56bffc0f8e"   # from step 5a (UUID format)
SP_ID="70866217708507"                                   # from step 5a (integer SCIM ID)
DATABASE="my_database"                                   # target database name
INSTANCE="my-instance"                                   # target instance name
PROFILE="my-profile"                                     # Databricks CLI profile

databricks psql $INSTANCE --profile=$PROFILE -- -c "
-- 1. Create the role (idempotent — skips if exists)
DO \$\$ BEGIN
  CREATE ROLE \"$SP_CLIENT_ID\" WITH LOGIN;
EXCEPTION WHEN duplicate_object THEN NULL;
END \$\$;

-- 2. Configure OAuth security label (required for token auth)
SECURITY LABEL FOR \"databricks_auth\" ON ROLE \"$SP_CLIENT_ID\"
  IS 'id=$SP_ID,type=service_principal';

-- 3. Grant access to the database and schema
GRANT ALL ON DATABASE \"$DATABASE\" TO \"$SP_CLIENT_ID\";
GRANT ALL ON SCHEMA public TO \"$SP_CLIENT_ID\";

-- 4. Grant access to existing tables and sequences
GRANT ALL ON ALL TABLES IN SCHEMA public TO \"$SP_CLIENT_ID\";
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO \"$SP_CLIENT_ID\";

-- 5. Grant access to future tables and sequences
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT ALL ON TABLES TO \"$SP_CLIENT_ID\";
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT ALL ON SEQUENCES TO \"$SP_CLIENT_ID\";
"

谁可以运行这个SQL？ CREATE ROLE 和 SECURITY LABEL 需要PostgreSQL超级用户。在Lakebase中，只有工作区管理员或项目所有者具有超级用户访问权限。以该用户身份登录时，在Lakebase UI中运行SQL。

所有步骤都是必需的：

1. CREATE ROLE ... WITH LOGIN --创建PostgreSQL角色
2. SECURITY LABEL FOR "databricks_auth" --将OAuth令牌映射到角色（没有这个，你会得到 no role security label is configured)
3. GRANT ALL ON DATABASE 和 GRANT ALL ON SCHEMA public --授予数据库级和架构级访问权限（CREATE TABLE和DDL所需）
4. GRANT ALL ON ALL TABLES/SEQUENCES --授予对现有对象的访问权限
5. ALTER DEFAULT PRIVILEGES --授予对其他用户创建的未来对象的访问权限

授予访问权限 全部 实例一次：

SP_CLIENT_ID="ecbb98b7-7186-43cf-ab8d-ac56bffc0f8e"
SP_ID="70866217708507"
DATABASE="my_database"
PROFILE="my-profile"

for INSTANCE in instance-a instance-b instance-c; do
  echo "=== $INSTANCE ==="
  databricks psql $INSTANCE --profile=$PROFILE -- -c "
  DO \$\$ BEGIN
    CREATE ROLE \"$SP_CLIENT_ID\" WITH LOGIN;
  EXCEPTION WHEN duplicate_object THEN NULL;
  END \$\$;
  SECURITY LABEL FOR \"databricks_auth\" ON ROLE \"$SP_CLIENT_ID\"
    IS 'id=$SP_ID,type=service_principal';
  GRANT ALL ON DATABASE \"$DATABASE\" TO \"$SP_CLIENT_ID\";
  GRANT ALL ON SCHEMA public TO \"$SP_CLIENT_ID\";
  GRANT ALL ON ALL TABLES IN SCHEMA public TO \"$SP_CLIENT_ID\";
  GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO \"$SP_CLIENT_ID\";
  ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO \"$SP_CLIENT_ID\";
  ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO \"$SP_CLIENT_ID\";
  "
done

步骤6：验证

curl https:///health
# {"status":"ok","lakebase":true}

curl https:///api/tools | python3 -c "import sys,json; print(len(json.load(sys.stdin)), 'tools')"
# 33 tools

访问 https:/// 对于web UI。

连接到MAS

部署后，此MCP服务器可供 多代理主管（MAS） 作为代理工作流的一部分读取和写入Lakebase表。

步骤1：创建UC HTTP连接

在您的copula工作区中：

1. 首选 目录>外部连接>创建连接
2. 连接类型： 超文本传输协议
3. 配置：

- 主机: ` （例如。 lakebase-mcp-server-1234567890.aws.databricksapps.com) - **端口**: 443 - **基础路径**: /mcp/ - **身份验证类型**：Databricks OAuth M2M - **客户端ID**：服务主体应用程序ID - **客户端密钥**：SP OAuth密钥（创建于 **帐户控制台>应用程序连接**) - **OAuth作用域**: all-apis`

步骤2：将外部MCP服务器代理添加到MAS

在MAS Supervisor配置中：

1. 点击 添加代理>外部MCP服务器
2. 从步骤1中选择UC HTTP连接
3. 设置代理描述（这是主管用于路由的描述）：

> 执行Lakebase数据库操作——读写操作表，包括库存、发货、订单和供应链数据

1. 点击 重新发现工具 --监督员将检测所有33个MCP工具

步骤3：测试

在MAS游乐场，尝试：

• “数据库中有哪些表？”
• “显示订单表中的前10行”
• “在笔记表中插入新记录”
• 创建一个名为alerts的表，其中包含以下列：id、严重性、消息、created_at
• “准备迁移以向订单表添加状态列”

主管将把这些请求发送给Lakebase MCP代理，后者将根据您的数据库执行这些请求并返回结构化结果。

MAS代理描述提示

代理描述决定了主管何时将请求路由到此代理。请具体说明您的Lakebase中有哪些数据：

# Generic (works but less precise routing)
"Read and write to the Lakebase operational database"

# Specific (better routing for supply chain use case)
"Execute database operations on supply chain tables: inventory_levels, shipments,
purchase_orders, demand_forecasts, routes, warehouses, notes. Supports reads, writes,
DDL, transactions, query analysis, safe migrations, query tuning, and data quality profiling."

多数据库路由

单个部署的MCP服务器可以为同一Lakebase实例上的多个数据库提供服务。每个数据库都有自己的URL命名空间，不需要重新部署。

URL模式

运作原理

• 每个请求的ContextVar范围 --每一个请求 /db/{database}/mcp/ 设置a ContextVar 使用目标数据库名称。所有工具处理程序都从该变量读取，因此对不同数据库的并发请求是完全隔离的。
• 每个数据库连接池的延迟 --池是在首次向数据库发出请求时创建的，并在之后重复使用。令牌刷新适用于所有池。
• 向后兼容 — /mcp/ 继续使用来自的默认数据库 PGDATABASE 或 LAKEBASE_DATABASE现有的MAS连接不需要改变。

示例：两个演示共享一个服务器

部署一个Lakebase MCP Server应用程序，然后为每个演示创建单独的UC HTTP连接：

每个MAS主管都连接到同一个应用程序URL，但使用不同的URL base_path。服务器根据需要为每个数据库创建隔离的连接池。

MCP工具（33）

所有工具均包含MCP注释(readOnlyHint, destructiveHint, idempotentHint)因此，客户端可以在破坏性操作之前显示安全警告。

架构检查（READ）

数据操作（读/写）

通用SQL

数据定义语言

演出

基础设施管理（INFRA）

分行管理（Branch）

自动缩放配置（SCALE）

数据质量（Quality）

安全移民

两阶段迁移工作流程：首先验证，然后应用或丢弃。

用途：

1. Call prepare_database_migration(migration_sql="ALTER TABLE orders ADD COLUMN status TEXT DEFAULT 'pending'")
   → Returns: migration_id, validation results, tables affected
2. Review the results
3. Call complete_database_migration(migration_id="abc123", apply_changes=true)
   → Applies the migration for real

查询调优（Tuning）

两阶段查询调优：首先分析和建议索引，然后应用或丢弃。

用途：

1. Call prepare_query_tuning(sql="SELECT * FROM orders WHERE customer_id = 42")
   → Returns: tuning_id, execution plan, suggestions (e.g. "add index on customer_id")
2. Review suggestions
3. Call complete_query_tuning(tuning_id="xyz789", apply_changes=true, ddl_statements=["CREATE INDEX idx_orders_customer ON orders(customer_id)"])
   → Applies the index and shows the improved execution plan

探索（EXPLORE）

MCP资源（2）

MCP提示（3）

网页用户界面

根URL(/)提供一个Neon.tech风格的单页应用程序，带有固定的侧边栏导航：

数据库

• 数据库浏览器 --浏览表、查看列模式和约束、示例数据
• SQL查询 --使用表格结果运行只读查询（按Ctrl/Cmd+Enter执行）
• MCP工具 --按类型分类的工具参考卡+所有33种工具的互动游乐场

基础设施

• 项目 --Lakebase项目的卡片网格，带有状态徽章和分支机构数量
• 分支 --具有创建/删除操作的分支管理表
• 端点 --具有自动缩放CU滑块和缩放到零配置的端点卡

质量

• 分析器 --具有列级统计信息的表选择器：null、distinct、min/max、avg

参考

• 文档 -部署指南、MAS连接说明、REST API参考

侧边栏包括 实例切换器 （在所有Lakebase实例之间切换），a 数据库切换器 下拉菜单和实时连接状态指示器。

REST API（29个以上端点）

核心

实例和数据库管理

表格

数据运营

基础设施管理

数据质量

设置

跨演示重复使用

此服务器是完全通用的。要将其指向另一个Lakebase数据库：

1. 已配置：更改 instance_name 和 database_name 在 app.yaml
2. 自动缩放：更改 LAKEBASE_PROJECT / LAKEBASE_DATABASE 环境变量
3. 多实例：添加多个 resources 在 app.yaml，或在其他实例上授予应用程序SP（请参阅 步骤5)

无需更改代码。web用户界面、MCP工具和REST API可用于任何Lakebase数据库。

本地开发

配置模式

export PGHOST=instance-.database.cloud.databricks.com
export PGPORT=5432
export PGDATABASE=my_database
export PGUSER=
export PGSSLMODE=require

pip install -r app/requirements.txt
python app/mcp_server.py

自动缩放模式

export LAKEBASE_PROJECT=b10eb92b-dc0e-4ccf-ba26-0653c5e7ebec   # project UUID (from URL)
export LAKEBASE_BRANCH=br-cool-haze-d2hbxj2m                    # branch ID (not display name)
export LAKEBASE_DATABASE=my_db

pip install -r app/requirements.txt
python app/mcp_server.py

服务器在端口8000上启动。MCP端点： http://localhost:8000/mcp/.Web用户界面： http://localhost:8000/.

已知的戈查斯

1. 尾部斜杠：MCP端点位于 /mcp/ （带尾随斜线）。 /mcp 自动重定向。
2. MAS发送JSON字符串：MAS代理将嵌套对象序列化为JSON字符串。由自动处理 _ensure_dict() 和 _ensure_list().
3. 表权限：通过创建的表 databricks psql 由用户拥有。创建表后，授予对应用程序服务主体的访问权限。
4. 用于UC连接的OAuth M2M：必须在以下位置创建SP OAuth机密 帐户控制台 级别，而不是通过工作区API。
5. CAN_USE用于用户组：MAS MCP代理需要 CAN_USE 在应用程序上。授予 users 集团。
6. 自动缩放到零：如果自动缩放端点被挂起，则在计算唤醒时，第一个请求可能需要2-5秒。
7. 数据库切换器：切换数据库会重新初始化连接池。表缓存将自动清除。
8. 实例切换器——所有实例都需要角色+安全标签：切换器通过生成的OAuth令牌连接，即使对于以下实例也是如此 app.yaml 资源。这 resources: block只处理启动；它不会自动配置基于令牌的切换的角色/安全标签。跑吧 CREATE ROLE + SECURITY LABEL + GRANT SQL（参见 步骤5c)在应用程序将切换到的每个实例上。如果没有安全标签： no role security label is configured.
9. 迁移状态过期：如果未完成，准备好的迁移/调优会话将在1小时后过期。呼叫 prepare_* 再次创建新会话。

环境变量

许可证

麻省理工学院