Databricks MCP Servers (Official)

什么是 Databricks MCP Servers (Official)？

Databricks MCP Servers (Official) 是 Databricks 在 system.ai schema 中提供的 MCP 服务器：一组托管端点，让 Claude、Cursor、Codex 等智能体通过 Genie One 或 SQL 查询你的 Databricks 数据，并调用 GitHub、Slack 等服务。

你无需自行托管任何东西。每个 Databricks MCP 服务器都是通过 Unity Gateway 调用的 Unity Catalog 安全对象（securable），因此每次调用都会强制执行 Unity Catalog 权限，管理员可以通过授权（grants）和策略（policies）管理访问。这些服务器在 AWS、Azure 和 GCP 上的 Databricks 均有文档。

如何使用 Databricks MCP Servers (Official)？

所有 system.ai MCP 都使用同一个 URL 格式：

https://<workspace-hostname>/ai-gateway/mcp-services/<mcp-name>

将 <workspace-hostname> 替换为你的工作区主机名（不含 https:// 和路径），将 <mcp-name> 替换为完整名称，例如 system.ai.genie_one_mcp 或 system.ai.dbsql。要查看名称，请在工作区中打开 Unity Gateway > MCPs。

前提条件：

• 一个 Databricks 工作区，以及调用该 MCP 的权限。
• 使用 system.ai.dbsql、system.ai.sandbox 和 system.ai.web_search 时，需要账户管理员在账户控制台的 Previews 页面启用 Unity Gateway beta。Genie One MCP 已正式发布（GA）。
• 认证：推荐使用带 ai-gateway scope 的 OAuth。本地测试时，也可以在 Authorization: Bearer <token> 请求头中使用个人访问令牌（personal access token）。

对于编码智能体，Databricks 推荐使用 Unity Gateway CLI（ug，需要 Python 3.12+ 和 uv），它会处理登录和令牌刷新：

uv tool install git+https://github.com/databricks/unity-gateway
ug mcp add --names system.ai.genie_one_mcp,system.ai.dbsql

省略 --names 可在选择器中挑选服务器。ug mcp list 显示已有连接，ug mcp remove 用于移除连接。

Claude Code

使用 ug：ug mcp add --agents claude --names system.ai.github，然后用 ug claude 重启。手动配置时，可使用 Databricks 内置的 OAuth 客户端：

claude mcp add --transport http --scope user \
  --client-id claude-code --callback-port 3118 \
  databricks-tools \
  "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>"

然后在 Claude Code 中输入 /mcp，用你的 Databricks 账号登录。

Claude Desktop

如果在网页版或桌面版 Claude 中使用自己的 Claude 账号，需要账户管理员创建一个带 ai-gateway scope 的 OAuth 客户端，并注册重定向 URL https://claude.ai/api/mcp/auth_callback 和 https://claude.com/api/mcp/auth_callback。然后打开 Settings > Connectors > Add custom connector，输入 MCP URL 和客户端 ID 并登录。若要用令牌进行本地测试，Databricks 文档给出了如下 claude_desktop_config.json 配置（需要 Node.js）：

{
  "mcpServers": {
    "databricks-tools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>",
        "--header",
        "Authorization: Bearer <databricks-pat>"
      ]
    }
  }
}

Cursor

运行 ug mcp add --agents cursor，它会写入 ~/.cursor/mcp.json。若要基于令牌进行本地测试，将以下内容合并到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "dbsql": {
      "url": "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql",
      "headers": { "Authorization": "Bearer <databricks-pat>" }
    }
  }
}

Codex

运行 ug mcp add --agents codex --names <catalog>.<schema>.<service>，或手动用 codex mcp add databricks-tools --url "<mcp-url>" --oauth-client-id <client-id> 注册，再用 codex mcp login databricks-tools --scopes ai-gateway,offline_access 登录。

要检查任一客户端，可让它通过 system.ai.dbsql 运行 SELECT 1 AS result，并确认它确实发起了工具调用。

Databricks MCP Servers (Official) 的主要功能

