Servidor MCP do Databricks SQL
The Databricks SQL MCP server lets agents execução AI-generated SQL against your Unity Catalog tables to read and write data, with access governed by Unity Catalog permissions. Queries execução asynchronously: the agent calls the tool to começar a query, then polls until the response completes.
Unity Gateway Beta
Para usar system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, um administrador de account deve habilitar a versão beta do Unity Gateway na página Previews do console da account. Consulte Gerenciar prévias da account.
Use este servidor para desenvolvimento e engenharia de dados: execução de uma query específica que você ou seu agente de codificação escreveu, inspeção de esquemas, validação de sintaxe SQL e criação de pipelines de dados a partir de ferramentas de codificação de AI. Ele oferece controle determinístico sobre o SQL exato que é executado.
O MCP permite leituras e gravações por default. Para torná-lo somente leitura, defina disallow_writes como true na política system.ai.dbsql_policy integrada. Consulte Aplicar uma política.
Servidores MCP do Genie One versus Databricks SQL MCP
For business questions asked in natural language, Databricks recommends the Genie One MCP server. Genie resolves business terms through Genie Ontology, your governed semantic layer. This produces more accurate answers than an agent writing SQL directly against raw tables.
Use o servidor Databricks SQL MCP quando precisar executar uma query específica que você ou seu agente de codificação escreveu, como validar a sintaxe ou criar um pipeline.
Para fazer perguntas com escopo definido para um único Genie Agent com curadoria, use o servidor MCP do Genie Agent. Para uma comparação de todos os três servidores, consulte Escolha entre servidores MCP Genie One, Genie Agent e Databricks SQL.
Conecte seu agente
Use esta URL com o guia de configuração do agente de programação ou a configuração do agente Python:
Padrão de URL | Escopo OAuth |
|---|---|
|
|
Peça ao seu agente para execução SELECT 1 AS result. Confirme que ele chama a ferramenta MCP e retorna 1.
_meta parâmetros
_meta parâmetros são valores de configuração que você predefine no código do seu agente para definir o comportamento do servidor MCP de forma determinística, em vez de deixar que o LLM os gere dinamicamente no momento da chamada da ferramenta. O servidor MCP do Databricks SQL aceita o seguinte parâmetro _meta:
Nome do parâmetro | Tipo | Descrição |
|---|---|---|
|
| O ID do SQL warehouse a ser usado para executar queries. Exemplo: Se não for especificado, o sistema seleciona automaticamente um warehouse com base em recursos e permissões. |
Exemplo: especificar um SQL warehouse para queries do Databricks SQL
Este exemplo mostra como usar o parâmetro warehouse_id _meta para especificar qual SQL Warehouse realiza a execução de queries do servidor Databricks SQL MCP usando o Python MCP SDK oficial.
Nesse cenário, você deseja:
- Use um SQL warehouse específico para a execução da query em vez de deixar o sistema selecionar um automaticamente
- Verifique o desempenho consistente roteando queries para um warehouse dedicado
Para execução deste exemplo, configure seu ambiente Python para desenvolvimento de MCP gerenciado:
Para encontrar o ID do seu SQL warehouse, consulte Conectar a um SQL warehouse.
# 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())
Limitações
- Sem contexto semântico. O servidor executa o SQL que lhe é fornecido. Ele não resolve termos de negócios, definições de métricas ou relacionamentos de tabelas, portanto, um agente deve inferi-los apenas a partir de esquemas. Para perguntas de analítica feitas em linguagem natural, use o servidor MCP do Genie One, que fundamenta as respostas na Ontologia do Genie.
- Tamanho do resultado. O servidor trunca grandes conjuntos de resultados nas respostas da ferramenta para evitar esgotar a janela de contexto do modelo. Retorne menos linhas e colunas, ou agregue em SQL, para manter os resultados dentro do limite.
- Execução assíncrona. As queries não retornam de forma síncrona. O agente inicia uma query e, em seguida, faz o polling até que ela seja concluída; portanto, ele deve lidar com estados em andamento.
Endpoint do workspace legado
For existing integrations, use https://<workspace-hostname>/api/2.0/mcp/sql with the sql OAuth scope. This Endpoint uses the Managed MCP Servers Workspace preview and underlying recursos permissions.