Aller au contenu principal
Dernière mise à jour le

Serveur MCP Genie One

Le serveur MCP Genie One est un MCP fourni par Databricks qui expose Genie en tant qu’outil conversationnel via le Model Context Protocol (MCP), en tirant parti de Chat in Genie One. Un client ou agent MCP envoie une question en langage naturel, et Genie effectue une recherche dans vos données d’entreprise, écrit du SQL et renvoie une réponse basée sur la Genie Ontology avec des Link profonds vers vos sources Databricks citées.

Connectez n’importe quel client ou agent MCP pour ancrer ses questions sur les données dans les insights de confiance de Genie. Les clients qui prennent en charge les applications MCP peuvent afficher une vue interactive qui montre la progression, les visualisations et les résultats de Genie en ligne.

Les autorisations de Unity Catalog sont toujours appliquées ; ainsi, les utilisateurs et les agents ne peuvent effectuer que des query sur les données auxquelles ils sont autorisés à accéder.

Utilisez ce serveur pour l'analytique dans votre Workspace : questions métier posées en langage naturel, où la précision dépend de la compréhension de la signification de vos données. Genie résout les termes métier, les définitions de métriques et les relations entre les tables via Genie Ontology, votre couche sémantique gouvernée, ce qui produit des réponses plus précises qu'un agent écrivant du SQL directement sur des tables brutes.

astuce

Pour query un agent Genie Agent sélectionné à partir de Python, utilisez les exemples d’outils AI Bridge. Pour query un agent spécifique via MCP, consultez le serveur MCP Genie Agent. Pour appeler Genie One à partir d’une application sans MCP, utilisez l’ API Genie One.

Prérequis​

Pour appeler le serveur MCP Genie One, un utilisateur ou un Service Principal a besoin des éléments suivants :

  • EXECUTE sur system.ai.genie_one_mcp. Son type sécurisable est mcp_service.
  • USE CATALOG sur le catalogue system et USE SCHEMA sur le schéma system.ai.
  • Attribution au workspace.

Pour vérifier les autorisations effectives d'un appelant avec le Databricks CLI, exécutez :

Bash
databricks grants get-effective mcp_service system.ai.genie_one_mcp --principal someone@example.com

Pour accorder EXECUTE, exécutez :

Bash
databricks grants update mcp_service system.ai.genie_one_mcp \
  --json '{"changes": [{"principal": "someone@example.com", "add": ["EXECUTE"]}]}'

Pour accorder l’accès à un MCP fourni par Databricks, un administrateur de metastore doit d’abord s’accorder MANAGE sur le schéma system.ai. Voir Partager un MCP.

Accès via Unity Gateway​

Le serveur MCP Genie One est un MCP fourni par Databricks, system.ai.genie_one_mcp, régi par Unity Gateway.

Appelez le MCP à l'URL de sa Unity Gateway, avec son nom Unity Catalog pleinement qualifié dans le chemin et votre ID de workspace dans le o parameter de query :

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>

Pour obtenir l'identifiant du workspace sans l'interface utilisateur, utilisez l'une des options suivantes :

  • Valeur o= dans l'URL de votre workspace.
  • L’en-tête x-databricks-org-id sur toute réponse de l’API REST Databricks.
  • WorkspaceClient().get_workspace_id() dans le SDK Databricks pour Python.

Lors de la connexion avec l'authentification de l'utilisateur pour le compte de, incluez le périmètre OAuth ai-gateway. Pour contrôler l'accès et appliquer des politiques, consultez Régir un MCP. Pour ajouter le MCP à un agent, consultez Appeler des outils MCP à partir d'un agent Python. Pour connecter des clients externes tels que Cursor ou Claude Desktop, consultez Agents de codage et de travail pris en charge.

attention

Obsolète

