將非 Databricks 用戶端連線到 Databricks MCP 伺服器

Important

這項功能位於測試版 (Beta) 中。工作區管理員可以從 「預覽 」頁面控制對此功能的存取。請參閱管理 Azure Databricks 預覽。

將支援模型內容通訊協定（MCP）的非 Databricks （外部）用戶端、AI 助理和 IDE 連線到 Databricks MCP 伺服器。這可讓您直接在開發環境中存取 Databricks 資料和工具。

藉由將外部用戶端連線到 Databricks MCP 伺服器，您可以：

從您的 IDE 或 AI 助理存取 Unity 目錄函式、資料表和向量索引
直接從 Claude、游標、Replit 或其他支援 MCP 的工具查詢 Databricks 資料

Prerequisites

伺服器網址：取得你想使用的 Databricks MCP 伺服器所需的適當伺服器網址：
資源存取：確認你能存取你想使用的 MCP 伺服器及任何底層資源。例如，如果你使用 Genie 管理的 MCP 伺服器，你需要存取底層的 Genie 空間。
網路存取：如果你的 Databricks 工作區有 IP 存取限制，請將客戶端的出站 IP 位址加入允許清單，使其能連接到你的工作區：
- 請參考工作空間 IP 存取清單和帳戶 IP 存取清單的文件，檢查是否有任何限制
- 如果啟用了 IP 存取清單，請識別客戶端的出站 IP。這些資訊通常可在客戶文件中找到;例如，Claude 會在此記錄其出站 IP 位址。
- 確保你客戶的外撥 IP 也被加入清單。

身份驗證方法

選擇最適合您安全需求的身份驗證方法：

方法	託管/外部 MCP	自訂 MCP	安全等級	適用對象
OAuth（推薦）	支持	支持	範圍限定的高級許可權、自動令牌更新	生產用途、團隊環境、長期存取
個人存取令牌	支持	不支援	中等 - 權杖型存取，具有到期時間	個人發展、測試、短期存取

使用 OAuth 認證連接客戶端

OAuth 提供安全認證，具備有範圍的權限及自動憑證更新。

備註

Databricks MCP 伺服器支援 MCP 授權規格的兩種用戶端類型：

公用用戶端：不需要用戶端密碼
機密用戶端：包含用戶端密碼

取得你客戶的 OAuth 轉址網址

每個 MCP 用戶端都需要特定的 OAuth 重定向 URL 來進行認證回撥。常見的重定向網址模式包括：

網頁用戶端：https://<domain>/oauth/callback或https://<domain>/api/mcp/auth_callback
在地開發工具： http://localhost:<port>/oauth/callback

請查閱客戶文件，找出所需的精確重定向網址。

建立 Databricks OAuth 應用程式

請帳號管理員建立一個 Databricks OAuth 應用程式。取得它的客戶端識別碼，如果客戶端需要，則取得客戶端密碼。

基於使用者介面（Account Console）

使用帳號主控台建立 Databricks OAuth 應用程式：

在 Databricks 帳號主控台，點到設定>、應用程式連線、>新增連線。
設定應用程式設定：
- 名稱：為您的 OAuth 申請輸入描述性名稱（例如，claude-mcp-client，） mcp-inspector
- 重定向網址：新增外部客戶所需的重定向網址
- 用戶端類型：對於公開用戶端（瀏覽器端、行動端），請取消勾選 產生用戶端秘密。對於機密客戶端（伺服器端），請持續檢查。
- 範圍：配置 API 範圍（詳見下方配置 OAuth 範圍）
- 令牌到期：設定適當的令牌存取與刷新時間

CLI

使用 Databricks CLI 建立 Databricks OAuth 應用程式：

databricks account custom-app-integration create --json '{
  "name": "mcp-oauth-client",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

用你客戶的實際轉址網址替換 <your-client-redirect-url> 。

設定 OAuth 範圍

OAuth 範圍控制客戶端可存取哪些 Databricks API。在大多數的使用案例中，使用all-apis範圍，它允許存取所有的Databricks API，並且是最簡單的選擇。

若需更細緻的控制，您可以指定 MCP 特定的範圍，而不是使用 all-apis：

MCP 伺服器類型	所需範圍
MCP 精靈空間	`mcp.genie`
MCP Unity 目錄功能	`mcp.functions`
MCP 向量搜尋	`mcp.vectorsearch`
MCP Databricks SQL	`mcp.sql`、`sql.warehouses`、`sql.statement-execution`
MCP 外部功能	`mcp.external`

欲了解更多關於宣告 REST API 範圍及與代理程式共用的資訊，請參閱記錄代理時宣告 REST API 範圍。

設定網路存取（可選）

如果你的 Databricks 工作區有 IP 存取限制，請將客戶端的出站 IP 位址加入工作區的允許清單。否則，工作區會阻擋來自客戶端的認證請求。請參閱管理 IP 存取清單。

