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 :

Databricks Apps

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.

External identity provider

Si votre application possède déjà un jeton OAuth Databricks pour l'utilisateur, utilisez-le directement et ignorez la configuration de la fédération et l'échange de jetons. Le jeton a besoin des portées ai-gateway et unity-catalog pour les APIs de ce guide. Sinon, suivez ces étapes :

1. Demandez à un administrateur de compte de configurer une politique de fédération de compte pour votre fournisseur d'identité. La politique définit l'émetteur, l'audience et le mappage d'utilisateurs acceptés.
2. Obtenez un jeton pour l'utilisateur connecté auprès de votre fournisseur d'identité. La première étape du code l'échange contre un jeton OAuth Databricks avec all-apis, qui couvre les APIs utilisées dans ce guide.

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.

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 à partir de la page Previews de la console de compte. Consultez Gérer les aperçus du 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

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.

External identity provider

Si vous disposez déjà d'un jeton OAuth Databricks pour l'utilisateur, utilisez-le directement. Sinon, échangez le jeton du fournisseur d'identité de l'utilisateur contre un jeton OAuth Databricks :

Python

import requests

response = requests.post(
    "https://<workspace-hostname>/oidc/v1/token",
    data={
        "subject_token": idp_token,
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "scope": "all-apis",
    },
)
response.raise_for_status()
databricks_token = response.json()["access_token"]

Utilisez databricks_token dans les étapes suivantes. L’échange ne renvoie pas de jeton de refresh. Utilisez expires_in à partir de la réponse pour suivre l’expiration et répétez l’échange avec un jeton de fournisseur d’identité valide si nécessaire. Voir Exigences et limitations de l’échange de jetons.

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.

Databricks SDK

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.

Python

Appelez l'API REST avec le jeton de l'utilisateur et listez les MCP :

Python

import requests

url = "https://<workspace-hostname>/api/2.1/unity-catalog/mcp-services"
headers = {"Authorization": f"Bearer {databricks_token}"}
params = {"parent": "schemas/system.ai"}

while True:
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    body = response.json()
    for service in body.get("mcp_services", []):
        print(service["name"])
    if not body.get("next_page_token"):
        break
    params["page_token"] = body["next_page_token"]

Voir Liste des services MCP.

Vérifier le statut de connexion de l’utilisateur

Pour les MCP qui utilisent OAuth par utilisateur, tel que system.ai.github, vérifiez si l'utilisateur est connecté au fournisseur externe :

Databricks SDK

Obtenir les identifiants de l’utilisateur pour le MCP :

Python

from databricks.sdk.errors import NotFound
from databricks.sdk.service.catalog import ProvisioningInfoState

try:
    credential = workspace_client.ai_gateway.get_mcp_service_user_mapped_credential(
        name="mcp-services/system.ai.github"
    )
    signed_in = (
        credential.provisioning_info is not None
        and credential.provisioning_info.state == ProvisioningInfoState.ACTIVE
    )
except NotFound:
    signed_in = False

Python

Appelez l’API REST avec le jeton de l’utilisateur :

Python

import requests

response = requests.get(
    "https://<workspace-hostname>/api/2.1/unity-catalog/mcp-services/system.ai.github/user-credentials",
    headers={"Authorization": f"Bearer {databricks_token}"},
)
if response.status_code == 404:
    signed_in = False
else:
    response.raise_for_status()
    signed_in = response.json().get("provisioning_info", {}).get("state") == "ACTIVE"

• 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.

Les MCP qui n’utilisent pas OAuth par utilisateur, comme les MCP de données et d’outils Databricks, n’ont pas besoin de cette étape. Voir 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. L'utilisateur se connecte sur cette page et autorise l'accès sur l'écran de consentement du fournisseur.

JavaScript

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 des requêtes MCP à l’URL du MCP, https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>, avec le jeton Databricks de l’utilisateur.

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.

Databricks SDK

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_client = DatabricksMCPClient(
    server_url="https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github",
    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)

Python

Cet exemple utilise la version 2 du SDK Python MCP:

Bash

pip install --upgrade "mcp>=2"

Ouvrez une session avec le jeton de l'utilisateur, puis répertoriez et appelez les outils :

Python

import asyncio

import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

MCP_URL = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.github"


async def main(databricks_token):
    http_client = httpx2.AsyncClient(headers={"Authorization": f"Bearer {databricks_token}"})
    async with http_client, streamable_http_client(MCP_URL, http_client=http_client) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            result = await session.list_tools()
            for tool in result.tools:
                print(f"{tool.name}: {tool.description}")

            result = await session.call_tool("<tool-name>", arguments={})
            print(result)


asyncio.run(main(databricks_token))

Découvrez les noms des outils et les schémas d’entrée avec list_tools() avant d’appeler un outil, et vérifiez isError sur chaque résultat. Pour savoir comment lire les résultats, consultez Appeler directement un outil pour résoudre les problèmes. Si la liste des outils est vide ou si la connexion échoue, voir Authentification MCP.

Ressources supplémentaires

• Référence de l’API et du SDK MCP
• Connexion à un fournisseur externe
• Appeler des outils MCP à partir d'un agent Python
• Authentification pour les agents