L’endpoint bêta, https://<workspace-hostname>/api/2.0/mcp/genie, est obsolète et arrivera en fin de vie le 30 novembre 2026. Après cette date, les requêtes vers l’endpoint bêta échoueront. Déplacez toutes les charges de travail vers le MCP system.ai.genie_one_mcp généralement disponible avant cette date.

Les noms d’outils et les arguments sont les mêmes sur les deux Endpoint. Pour déplacer un client de l’endpoint bêta, mettez à jour sa configuration MCP :

  • Remplacez l’URL du serveur par https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>.
  • Si le client utilise OAuth, demandez le scope ai-gateway plutôt que le scope genie.
  • Assurez-vous que les appelants disposent des autorisations dans Configuration requise.

Connecter des agents IA à Genie One MCP​

Pour connecter un agent de codage ou un autre client MCP, configurez le client pour qu’il se connecte à l’URL MCP de Unity Gateway https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp?o=<workspace-id>. Suivez la configuration pour les agents de codage ou les autres clients MCP.

Pour afficher vos MCP et leurs URL, accédez à votre workspace et sélectionnez Unity Gateway > MCP . Pour lister les MCP fournis par Databricks avec l’API REST, appelez GET /api/2.1/unity-catalog/mcp-services?parent=schemas/system.ai. Voir Trouver un MCP.

Appel depuis Python avec le SDK MCP​

Le serveur utilise le transport HTTP diffusable et accepte un jeton Databricks dans un en-tête Authorization: Bearer <token>. L’exemple suivant utilise le MCP Python SDK et le SDK Databricks pour Python afin de poser une question, d’interroger jusqu’à ce que Genie termine, puis de poser une question de suivi dans la même conversation.

Installez les packages :

Bash
pip install mcp databricks-sdk

Exécutez l’exemple :

Python
import asyncio

from databricks.sdk import WorkspaceClient
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

w = WorkspaceClient()
url = (
    f"{w.config.host}/ai-gateway/mcp-services/system.ai.genie_one_mcp"
    f"?o={w.get_workspace_id()}"
)


async def ask(session, question, conversation_id=None):
    args = {"question": question}
    if conversation_id:
        args["conversation_id"] = conversation_id
    state = (await session.call_tool("genie_ask", args)).structuredContent

    # Poll until Genie finishes: completed, incomplete, or failed.
    while state["status"] == "in_progress":
        poll = await session.call_tool(
            "genie_poll_response",
            {
                "conversation_id": state["conversation_id"],
                "response_id": state["response_id"],
            },
        )
        state = poll.structuredContent
    return state


async def main():
    # w.config.authenticate() returns {"Authorization": "Bearer <token>"}.
    async with streamablehttp_client(url, headers=w.config.authenticate()) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([tool.name for tool in tools.tools])

            first = await ask(session, "What were total sales last month?")
            print(first["status"], first.get("final_answer"))

            follow_up = await ask(
                session, "Break that down by region.", first["conversation_id"]
            )
            print(follow_up["status"], follow_up.get("final_answer"))


asyncio.run(main())

L’exemple ne demande pas de notifications de progression, donc genie_ask retourne immédiatement avec status: in_progress, et le client interroge genie_poll_response pour la réponse.

Plugins Databricks Genie pour ChatGPT, Claude et Grok Bot/Cursor​

Les plugins Databricks Genie connectent ChatGPT, Claude et Grok Bot/Cursor au MCP Genie One. Ils utilisent des applications OAuth default, si bien que les utilisateurs se connectent avec leur compte Databricks et qu’un administrateur n’a pas besoin de créer d’application OAuth.

Un administrateur configure le plugin en premier. Ensuite, chaque utilisateur s’y connecte et s’identifie.

remarque

Si votre workspace restreint l'accès réseau entrant, un administrateur Databricks doit autoriser le trafic ChatGPT ou Claude, sinon le plugin ne pourra pas se connecter. Voir Autoriser les plates-formes partenaires dans les politiques d'accès entrant basées sur le contexte.

