serveur MCP Databricks SQL

Le serveur SQL MCP de Databricks 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, l’accès étant régi par les autorisations d’Unity Catalog. Les requêtes s’exécutent de manière asynchrone : l’agent appelle l’outil pour lancer une requête, puis interroge jusqu’à la fin de la réponse.

Important

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

Utilisez ce serveur pour le développement et l’ingénierie des données : exécuter une requête spécifique que vous ou votre agent de codage avez rédigée, inspecter des schémas, valider la syntaxe SQL et créer des pipelines de données à partir d’outils de codage IA. Cela vous donne un contrôle déterministe sur le SQL exact qui s’exécute.

Le MCP permet par défaut les lectures et écritures. Pour la définir en lecture seule, définissez disallow_writes sur true dans la stratégie intégrée system.ai.dbsql_policy. Voir Appliquer une stratégie.

Genie One MCP versus serveurs Databricks SQL MCP

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

Utilisez le serveur SQL MCP de Databricks lorsque vous devez exécuter une requête spécifique que vous ou votre agent de codage avez écrite, comme valider la syntaxe ou créer un pipeline.

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

Connecter votre assistant

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

Modèle d’URL Étendue 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.

Paramètres _meta

_meta Les paramètres sont des valeurs de configuration que vous prédéfinissez dans votre code d’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 de l’outil. Le serveur SQL MCP de Databricks prend en charge le paramètre suivant _meta :

Nom du paramètre Type Description
warehouse_id str ID de l’entrepôt SQL à utiliser pour l’exécution de requêtes.
Exemple : "a1b2c3d4e5f67890"
S’il n’est pas spécifié, le système sélectionne automatiquement un entrepôt en fonction des ressources et des autorisations.

Exemple : spécifier un entrepôt SQL pour les requêtes Databricks SQL

Cet exemple montre comment utiliser le warehouse_id_meta paramètre pour spécifier l’entrepôt SQL qui exécute des requêtes à partir du serveur Databricks SQL MCP à l’aide du kit de développement logiciel (SDK) MCP officiel Python.

Dans ce scénario, vous souhaitez :

  • Utiliser un entrepôt SQL spécifique pour l’exécution des requêtes au lieu de laisser le système en sélectionner un automatiquement
  • Vérifier les performances cohérentes en acheminant les requêtes vers un entrepôt dédié

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

Pour rechercher votre ID d’entrepôt SQL, consultez Se connecter à un entrepôt 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

  • Aucun contexte sémantique. Le serveur exécute le SQL qui lui est donné. Il ne résout pas les termes métier, les définitions métriques ou les relations de table, donc un agent doit les déduire uniquement à partir des schémas. Pour les questions d’analyse posées en langage naturel, utilisez le serveur MCP Genie One, qui base les réponses dans Genie Ontology.
  • Taille du résultat. Le serveur tronque de grands ensembles de résultats dans les réponses des outils afin d’éviter d’épuiser la fenêtre de contexte du modèle. Retournez moins de lignes et de colonnes, ou agrégez en SQL pour garder les résultats dans la limite.
  • Exécution asynchrone. Les requêtes ne sont pas rendues de manière synchrone. L’agent lance une requête, puis interroge jusqu’à ce qu’elle soit terminée, il doit donc gérer les états en cours.

Point de terminaison de l’espace de travail hérité

Pour les intégrations existantes, utilisez https://<workspace-hostname>/api/2.0/mcp/sql avec le sql scope OAuth. Ce point de terminaison utilise l’aperçu de l’espace de travail des Managed MCP Servers et les permissions de ressources sous-jacentes.

  • Dernière mise à jour :