Servidor MCP de Databricks SQL

El servidor SQL MCP de Databricks permite a los agentes ejecutar SQL generado por IA sobre tus tablas de Unity Catalog para leer y escribir datos, con acceso regido por permisos de Unity Catalog. Las consultas se ejecutan de forma asíncrona: el agente llama a la herramienta para iniciar una consulta y luego consulta hasta que la respuesta se completa.

Importante

Para usar system.ai.dbsql, system.ai.sandbox, o system.ai.web_search, un administrador de cuenta debe habilitar la beta Unity Gateway desde la página de Previews de la consola de cuentas. Consulta Administrar vistas previas de la cuenta.

Utiliza este servidor para desarrollo e ingeniería de datos: ejecutando una consulta específica que tú o tu agente de programación hayan redactado, inspeccionando esquemas, validando la sintaxis SQL y creando pipelines de datos a partir de herramientas de codificación con IA. Te da un control determinista sobre el SQL exacto que se ejecuta.

El MCP permite operaciones de lectura y escritura por defecto. Para que sea de solo lectura, establece disallow_writes en true en la directiva integrada system.ai.dbsql_policy. Consulta Aplicar una política.

Genie One MCP frente a servidores SQL MCP de Databricks

Para preguntas empresariales hechas en lenguaje natural, Databricks recomienda el servidor MCP Genie One. Genie resuelve términos de negocio a través de la Ontología Genie, tu capa semántica gobernada. Esto produce respuestas más precisas que un agente que escribe SQL directamente sobre tablas en bruto.

Usa el servidor SQL MCP de Databricks cuando necesites ejecutar una consulta específica que tú o tu agente de programación hayan escrito, como validar la sintaxis o crear una pipeline.

Para hacer preguntas limitadas a un único Agente Genie seleccionado, utiliza el servidor MCP del Agente Genie. Para una comparación de los tres servidores, consulte Elegir entre los servidores Genie One, Genie Agent y Databricks SQL MCP.

Conectar su agente

Usa esta URL con la guía de configuración de tu agente de programación o la configuración del agente en Python:

Patrón de URL Ámbito de OAuth
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql ai-gateway

Pide a tu agente que ejecute SELECT 1 AS result. Confirma que llama a la herramienta MCP y devuelve 1.

Parámetros _meta

_meta los parámetros son valores de configuración que preestableces en el código de tu agente para establecer el comportamiento del servidor MCP de forma determinista, en lugar de dejar que el LLM los genere dinámicamente en el momento de la llamada a la herramienta. El servidor SQL MCP de Databricks soporta el siguiente _meta parámetro:

Nombre del parámetro Tipo Descripción
warehouse_id str El identificador del almacén de datos SQL que se va a usar para ejecutar consultas.
Ejemplo: "a1b2c3d4e5f67890"
Si no se especifica, el sistema selecciona automáticamente un almacén en función de los recursos y los permisos.

Ejemplo: especificar un almacén SQL para las consultas de Databricks SQL

En este ejemplo se muestra cómo usar el warehouse_id_meta parámetro para especificar qué almacenamiento SQL ejecuta consultas desde el servidor MCP de SQL de Databricks mediante el SDK de MCP oficial de Python.

En este escenario, deseas:

  • Usar un almacenamiento SQL específico para la ejecución de consultas en lugar de permitir que el sistema seleccione uno automáticamente.
  • Comprobación del rendimiento coherente mediante el enrutamiento de consultas a un almacenamiento dedicado

Para ejecutar este ejemplo, configure el entorno de Python para el desarrollo de MCP administrado:

Para encontrar su identificador de SQL Warehouse, consulte Conectar a un 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

  • Sin contexto semántico. El servidor ejecuta el SQL que se le asigna. No resuelve términos de negocio, definiciones métricas ni relaciones de tablas, por lo que un agente debe inferirlos solo a partir de esquemas. Para preguntas de analítica hechas en lenguaje natural, usa el servidor MCP de Genie One, que fundamenta las respuestas en Ontología Genie.
  • Tamaño del resultado. El servidor trunca grandes conjuntos de resultados en las respuestas de la herramienta para evitar agotar la ventana de contexto del modelo. Devuelve menos filas y columnas, o agrega en SQL para mantener los resultados dentro del límite.
  • Ejecución asincrónica. Las consultas no se devuelven de forma sincrónica. El agente inicia una consulta y, a continuación, realiza sondeos hasta que se completa, por lo que debe administrar los estados en curso.

Endpoint de espacio de trabajo heredado

Para integraciones existentes, úsalo https://<workspace-hostname>/api/2.0/mcp/sql con el sql alcance OAuth. Este punto de conexión utiliza la versión preliminar del área de trabajo de servidores MCP administrados y los permisos de los recursos subyacentes.

  • Última actualización el