設定您的用戶端

在 Databricks 建立 OAuth 應用程式後，請用 OAuth 憑證設定你的特定 MCP 用戶端。每個用戶端都有自己的設定方式。請參閱以下平台特定範例，了解熱門 MCP 用戶端的詳細說明。

OAuth 範例

以下範例說明如何配置特定 MCP 用戶端與 OAuth 認證。先依照前一節的通用 OAuth 設定步驟操作，然後用這些範例來設定你特定的客戶端。

MCP檢查員

MCP 檢查器是用於測試和調試 MCP 伺服器的開發人員工具。

MCP 檢查器

請依照上述 OAuth 認證設定，搭配以下 Inspector 專用設定：

重新導向網址：
- http://localhost:6274/oauth/callback
- http://localhost:6274/oauth/callback/debug
用戶端類型：公用（取消勾選 產生用戶端密碼）

設定 MCP 檢查器：

執行檢查器： npx @modelcontextprotocol/inspector
將 運輸類型 設為 Streamable HTTP。
輸入你的 Databricks MCP 伺服器網址。
在認證區塊，新增你的 OAuth 用戶端 ID。
點選 開啟認證設定 ，選擇引導式或快速流程。
成功認證後，將存取權杖貼上至 Bearer Token 的 API 令牌認證 區塊。
按一下 [ 連接]。

MCP 檢查員認證流程

Claude 連接器

使用 Claude 連接器與遠端 MCP 來連接 Databricks 的管理型及外部 MCP 伺服器。

請依照上述 OAuth 認證設定，搭配以下 Claude 專屬設定：

重新導向網址： https://claude.ai/api/mcp/auth_callback 以及 https://claude.com/api/mcp/auth_callback
IP 允許清單（如有需要）：新增 Claude 的出站 IP 位址

設定 Claude：

請前往 Claude 的 設定 >連接器頁面。
點擊 新增自訂連接器。
輸入你的 Databricks MCP 伺服器網址。
輸入你的 OAuth 應用程式的客戶端 ID。
按一下 [新增 ] 以完成。

在 Claude 中設定連接器

ChatGPT 應用程式

利用自訂 ChatGPT 應用程式（具備開發者模式）和完整 MCP 應用程式，將 ChatGPT 連接到 Databricks 管理及外部 MCP 伺服器。

新增自訂 ChatGPT 應用程式需要：

開發者模式已開啟
ChatGPT 商業、企業或教育工作空間

請依照上述的 OAuth 認證設定，並應用這些專為 ChatGPT 設計的設定：

重新導向網址： https://chatgpt.com/connector_platform_oauth_redirect
IP 允許清單：新增 ChatGPT 的出站 IP 位址

設定 ChatGPT：

在 ChatGPT 裡，請前往設定>應用程式>創建應用程式。
輸入你的 Databricks MCP 伺服器網址。
使用 OAuth 作為認證方法。
輸入你的 OAuth 應用程式的客戶端 ID 和秘密（如適用）。
完成設定並儲存你的應用程式。

自訂的 ChatGPT 應用程式不支援配置為私有連結前端或後端的 Azure 工作空間。

游標/風浪板

若要安全地將本地 IDE 如 Cursor 或 Windsurf 連接到 Databricks MCP 伺服器，請使用 mcp-remote OAuth。依照 mcp-remote repo 的指示設定 mcp-remote。接著依照 OAuth 認證設定，確保你的 OAuth 設定正確。

設定游標或風帆：

找到你的 MCP 設定檔：
- 游標： ~/.cursor/mcp.json
- 風帆衝浪： ~/.codeium/windsurf/mcp_config.json

在你的設定檔中，新增你的 MCP 伺服器：

對於機密 OAuth 用戶端 （用戶端秘密）：

{
  "mcpServers": {
    "databricks-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
        "--static-oauth-client-info",
        "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
      ]
    }
  }
}

對於公開的 OAuth 用戶端 （不含用戶端秘密）：

{
  "mcpServers": {
    "databricks-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
        "--static-oauth-client-info",
        "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\" }"
      ]
    }
  }
}

替換 <your-workspace-hostname> 成你的 Databricks 工作空間主機名稱。
用你的 OAuth 客戶端 ID 設定環境變數 MCP_REMOTE_CLIENT_ID 。對於機密客戶，還需要將 MCP_REMOTE_CLIENT_SECRET 設定為你的客戶密鑰。

使用個人存取權杖（PAT）認證連接用戶端

個人存取權杖提供一種更簡單的認證方法，適合個人開發、測試及短期存取 Databricks MCP 伺服器。

備註

個人存取權杖僅支援於受管理及外部 MCP 伺服器。自訂 MCP 伺服器需要 OAuth 認證。

