Aller au contenu principal

Connectez votre application aux outils MCP

Développez votre propre application à partir des serveurs MCP (Model Context Protocol), y compris les MCP du schéma system.ai et les MCP que vous enregistrez. Votre application appelle des outils en tant qu'utilisateur connecté. La gouvernance de Unity Gateway contrôle les MCP et les outils que chaque utilisateur peut appeler.

Utilisez l'autorisation utilisateur lorsque votre application s'exécute sur Databricks Apps. Si votre application connecte les utilisateurs avec un fournisseur d'identité externe, utilisez la fédération de jetons OAuth pour obtenir un jeton Databricks. Ce guide concerne les applications qui desservent plusieurs utilisateurs. Pour créer et tester un agent localement avec vos propres informations d'identification, consultez Appeler des outils MCP à partir d'un agent Python.

Pour les MCP qui utilisent OAuth par utilisateur, les utilisateurs autorisent aussi leur compte fournisseur externe. Les étapes suivantes couvrent l'obtention du jeton Databricks et la connexion au fournisseur.

Configurer l’authentification et l’accès​

Avant d'ajouter du code, donnez aux utilisateurs l'accès aux MCP et configurez l'authentification de votre application.

Donner aux utilisateurs l'accès aux MCP​

Ces exigences s’appliquent aux deux méthodes d’authentification :

  • Ajoutez chaque utilisateur au Workspace Databricks. L’accès consommateur est suffisant pour appeler des MCP via Unity Gateway.
  • Accordez à chaque utilisateur EXECUTE sur les MCP, plus USE CATALOG et USE SCHEMA sur leur catalogue et leur schéma parents. Voir Partager un MCP.

Configurer l’authentification de votre application​

Choisissez l’option correspondant à votre application :

  1. Activez l'autorisation utilisateur pour l'application. Votre application utilise directement le jeton utilisateur Databricks transmis, sans échange de jetons ni politique de fédération de compte.
  2. Ajoutez les étendues d’autorisation utilisateur: ai-gateway pour les appels d’outils et unity-catalog pour les APIs de découverte et de statut de connexion.
  3. Attribuez à chaque utilisateur CAN USE sur l'application.

Le serveur de votre application doit aussi être en mesure d’atteindre le workspace. Si les listes d’accès IP sont activées, autorisez son IP sortante. Voir Réseau MCP.

system.ai.dbsql, system.ai.sandbox et system.ai.web_search sont en Bêta. Pour les utiliser, un administrateur de compte doit activer l’aperçu Enhanced Unity Gateway depuis la page Aperçus de la console de compte. Unity Gateway elle-même est en disponibilité générale. Consultez Gérer les aperçus de compte.

Configurez votre application​

Conservez le jeton et le client spécifiques à l’utilisateur connecté tout au long de ces étapes.

Obtenir un jeton Databricks pour l'utilisateur​

Choisissez l’option qui correspond à la manière dont votre application authentifie les utilisateurs. Les deux options vous fournissent databricks_token pour les étapes restantes.

Databricks Apps fournit le jeton Databricks de l'utilisateur dans l'en-tête de requête x-forwarded-access-token. Utilisez ce jeton directement. Votre application n'a pas besoin d'effectuer l'échange de jetons.

Lire le jeton dans la demande actuelle. Par exemple, dans un gestionnaire de requête Flask :

Python
from flask import request

databricks_token = request.headers.get("x-forwarded-access-token")
if not databricks_token:
raise ValueError("A Databricks user token is required.")

Pour d'autres frameworks, consultez Récupérer les informations d'identification d'autorisation utilisateur.

Lister les MCP​

Lister les MCP auxquelles l'utilisateur peut accéder dans un schéma. Pour les MCP fournies par Databricks, utilisez schemas/system.ai. Pour les MCP enregistrées, utilisez le schéma dans lequel elles sont enregistrées, tel que schemas/main.default.

Installez le SDK :

Bash
pip install --upgrade databricks-sdk

Créez un client avec le jeton de l'utilisateur et répertoriez les MCP :

Python
from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient(
host="https://<workspace-hostname>",
token=databricks_token,
auth_type="pat",
)

for service in workspace_client.ai_gateway.list_mcp_services(parent="schemas/system.ai"):
print(service.name)

Le paramètre auth_type="pat" du SDK sélectionne le jeton fourni au lieu des informations d'identification de l'environnement de l'application. Le jeton fourni est toujours le jeton OAuth de l'utilisateur. Créez un WorkspaceClient pour chaque utilisateur afin que chaque appel utilise le jeton de cet utilisateur. Les étapes suivantes réutilisent workspace_client. Le SDK gère la pagination pour vous.

Chaque name est un chemin de ressource de la forme mcp-services/<catalog>.<schema>.<service>, tel que mcp-services/system.ai.github. Passez-le inchangé à l’API de statut de connexion et utilisez-le pour construire l’URL MCP dans Appeler des outils. Voir Lister les services MCP.