Pour configurer le plugin, un administrateur ChatGPT effectue les opérations suivantes :

  1. Dans les paramètres de votre workspace ChatGPT, cliquez sur Plugins .
  2. Rechercher Databricks Genie .
  3. Cliquez sur Créer à partir d’un template .
  4. Saisissez l’URL de votre Workspace Databricks. Si vous utilisez une URL personnalisée, incluez votre ID Workspace en tant que ?o=<workspace-id>.
  5. Cliquez sur Créer un brouillon .
  6. Cliquez sur Publier .

Pour se connecter, chaque utilisateur effectue les opérations suivantes :

  1. Dans ChatGPT, ouvrez la page Plugins .
  2. Rechercher Databricks Genie .
  3. Sur le plugin que votre administrateur a configuré, cliquez sur Connexion .
  4. Lorsque ChatGPT vous redirige, connectez-vous avec votre compte Databricks.

Pour plus d’informations, voir le plugin ChatGPT Genie.

Outils disponibles​

Le serveur MCP Genie One expose les outils suivants. En pratique, un agent appelle genie_ask (ou view_ask sur les clients MCP Apps) pour poser une question ; l’agent gère les outils restants en votre nom pendant qu’il traite la réponse.

Outil

Description

genie_ask

Posez une question sur les données en langage naturel à Genie et start une réponse. Renvoie conversation_id, response_id et status. Transmettez un conversation_id pour poursuivre une conversation précédente.

genie_poll_response

Récupérez le dernier état d'une réponse en cours ou terminée, y compris les étapes de progression, la réponse finale et les Link profonds vers vos sources Databricks.

genie_get_query_result

Récupère le résultat SQL complet, y compris le schéma de colonne et les lignes, pour une query exécutée par Genie. Appelez-la après que genie_poll_response a signalé status: completed. Prend les éléments conversation_id et response_id avec lesquels vous avez effectué l'interrogation, ainsi que les éléments item_id de la query à partir de genie_poll_response, dans structuredContent.query_items[].item_id.

genie_cancel_response

Demander l’annulation d’un tour Genie en cours.

view_ask

Posez une question à Genie et ouvrez la vue interactive. Proposé à la place de genie_ask aux clients MCP Apps, et privilégié lorsqu’il est disponible.

Outil

Description

genie_ask

Posez une question sur les données en langage naturel à Genie et start une réponse. Renvoie conversation_id, response_id et status. Transmettez un conversation_id pour poursuivre une conversation précédente.

genie_poll_response

Récupérez le dernier état d'une réponse en cours ou terminée, y compris les étapes de progression, la réponse finale et les Link profonds vers vos sources Databricks.

genie_get_query_result

Récupère le résultat SQL complet, y compris le schéma de colonne et les lignes, pour une query exécutée par Genie. Appelez-la après que genie_poll_response a signalé status: completed. Prend les éléments conversation_id et response_id avec lesquels vous avez effectué l'interrogation, ainsi que les éléments item_id de la query à partir de genie_poll_response, dans structuredContent.query_items[].item_id.

genie_cancel_response

Demander l’annulation d’un tour Genie en cours.

view_ask

Posez une question à Genie et ouvrez la vue interactive. Proposé à la place de genie_ask aux clients MCP Apps, et privilégié lorsqu’il est disponible.

Posez une question​

Comme Genie exécute un agent qui recherche des données et exécute du SQL, les réponses sont asynchrones. Vous (ou votre agent) invoquez genie_ask avec une question ; l’agent gère ensuite le reste de l’échange automatiquement. Un flux typique se présente comme suit :

  1. genie_ask start la réponse et renvoie un conversation_id et un response_id avec status: in_progress. Genie continue de fonctionner en arrière-plan.
  2. L’agent interroge genie_poll_response jusqu’à ce que la réponse soit terminée, en faisant apparaître progress_steps et narration_instruction en cours de route pour vous tenir informé.
  3. Lorsque status est completed (ou incomplete / failed), l’agent renvoie la réponse rendue, incluant un Explore in Databricks deep link vers la conversation complète et toute visualisation produite par Genie.

