メインコンテンツまでスキップ

Databricks SQL MCP サーバー

Databricks SQL MCP サーバーを使用すると、Unity Catalog の権限によってアクセスが管理された状態で、エージェントが Unity Catalog テーブルに対して AI 生成 SQL をランし、データの読み取りと書き込みを行うことができます。クエリーは非同期で実行されます。エージェントがツールを呼び出してクエリーを起動し、応答が完了するまでポーリングを行います。

備考

ベータ版

system.ai.dbsql、system.ai.sandboxおよびsystem.ai.web_searchはベータ版です。これらを使用するには、アカウント管理者がアカウントコンソールの プレビュー ページから 拡張 Unity ゲートウェイ プレビューを有効にする必要があります。Unity Gateway自体は一般提供されています。アカウントプレビューの管理をご覧ください。

ベータ版が有効になっていない場合、system.ai.dbsql の呼び出しは The MCP service is administratively suspended. (HTTP 400) を返します。代わりに ワークスペースEndpoint /api/2.0/mcp/sql を使用します。

このサーバーは、開発およびデータエンジニアリングに使用します。ユーザーやコーディングエージェントが作成した特定のクエリーの実行、スキーマの検査、SQL構文の検証、AIコーディングツールからのデータパイプラインの作成などを行います。これにより、実行される正確なSQLを確定的に制御できます。

MCPでは、defaultで読み取りと書き込みが許可されます。読み取り専用にするには、組み込みの system.ai.dbsql_policy ポリシーで disallow_writes を true に設定します。ポリシーの適用を参照してください。

Genie One MCP と Databricks SQL MCP サーバー​

自然言語で質問されるビジネス上の質問に対して、Databricksでは Genie One MCP server の使用をお勧めします。Genieは、管理対象のセマンティックレイヤーであるGenie Ontologyを通じてビジネス用語を解決します。これにより、エージェントが生のテーブルに対して直接SQLを記述するよりも、正確な回答が得られます。

構文の検証やパイプラインの作成など、自分またはコーディングエージェントが記述した特定のクエリーを実行する必要がある場合は、Databricks SQL MCP サーバーを使用します。

単一のキュレーションされた Genie Agent にスコープ設定された質問をするには、Genie Agent MCP サーバーを使用します。3つのすべてのサーバーの比較については、「 Genie One、Genie Agent、および Databricks SQL MCP サーバーから選択する」を参照してください。

エージェントを接続する​

コーディングエージェントのセットアップガイドまたは PythonエージェントのセットアップでこのURLを使用します。

URL パターン

OAuthスコープ

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

ai-gateway

URL パターン

OAuthスコープ

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

ai-gateway

SELECT 1 AS resultランするようにエージェントに依頼します。MCPツールを呼び出し、1が返されることを確認します。

ツール​

Databricks SQL MCPサーバーは、次のツールを提供します。

ツール

引数

説明

execute_sql

query

データを書き込む文を含め、SQL文をランします。サーバーポリシーで disallow_writes が true の場合、書き込みはブロックされます。

execute_sql_read_only

query

SELECT、SHOW、DESCRIBE などの読み取り専用 SQL ステートメントをランします。

poll_sql_result

statement_id

execute_sqlまたはexecute_sql_read_onlyが起動したステートメントの現在の状態と結果を返します。

ツール

引数

説明

execute_sql

query

データを書き込む文を含め、SQL文をランします。サーバーポリシーで disallow_writes が true の場合、書き込みはブロックされます。

execute_sql_read_only

query

SELECT、SHOW、DESCRIBE などの読み取り専用 SQL ステートメントをランします。

poll_sql_result

statement_id

execute_sqlまたはexecute_sql_read_onlyが起動したステートメントの現在の状態と結果を返します。

各ツールは、 statement_id および status.state を含む JSON テキストを返します。状態が SUCCEEDED の場合、行は result.data_typed_array にあります。

_metaパラメーター​

_meta パラメーターとは、ツール呼び出し時に LLM が動的に生成するのではなく、MCP サーバーの動作を決定論的に設定するためにエージェントコード内で事前設定する構成値のことです。Databricks SQL MCP サーバーでは、次の_metaパラメーターがサポートされています。

パラメーター名

Type

説明

warehouse_id

str

クエリーを実行するために使用するSQLウェアハウスのID。

例: "a1b2c3d4e5f67890"

指定されていない場合、システムはリソースとアクセス許可に基づいてwarehouseを自動的に選択します。

パラメーター名

Type

説明

warehouse_id

str

クエリーを実行するために使用するSQLウェアハウスのID。

例: "a1b2c3d4e5f67890"