• 官方出品、由 Databricks 托管：无需部署或维护服务器
• 所有 system.ai MCP 都通过 Unity Gateway 使用同一个 URL 格式
• 每次请求都强制执行 Unity Catalog 权限，并在 Unity Gateway 中提供授权、策略和追踪
• Genie One MCP（GA）基于 Genie Ontology（你受治理的语义层）回答自然语言问题
• Databricks SQL MCP 在 SQL warehouse 上运行确切的 SQL；可通过 system.ai.dbsql_policy 中的 disallow_writes 设为只读
• 面向外部服务的 MCP：Slack、GitHub、Atlassian、Google Drive、Google Calendar、Gmail 和 Microsoft 365
• 提供 Claude Code、Claude Desktop、Codex、Cursor、ChatGPT、Windsurf 和 Replit 的配置指南

Databricks MCP Servers (Official) 工具

可用工具取决于你连接的服务器：

• Genie One（system.ai.genie_one_mcp）： genie_ask 针对自然语言问题开始生成回答，genie_poll_response 获取进度和最终答案，genie_get_query_result 返回完整的 SQL 结果，genie_cancel_response 取消一轮对话，view_ask 在支持 MCP Apps 的客户端中打开交互式 View。
• Databricks SQL（system.ai.dbsql）： execute_sql 工具运行你或智能体编写的查询。查询异步执行，过大的结果会被截断。
• 网页搜索和沙箱： system.ai.web_search 返回带引用的综合答案；system.ai.sandbox 在隔离环境中运行 Python、SQL 或 shell 代码，且没有出站网络访问。
• 外部服务： system.ai.slack、system.ai.github、system.ai.atlassian、system.ai.google_drive、system.ai.google_calendar、system.ai.gmail 和 system.ai.microsoft_365 通过 OAuth 连接到各自的服务商。

Databricks MCP Servers (Official) 的使用场景

• 在对话中做业务分析：“上个季度各地区的收入是多少？”由 Genie One 回答，并附带指向数据来源的链接。
• 在编码智能体中做数据工程：“检查 main.sales.orders 的 schema，并验证这段 SQL”，使用 Databricks SQL MCP。
• 跨工具协作：“找到关于失败作业的那个未关闭 GitHub issue”，通过 system.ai.github 完成。
• 面向团队的受治理智能体：由管理员集中限制工具并应用策略。

Databricks MCP Servers (Official) 与替代方案对比

旧版工作区端点。 较早的托管端点，例如 https://<workspace-hostname>/api/2.0/mcp/sql、/api/2.0/mcp/genie/{genie_space_id}、/api/2.0/mcp/ai-search/{catalog}/{schema}/{index_name} 和 /api/2.0/mcp/functions/{catalog}/{schema}/{function_name} 仍可使用，但它们绕过 Unity Gateway，因此没有 MCP 级别的授权、策略和追踪。Databricks 表示，beta 版 Genie 端点 https://<workspace-hostname>/api/2.0/mcp/genie 已弃用，并将于 2026 年 10 月 31 日下线。

databrickslabs/mcp。 Databricks Labs 的开源 Unity Catalog 服务器已弃用，其 README 建议改用托管服务器。

社区服务器。 也有自托管、基于令牌的方案，例如 Databricks MCP Server by RafaelCartenet，它侧重于 Unity Catalog 元数据、数据血缘和 SQL。这些项目并非由 Databricks 维护。

你也可以在 Unity Gateway 中注册外部 MCP 服务器，或在 Databricks Apps 上构建自定义服务器。

Databricks MCP Servers (Official) 常见问题排查

• 看不到 system.ai.dbsql 或 system.ai.sandbox： 需要账户管理员启用 Unity Gateway beta。
• 工具要求你登录： 对于外部服务，打开返回的登录链接，授权该服务商后重试。工作区登录和服务商登录是两个独立步骤。
• OAuth 重定向不匹配： 注册的重定向 URL 必须与客户端的回调主机和端口一致。OAuth 应用的变更最多可能需要 30 分钟生效。Databricks 端点不支持动态客户端注册（dynamic client registration），请使用预先配置的客户端 ID。
• 托管客户端无法连接： 如果启用了 IP 访问列表，需要放行服务商的出站 IP（例如 Claude 或 ChatGPT 的），而不仅是你自己的网络。
• Claude Code 通过 ug 无法连接： 运行 ug doctor。