Aller au contenu principal
Dernière mise à jour le

Serveur MCP Databricks SQL

Le serveur MCP Databricks SQL permet aux agents d’exécuter du SQL généré par IA sur vos tables Unity Catalog pour lire et écrire des données, avec un accès régi par les autorisations Unity Catalog. Les queries s’exécutent de manière asynchrone : l’agent appelle l’outil pour start une query, puis effectue des requêtes successives jusqu’à ce que la réponse soit complète.

info

Unity Gateway Beta

Pour utiliser system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, un administrateur de compte doit activer la version bêta de Unity Gateway depuis la page Previews de la console du compte. Consultez Gérer les aperçus du compte.

Utilisez ce serveur pour le développement et le data engineering : exécution d'une query spécifique que vous ou votre agent de codage avez écrite, inspection des schémas, validation de la syntaxe SQL et création de pipelines de données à partir d'outils de codage IA. Cela vous donne un contrôle déterministe sur le SQL exact qui est exécuté.

Le protocole MCP autorise les lectures et les écriture par default. Pour le rendre en lecture seule, définissez disallow_writes sur true dans la politique system.ai.dbsql_policy intégré. Voir Appliquer une politique.

Serveurs MCP Genie One versus MCP Databricks SQL​

Pour les questions métier posées en langage naturel, Databricks recommande le serveur MCP Genie One. Genie résout les termes métier par le biais de Genie Ontology, votre couche sémantique gouvernée. Cela produit des réponses plus précises qu’un agent écrivant du SQL directement sur des tables brutes.

Utilisez le serveur MCP Databricks SQL lorsque vous devez exécuter une query spécifique écrite par vous ou par votre agent de codage, telle que la validation de la syntaxe ou la création d'un pipeline.

Pour poser des questions limitées à un seul Genie Agent organisé, utilisez le serveur MCP Genie Agent. Pour une comparaison des trois serveurs, voir Choisir entre les serveurs MCP Genie One, Genie Agent et Databricks SQL.

Connectez votre agent​

Utilisez cette URL avec le guide de configuration de votre agent de programmation ou la configuration de l'agent Python:

Modèle d'URL

Champ d’application d’OAuth

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

ai-gateway

Modèle d'URL

Champ d’application d’OAuth

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

ai-gateway

Demandez à votre agent d'exécuter SELECT 1 AS result. Confirmez qu'il appelle l'outil MCP et renvoie 1.

_meta parameter​

_meta Les paramètres sont des valeurs de configuration que vous prédéfinissez dans le code de votre agent pour définir le comportement du serveur MCP de manière déterministe, plutôt que de laisser le LLM les générer dynamiquement au moment de l’appel d’outil. Le serveur MCP Databricks SQL prend en charge le parameter _meta suivant :

Nom du parameter

Type

Description

warehouse_id

str

L’ID du SQL Warehouse à utiliser pour l’exécution des queries.

Exemple : "a1b2c3d4e5f67890"

S’il n’est pas spécifié, le système sélectionne automatiquement un warehouse en fonction des ressources et des autorisations.

Nom du parameter

Type

Description

warehouse_id

str

L’ID du SQL Warehouse à utiliser pour l’exécution des queries.

Exemple : "a1b2c3d4e5f67890"

S’il n’est pas spécifié, le système sélectionne automatiquement un warehouse en fonction des ressources et des autorisations.

Exemple : spécifier un SQL warehouse pour les requêtes Databricks SQL​

Cet exemple montre comment utiliser le parameter warehouse_id _meta pour spécifier quel SQL Warehouse exécute les queries depuis le serveur Databricks SQL MCP à l’aide du SDK MCP Python officiel.

Dans ce scénario, vous souhaitez :

  • Utilisez un SQL Warehouse spécifique pour l'exécution de la query au lieu de laisser le système en sélectionner un automatiquement
  • Vérifiez la cohérence des performances en routant les query vers un warehouse dédié

Pour exécuter cet exemple, configurez votre environnement Python pour le développement MCP géré:

Pour trouver votre ID de SQL Warehouse, consultez Connect to a SQL warehouse.

Python
# 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​

  • Aucun contexte sémantique. Le serveur exécute le SQL qui lui est fourni. Il ne résout pas les termes métier, les définitions de métriques ou les relations de table ; un agent doit donc les déduire uniquement à partir des schémas. Pour les questions d’analytique posées en langage naturel, utilisez le serveur MCP Genie One, qui base les réponses sur la Genie Ontology.
  • Taille des résultats. Le serveur tronque les jeux de résultats volumineux dans les réponses des outils afin d'éviter d'épuiser la fenêtre de contexte du modèle. Renvoyez moins de lignes et de colonnes, ou effectuez une agrégation en SQL, pour maintenir les résultats dans la limite autorisée.
  • Exécution asynchrone. Les queries ne renvoient pas de résultats de manière synchrone. L’agent start une query, puis interroge jusqu’à ce qu’elle soit terminée ; il doit donc gérer les états en cours.

Endpoint de Workspace hérité​

Pour les intégrations existantes, utilisez https://<workspace-hostname>/api/2.0/mcp/sql avec le champ d'application d'OAuth sql. Cet endpoint utilise l'aperçu du workspace des serveurs MCP gérés et les autorisations de ressources sous-jacentes.

Sur cette page