指定されていない場合、システムはリソースとアクセス許可に基づいてwarehouseを自動的に選択します。

例:Databricks SQLクエリーのSQL Warehouseを指定する​

この例では、warehouse_id _metaパラメーターを使用して、公式の Python MCP SDK を使用して Databricks SQL MCP サーバーからクエリーを実行する SQL Warehouse を指定する方法を示します。

このシナリオでは、次のことを行います:

  • システムが自動的に選択するのではなく、特定のSQLウェアハウスを使用してクエリーをランします
  • クエリーを専用のwarehouseにルーティングして、一貫したパフォーマンスを確認する

この例をランするには、マネージド MCP 開発用に Python 環境をセットアップしてください:

Bash
pip install --upgrade databricks-mcp databricks-sdk "mcp>=1.24,<2"

SQLウェアハウス ID を確認するには、「SQLウェアハウスへの接続」を参照してください。

Python
# Import required libraries for MCP client and Databricks authentication
import asyncio
import json
from databricks.sdk import WorkspaceClient
from databricks_mcp.oauth_provider import DatabricksOAuthClientProvider
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.types import CallToolRequest, CallToolResult

async def run_dbsql_tool_call_with_meta():
# Initialize Databricks workspace client for authentication
workspace_client = WorkspaceClient()

# Construct the MCP server URL for DBSQL
# Replace <workspace-hostname> with your workspace hostname
mcp_server_url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"

# Establish connection to the MCP server with OAuth authentication
async with streamablehttp_client(
url=mcp_server_url,
auth=DatabricksOAuthClientProvider(workspace_client),
) as (read_stream, write_stream, _):

# Create an MCP session for making tool calls
async with ClientSession(read_stream, write_stream) as session:
# Initialize the session before making requests
await session.initialize()

# Create the tool call request with warehouse_id in _meta
request = CallToolRequest(
method="tools/call",
params={
# Tool name for executing SQL queries
"name": "execute_sql",

# Dynamic arguments - typically provided by your AI agent
"arguments": {
"query": "SELECT * FROM my_catalog.my_schema.my_table LIMIT 10"
},

# Meta parameters - specify which warehouse to use
"_meta": {
"warehouse_id": "a1b2c3d4e5f67890" # Your SQL warehouse ID
}
}
)

# Send the request and parse the JSON text in the response
response = await session.send_request(request, CallToolResult)
result = json.loads(response.content[0].text)

# Poll until the statement leaves the PENDING or RUNNING state
while result["status"]["state"] in ("PENDING", "RUNNING"):
await asyncio.sleep(1)
poll_request = CallToolRequest(
method="tools/call",
params={
"name": "poll_sql_result",
"arguments": {"statement_id": result["statement_id"]},
}
)
response = await session.send_request(poll_request, CallToolResult)
result = json.loads(response.content[0].text)

if result["status"]["state"] != "SUCCEEDED":
raise RuntimeError(f"Query ended in state {result['status']['state']}: {result}")

# The rows are in result.data_typed_array
return result["result"]["data_typed_array"]

# Execute the async function and get the rows
rows = asyncio.run(run_dbsql_tool_call_with_meta())
print(rows)

FAILED と CANCELED は終了状態であるため、この例ではポーリングを停止してエラーを発生させます。

制限事項​

  • セマンティックコンテキストがありません。 サーバーは、与えられたSQLを実行します。ビジネス用語、メトリクス定義、テーブル関係を解決しないため、エージェントはスキーマのみからそれらを推論する必要があります。自然言語でアナリティクスの質問をする場合は、Genie One MCPサーバーを使用してください。これにより、Genie Ontologyに基づいて回答が生成されます。
  • 結果サイズ。 サーバーは、モデルのコンテキストウィンドウの枯渇を防ぐため、ツール応答内の大きな結果セットを切り捨てます。結果を制限内に収めるには、返す行数と列数を減らすか、SQLで集計を行ってください。
  • 非同期実行 クエリーは同期して返されません。まだ実行中のクエリーは、状態 PENDING または RUNNING と statement_id を返します。状態が変化するまで、そのIDでpoll_sql_resultを呼び出します。例:SQLウェアハウスの指定を参照してください。

ワークスペースEndpoint​

このEndpointはパブリック プレビュー段階です。

既存の統合については、sql OAuth スコープで https://<workspace-hostname>/api/2.0/mcp/sql を使用します。このEndpointは、Managed MCP Serversワークスペースのプレビューと基盤となるリソースの権限を使用します。呼び出しはUnity Gatewayのトレース、MCPの権限付与、ポリシー、ガードレールを迂回します。新しい統合には、system.ai.dbsqlを使用してください。