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
EXECUTEsur les MCP, plusUSE CATALOGetUSE SCHEMAsur 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
- External identity provider
- 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.
- Ajoutez les étendues d’autorisation utilisateur:
ai-gatewaypour les appels d’outils etunity-catalogpour les APIs de découverte et de statut de connexion. - Attribuez à chaque utilisateur CAN USE sur l'application.
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 :
- 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.
- 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.
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
- External identity provider
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 :
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.
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 :
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
- Python
Installez le SDK :
pip install --upgrade databricks-sdk
Créez un client avec le jeton de l'utilisateur et répertoriez les MCP :
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.
Appelez l'API REST avec le jeton de l'utilisateur et listez les MCP :
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"]
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 :
- Databricks SDK
- Python
Obtenir les identifiants de l’utilisateur pour le MCP :
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
Appelez l’API REST avec le jeton de l’utilisateur :
import requests
mcp_name = service["name"] # From List MCPs, for example "mcp-services/system.ai.github"
response = requests.get(
f"https://<workspace-hostname>/api/2.1/unity-catalog/{mcp_name}/user-credentials",
headers={"Authorization": f"Bearer {databricks_token}"},
)
needs_sign_in = True
if response.status_code == 404:
signed_in = False
elif (
response.status_code == 400
and response.json().get("error_code") == "INVALID_PARAMETER_VALUE"
):
# The MCP doesn't use per-user OAuth.
needs_sign_in = False
signed_in = True
else:
response.raise_for_status()
signed_in = response.json().get("provisioning_info", {}).get("state") == "ACTIVE"
- Si
provisioning_info.stateestACTIVE, l’utilisateur est connecté. Allez sur Outils d’appel. - Si la demande retourne
NOT_FOUNDou si l’état est autre queACTIVE, 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.
// 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.
- Databricks SDK
- Python
Installez les packages :
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 :
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)
Cet exemple utilise la version 2 du SDK Python MCP:
pip install --upgrade "mcp>=2"
Ouvrez une session avec le jeton de l'utilisateur, puis répertoriez et appelez les outils :
import asyncio
import httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
mcp_name = "mcp-services/system.ai.github" # A name from List MCPs
MCP_URL = f"https://<workspace-hostname>/ai-gateway/{mcp_name}"
async def main(databricks_token):
http_client = httpx2.AsyncClient(
timeout=120.0,
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.is_error)
print(result.content)
asyncio.run(main(databricks_token))
Les appels d'outils via Unity Gateway peuvent prendre plus de temps que le délai d'expiration default de 5 secondes de httpx2.AsyncClient. Définissez donc un timeout plus long sur le client.
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.