Vérifier le statut de connexion de l’utilisateur​

Vérifiez chaque MCP utilisé par votre application. La réponse indique si le MCP utilise OAuth par utilisateur et, si c’est le cas, si l’utilisateur est connecté au fournisseur externe :

Obtenir les identifiants de l’utilisateur pour le MCP :

Python
from databricks.sdk.errors import InvalidParameterValue, NotFound
from databricks.sdk.service.catalog import ProvisioningInfoState

mcp_name = service.name # From List MCPs, for example "mcp-services/system.ai.github"

needs_sign_in = True
try:
credential = workspace_client.ai_gateway.get_mcp_service_user_mapped_credential(
name=mcp_name
)
signed_in = (
credential.provisioning_info is not None
and credential.provisioning_info.state == ProvisioningInfoState.ACTIVE
)
except NotFound:
signed_in = False
except InvalidParameterValue:
# The MCP doesn't use per-user OAuth.
needs_sign_in = False
signed_in = True
  • Si provisioning_info.state est ACTIVE, l’utilisateur est connecté. Allez sur Outils d’appel.
  • Si la demande retourne NOT_FOUND ou si l’état est autre que ACTIVE, afficher un bouton de connexion pour le MCP.
  • Si la demande renvoie INVALID_PARAMETER_VALUE, le MCP n'utilise pas OAuth par utilisateur, l'utilisateur n'a donc pas besoin de se connecter. C’est le cas pour les MCP de données et d’outils Databricks. Accédez à Appeler des outils.

Consultez Obtenir les identifiants de l'appelant.

Connecter l'utilisateur au fournisseur​

Lorsque l’utilisateur clique sur votre bouton de connexion, ouvrez la page de connexion du MCP dans une fenêtre contextuelle. Le parameter name de la page est le nom du MCP sans le préfixe mcp-services/, comme system.ai.github. L’utilisateur se connecte sur cette page et autorise l’accès sur l’écran de consentement du fournisseur.

JavaScript
// mcpName is the MCP name without the mcp-services/ prefix, for example "system.ai.github"
const signInUrl = `https://${workspaceHostname}/mcp-service-login?name=${encodeURIComponent(mcpName)}`;
window.open(signInUrl, 'mcp-sign-in', 'popup,width=600,height=700');

La page de connexion ne renvoie pas de message à votre application. Pour détecter la fin de la connexion, vérifiez à nouveau l'état de la connexion lorsque l'utilisateur revient dans votre application.

La page de connexion utilise la session de navigateur Databricks de l’utilisateur. Si l’utilisateur n’est pas connecté au workspace dans ce navigateur, Databricks lui demande de se connecter en premier. Les informations d’identification du fournisseur sont enregistrées pour l’utilisateur qui est connecté sur la page ; cet utilisateur doit donc être le même que celui pour lequel votre application agit.

Appeler des outils​

Envoyez les requêtes MCP à l’URL du MCP avec le jeton Databricks de l’utilisateur. L’URL MCP est https://<workspace-hostname>/ai-gateway/ suivie du nom de Liste des MCP, par exemple https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github.

Votre application peut appeler des outils directement, comme indiqué à cette étape, ou les donner à un agent qui décide quels outils appeler. Pour exécuter un agent, suivez l’ étape 3 : Exécuter un agent avec ces outils et transmettez le workspace_client que vous avez créé avec le jeton de l’utilisateur dans Répertorier les MCP, afin que l’agent appelle les outils en tant que cet utilisateur. Les frameworks d’agent utilisent la version 1 du SDK MCP Python, donc installez les packages listés sur cette page.

Installez les packages :

Bash
pip install --upgrade databricks-mcp

Connectez-vous avec le workspace_client de l'utilisateur à partir de la liste des MCP, puis listez et appelez les outils :

Python
from databricks_mcp import DatabricksMCPClient

mcp_name = "mcp-services/system.ai.github" # A name from List MCPs

mcp_client = DatabricksMCPClient(
server_url=f"https://<workspace-hostname>/ai-gateway/{mcp_name}",
workspace_client=workspace_client,
)

for tool in mcp_client.list_tools():
print(f"{tool.name}: {tool.description}")

result = mcp_client.call_tool("<tool-name>", arguments={})
print(result.isError)
print(result.content)

Découvrez les noms des outils et les schémas d’entrée avec list_tools() avant d’appeler un outil, et vérifiez si chaque résultat est une erreur : result.isError avec databricks-mcp, ou result.is_error avec la version 2 du SDK MCP Python. Pour savoir comment lire les résultats, consultez Appeler un outil directement pour le dépannage. Si la liste des outils est vide ou si la connexion échoue, consultez Authentification MCP.

Ressources supplémentaires​