Databricks SQL MCP servidor

O servidor SQL MCP do Databricks permite que agentes executem SQL gerado por IA contra suas tabelas do Unity Catalog para ler e gravar dados, com acesso regido pelas permissões do Unity Catalog. Consultas rodam de forma assíncrona: o agente chama a ferramenta para iniciar uma consulta, depois faz sondeios até que a resposta seja concluída.

Importante

Para usar system.ai.dbsql, system.ai.sandbox, ou system.ai.web_search, um administrador de conta deve ativar a versão beta do Unity Gateway a partir da página de Pré-visualizações do console da conta. Veja Gerenciar prévias de conta.

Use este servidor para desenvolvimento e engenharia de dados: executando uma consulta específica que você ou seu agente de codificação escreveu, inspecionando esquemas, validando a sintaxe SQL e criando pipelines de dados a partir de ferramentas de codificação de IA. Isso te dá controle determinístico sobre o SQL exato que roda.

O MCP permite leituras e gravações por padrão. Para torná-lo somente leitura, defina disallow_writes como true na política embutida system.ai.dbsql_policy. Veja Aplicar uma política.

Genie One MCP versus servidores SQL MCP Databricks

Para perguntas de negócios feitas em linguagem natural, a Databricks recomenda o servidor MCP Genie One. Genie resolve os termos de negócio por meio da Ontologia Genie, sua camada semântica governada. Isso produz respostas mais precisas do que um agente escrevendo SQL diretamente sobre tabelas brutas.

Use o servidor SQL MCP do Databricks quando precisar executar uma consulta específica que você ou seu agente de programação escreveu, como validar sintaxe ou criar um pipeline.

Conectar seu agente

Use este URL com o guia de configuração do seu agente de programação ou com a configuração do agente Python:

Padrão de URL Escopo do OAuth
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql ai-gateway

Peça para seu agente executar SELECT 1 AS result. Confirme que ele chama a ferramenta MCP e retorna 1.

Parâmetros _meta

_meta os parâmetros são valores de configuração que você pré-define no código do seu agente para definir o comportamento do servidor MCP de forma determinista, em vez de deixar o LLM gerá-los dinamicamente no momento da chamada de ferramenta. O servidor SQL MCP do Databricks suporta o seguinte _meta parâmetro:

Nome do parâmetro Tipo Description
warehouse_id str O ID do SQL Warehouse a ser usado para executar consultas.
Exemplo: "a1b2c3d4e5f67890"
Se não for especificado, o sistema selecionará automaticamente um warehouse com base em recursos e permissões.

Exemplo: especificar um SQL Warehouse para consultas SQL do Databricks

Este exemplo mostra como usar o parâmetro warehouse_id_meta para especificar qual SQL warehouse executa consultas do servidor MCP do Databricks SQL usando o SDK MCP oficial para Python.

Nesse cenário, você deseja:

  • Use um sql warehouse específico para execução de consulta em vez de permitir que o sistema selecione um automaticamente
  • Verificar o desempenho consistente roteando consultas para um warehouse dedicado

Para executar este exemplo, configure o ambiente do Python para o desenvolvimento gerenciado do MCP:

Para encontrar sua ID do SQL Warehouse, consulte Conectar-se 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())

Limitations

  • Sem contexto semântico. O servidor roda o SQL que ele recebe. Ele não resolve termos de negócios, definições métricas ou relações de tabelas, então um agente deve inferir esses termos apenas a partir dos esquemas. Para perguntas de análise feitas em linguagem natural, use o servidor MCP do Genie One, que fundamenta as respostas no Genie Ontology.
  • Tamanho do resultado. O servidor trunca grandes conjuntos de resultados nas respostas das ferramentas para evitar esgotar a janela de contexto do modelo. Retorne menos linhas e colunas, ou faça agregações em SQL, para manter os resultados dentro do limite.
  • Execução assíncrona. As consultas não retornam de forma síncrona. O agente inicia uma consulta e, em seguida, consulta até que ela seja concluída, logo, ele deve manipular estados em andamento.

Endpoint de workspace legado

Para integrações existentes, use https://<workspace-hostname>/api/2.0/mcp/sql com o sql escopo OAuth. Este endpoint utiliza a prévia do workspace do Managed MCP Servers e as permissões de recursos subjacentes.

  • Última atualização em