在您的 Databricks 工作區產生個人存取權杖。請參閱使用 Azure Databricks 個人存取權杖（舊版）進行驗證。
設定網路存取（可選）。

如果你的 Databricks 工作區有 IP 存取限制，請將客戶端的出站 IP 位址加入允許清單。請參考客戶文件或部署環境的網路設定，取得所需的 IP 位址。
設定你的客戶端。

產生 PAT 後，設定 MCP 用戶端使用它來進行驗證。每個用戶端都有自己的設定方式。請參閱下方平台專屬範例，了解熱門 MCP 客戶端的詳細說明。

PAT 範例

以下範例說明如何配置特定 MCP 用戶端的個人存取權杖認證。先依照上述 PAT 認證設定，然後用這些範例來設定你的特定客戶端。

Cursor

Cursor 透過其設定組態支援MCP。

打開你的游標設定。

新增以下設定（調整你選擇的 MCP 伺服器網址）：

{
  "mcpServers": {
    "uc-function-mcp": {
      "type": "streamable-http",
      "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      },
      "note": "Databricks UC function"
    }
  }
}

替換 <your-workspace-hostname> 成你的 Databricks 工作空間主機名稱。
將<YOUR_TOKEN>換成你的個人存取權憑證。

Claude 桌面版

Claude Desktop 可透過 mcp-remote 連接 Databricks MCP 伺服器。

找到你的 claude_desktop_config.json 檔案：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows： %APPDATA%\Claude\claude_desktop_config.json

新增以下設定（調整你選擇的 MCP 伺服器網址）：

{
  "mcpServers": {
    "uc-function-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
        "--header",
        "Authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}

替換 <your-workspace-hostname> 成你的 Databricks 工作空間主機名稱。
將<YOUR_TOKEN>換成你的個人存取權憑證。
重新啟動 Claude Desktop 變更才能生效。

Replit（雷普利特）

Replit 支援透過自訂的 MCP 伺服器設定連接 Databricks MCP 伺服器。

在你的 Replit 工作區，點選 新增 MCP 伺服器。

輸入你的 Databricks MCP 伺服器網址，例如：

https://<your-workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}

新增自訂標頭：
- 金鑰：Authorization
- 值：Bearer <YOUR_TOKEN>

請參閱 Replit MCP 文件。

連線問題疑難排解

請依照以下故障排除步驟診斷並解決常見的連線問題。

驗證認證

在測試連線前，請確認你的認證憑證設定正確。

服務主體（M2M）

若要使用機器對機器（M2M）OAuth 進行服務主體認證，請使用 Databricks CLI 測試您的憑證。

DATABRICKS_CLIENT_ID=<your-client-id> DATABRICKS_CLIENT_SECRET=<your-client-secret> databricks auth describe

此指令會驗證您的服務主體設定，並顯示已認證身份的資訊。如果指令回傳錯誤，請檢視你的服務主體設定並確保：

服務主體已在您的 Databricks 帳戶中建立
客戶端 ID 和客戶端秘密設定正確
服務主體擁有適當的權限來存取所需資源

OAuth 用戶對機器（U2M）

對於 OAuth 使用者對機器（U2M）認證，請使用 MCP Inspector 測試連線。 OAuth 流程在連線過程中驗證憑證。

驗證網路配置

網路限制可能會阻止外部用戶端連接到你的 Databricks 工作區。確保任何 Databricks 的 IP 存取清單政策都已設定，允許你的客戶端連接到你的 Databricks 帳號和工作區。請參閱必要條件。

向 Databricks 支援回報問題

如果你完成以下故障排除步驟後仍遇到連線問題：

檢查你 MCP 用戶端（Claude、游標、MCP Inspector 等）的日誌，看看有沒有錯誤訊息和堆疊追蹤。
收集以下診斷資訊：
- 所使用的認證方法（OAuth 或 PAT）
- MCP 伺服器網址
- 用戶端的錯誤訊息
- 網路設定細節（IP 限制、防火牆規則）
聯絡客服並分享診斷資訊以解決問題。

局限性

動態用戶端註冊：Databricks 不支援受控、外部或自訂 MCP 伺服器的動態用戶端註冊 OAuth 流程。不支援使用 OAuth 驗證強制執行動態用戶端註冊的外部用戶端和 IDE。
自訂 MCP 伺服器個人存取權杖支援：裝載在 Databricks Apps 上的自訂 MCP 伺服器不支援個人存取權杖進行驗證。
代表授權：裝載於 Databricks Apps 上的自訂 MCP 伺服器不支援代表使用者授權。

後續步驟

使用受控 MCP 伺服器將代理程式連線到 Unity 目錄資料
使用外部MCP伺服器存取第三方服務
託管組織特定工具的自訂 MCP 伺服器

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-17