Servidor Databricks SQL MCP

O servidor Databricks SQL MCP permite que os agentes executem SQL gerado por IA contra as suas tabelas do Unity Catalog para ler e escrever dados, com acesso regulado pelas permissões do Unity Catalog. As consultas são executadas de forma assíncrona: o agente chama a ferramenta para iniciar uma consulta e depois faz sondagens até a resposta estar 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 da consola da conta. Consulte Gerir pré-visualizações da conta.

Use este servidor para desenvolvimento e engenharia de dados: executar uma consulta específica que você ou o seu agente de programação escreveu, inspecionar esquemas, validar sintaxe SQL e criar pipelines de dados a partir de ferramentas de codificação por IA. Permite-lhe ter controlo determinístico sobre o SQL exato que é executado.

O MCP permite leituras e escritas por predefinição. Para o tornar apenas de leitura, defina disallow_writes como true na política incorporada system.ai.dbsql_policy. Veja Aplicar uma política.

Genie One MCP versus servidores SQL MCP Databricks

Para questões empresariais feitas em linguagem natural, a Databricks recomenda o servidor MCP Genie One. O Genie resolve termos empresariais através da Ontologia Genie, a sua camada semântica governada. Isto produz respostas mais precisas do que um agente a escrever SQL diretamente sobre tabelas brutas.

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

Ligar ao seu agente

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

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

Pede ao teu agente para executar SELECT 1 AS result. Confirme que chama a ferramenta MCP e retorna 1.

_meta Parâmetros

_meta Os parâmetros são valores de configuração que pré-define no código do agente para definir o comportamento do servidor MCP de forma determinista, em vez de deixar o LLM gerá-los dinamicamente no momento da chamada à 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 para usar na execução de consultas.
Exemplo: "a1b2c3d4e5f67890"
Se não especificado, o sistema seleciona automaticamente um armazém com base em recursos e permissões.

Exemplo: especificar um warehouse SQL para consultas SQL do Databricks

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

Nesse cenário, você deseja:

  • Use um warehouse SQL específico para execução de consultas em vez de deixar o sistema selecionar uma automaticamente
  • Verifique o desempenho consistente encaminhando consultas para um armazém dedicado

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

Para encontrar o ID do seu armazém SQL, veja Ligar a um armazém 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

  • Sem contexto semântico. O servidor executa o SQL que lhe é atribuído. Não resolve termos de negócio, definições de métricas ou relações de tabelas, pelo que um agente tem de os inferir apenas a partir dos esquemas. Para perguntas de análise feitas em linguagem natural, use o servidor Genie One MCP, que fundamenta as respostas na Genie Ontology.
  • Tamanho do resultado. O servidor trunca grandes conjuntos de resultados nas respostas da ferramenta para evitar esgotar a janela de contexto do modelo. Devolva menos linhas e colunas, ou faça a agregação 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, verifica periodicamente até que esta esteja concluída, pelo que tem de lidar com estados em curso.

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é-visualização do espaço de trabalho dos Managed MCP Servers e as permissões de recursos subjacentes.

  • Última atualização a