Server SQL MCP Databricks

Server Databricks SQL MCP memungkinkan agen menjalankan SQL yang dihasilkan AI terhadap tabel Unity Catalog Anda untuk membaca dan menulis data, dengan akses diatur oleh izin Unity Catalog. Kueri berjalan secara asinkron: agen memanggil alat untuk memulai kueri, lalu melakukan polling hingga respons selesai.

Important

Untuk menggunakan system.ai.dbsql, system.ai.sandbox, atau system.ai.web_search, admin akun harus mengaktifkan beta Unity Gateway dari halaman Pratinjau konsol akun. Lihat Kelola pratinjau akun.

Gunakan server ini untuk pengembangan dan rekayasa data: menjalankan kueri spesifik yang Anda atau agen coding Anda tulis, memeriksa skema, memvalidasi sintaks SQL, dan membuat pipeline data dari alat pengkodean AI. Ini memberi Anda kendali yang deterministik terhadap SQL persis yang dijalankan.

MCP secara default mengizinkan membaca dan menulis secara default. Untuk menjadikannya hanya baca, atur disallow_writes ke true dalam kebijakan bawaan system.ai.dbsql_policy. Lihat Terapkan kebijakan.

Genie One MCP versus Databricks SQL MCP server

Untuk pertanyaan bisnis yang diajukan dalam bahasa alami, Databricks merekomendasikan server Genie One MCP. Genie menafsirkan istilah bisnis melalui Genie Ontology, lapisan semantik terkelola Anda. Ini menghasilkan jawaban yang lebih akurat dibandingkan agen yang menulis SQL langsung terhadap tabel mentah.

Gunakan server Databricks SQL MCP saat Anda perlu menjalankan query spesifik yang Anda atau agen coding Anda tulis, seperti memvalidasi sintaks atau membuat pipeline.

Hubungkan agent Anda

Gunakan URL ini dengan panduan pengaturan agen kode Anda atau pengaturan agen Python:

Pola URL Cakupan OAuth
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql ai-gateway

Minta agen Anda untuk menjalankan SELECT 1 AS result. Konfirmasi bahwa alat tersebut memanggil alat MCP dan mengembalikan 1.

_meta parameter

_meta parameter adalah nilai konfigurasi yang Anda atur sebelumnya dalam kode agen Anda untuk mengatur perilaku server MCP secara deterministik, bukan membiarkan LLM menghasilkannya secara dinamis saat pemanggilan alat. Server Databricks SQL MCP mendukung parameter berikut _meta :

Nama Parameter Tipe Description
warehouse_id str ID gudang SQL yang akan digunakan untuk mengeksekusi kueri.
Contoh: "a1b2c3d4e5f67890"
Jika tidak ditentukan, sistem secara otomatis memilih gudang berdasarkan sumber daya dan izin.

Contoh: tentukan gudang SQL untuk kueri Databricks SQL

Contoh ini menunjukkan cara menggunakan warehouse_id_meta parameter untuk menentukan gudang SQL mana yang menjalankan kueri dari server Databricks SQL MCP menggunakan Python resmi MCP SDK.

Dalam skenario ini, Anda ingin:

  • Gunakan gudang SQL tertentu untuk eksekusi kueri alih-alih membiarkan sistem memilihnya secara otomatis
  • Verifikasi konsistensi kinerja dengan merutekan kueri ke warehouse khusus

Untuk menjalankan contoh ini, siapkan lingkungan Python Anda untuk pengembangan MCP terkelola:

Untuk menemukan ID gudang SQL Anda, lihat Menyambungkan ke gudang SQL.

# Import required libraries for MCP client and Databricks authentication
import asyncio
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 get the response
            response = await session.send_request(request, CallToolResult)
            return response

# Execute the async function and get results
response = asyncio.run(run_dbsql_tool_call_with_meta())

Limitations

  • Tidak ada konteks semantik. Server menjalankan SQL yang diberikan. Ia tidak menyelesaikan istilah bisnis, definisi metrik, atau hubungan tabel, jadi agen harus menyimpulkannya hanya dari skema. Untuk pertanyaan analitik yang diajukan dalam bahasa alami, gunakan server Genie One MCP, yang mendasarkan jawaban pada Genie Ontology.
  • Ukuran hasil. Server memotong set hasil besar dalam respons alat untuk menghindari kehabisan jendela konteks model. Kembalikan lebih sedikit baris dan kolom, atau agregasi dalam SQL, untuk menjaga hasil tetap dalam batas.
  • Eksekusi asinkron. Kueri tidak dikembalikan secara sinkron. Agen memulai kueri, lalu memeriksa statusnya secara berkala hingga kueri selesai, sehingga harus menangani status yang masih diproses.

Endpoint ruang kerja lama

Untuk integrasi yang sudah ada, gunakan https://<workspace-hostname>/api/2.0/mcp/sql dengan cakupan OAuth sql. Endpoint ini menggunakan pratinjau workspace Managed MCP Servers dan izin sumber daya yang mendasarinya.

  • Terakhir diperbarui pada