Pour poursuivre la même conversation, la question de suivi réutilise le conversation_id précédent.

Application MCP​

Le serveur MCP Genie One fournit une application MCP, une extension qui permet à un serveur de renvoyer une vue interactive au lieu d’un texte brut. Sur les clients qui prennent en charge les applications MCP, le serveur renvoie une vue interactive : un panneau intégré au client qui affiche la progression, les visualisations et la réponse finale de Genie au fur et à mesure du déroulement de la conversation, plutôt qu’une réponse textuelle uniquement.

L’application MCP Genie One affichant un graphique à barres, des métriques récapitulatives et des citations de l’ontologie Genie dans Claude Desktop.

L’application MCP Genie One affichant un graphique à barres, des métriques récapitulatives et des citations de l’ontologie Genie dans Claude Desktop.

Aucune configuration supplémentaire n'est requise. Les clients qui prennent en charge les applications MCP obtiennent automatiquement la vue interactive. Clients qui ne continuent pas à recevoir des résultats textuels.

Considérations​

  • Autorisations : les autorisations Unity Catalog sont appliquées à chaque requête, de sorte que les résultats sont limités à ce à quoi l'utilisateur peut accéder.
  • Authentification utilisateur : L’authentification OAuth utilisateur pour le compte de est recommandée, conformément aux meilleures pratiques de gouvernance des données et permettant un passage fluide aux sources Genie. L'authentification par Service Principal est également prise en charge pour les charges de travail programmatiques et automatisées. N’importe quel jeton Databricks envoyé dans un en-tête Authorization: Bearer fonctionne, y compris les jetons utilisateur à machine (U2M) OAuth, les jetons machine à machine (M2M) OAuth et les jetons d’accès personnels. Un flux OAuth dans un navigateur n’est donc pas nécessaire. Voir Authentification entrante prise en charge.
  • Configuration : le serveur respecte votre configuration Genie One dans Databricks. Ajustez et configurez le comportement de Genie à cet endroit. Voir Chat dans Genie One.
  • Cadence d’interrogation : attendez que l’appel genie_poll_response précédent soit terminé avant d’interroger à nouveau.
  • Taille des résultats : pour protéger la fenêtre de contexte du modèle, genie_ask et genie_poll_response renvoient des résultats de query tronqués. Lorsqu’un agent a besoin du résultat complet, il peut appeler genie_get_query_result pour récupérer le schéma complet et les lignes. Les résultats très volumineux restent soumis à une limite de taille ; si celle-ci est dépassée, la réponse est tronquée.
  • SQL Warehouse : Pour exécuter des query sur un SQL Warehouse spécifique, transmettez warehouse_id dans les _meta parameter sur genie_ask ou view_ask.
  • Tarifs : Le serveur MCP Genie One utilise Chat in Genie One. Voir les tarifs de Genie.

Dépannage​

  • Routine or Model ... does not exist ou MCP is not a valid securable type lorsque vous vérifiez ou accordez des permissions : utilisez mcp_service comme type sécurisable, pas function ou mcp. Les types function et mcp ne permettent pas de résoudre le MCP.
  • genie_poll_response ne renvoie aucun query_items une fois la réponse terminée : obtenez le item_id à partir du commentaire Tool-call IDs à la fin du texte du sondage, ou capturez structuredContent.query_items[].item_id à partir d'un sondage précédent alors que la réponse était en cours.
  • item_id ne se résout pas dans genie_get_query_result : un item_id valide ressemble à pub_..._output. Ne transmettez pas un ID incorporé query_... à partir des marqueurs de commentaire de la table de résultats en tant que item_id car il ne sera pas résolu.

Ressources supplémentaires​

Sur cette page