Aller au contenu principal

Appeler des outils MCP à partir d'un agent Python

Utilisez les outils MCP dans un agent Python personnalisé construit avec LangGraph, le SDK OpenAI Agents ou le client OpenAI. Les exemples montrent comment se connecter, découvrir des outils et exécuter un agent localement avec vos propres informations d’identification Databricks.

Pour une application qui appelle des outils au nom d’utilisateurs connectés, consultez Connectez votre application aux outils MCP.

Pour d’autres méthodes de connexion, consultez Agents de codage et de travail pris en charge, Autres clients MCP ou Ajouter des outils MCP avec l’interface de ligne de commande Agent Bricks CLI.

Prerequisites​

system.ai.dbsql, system.ai.sandbox et system.ai.web_search sont en Beta. Pour les utiliser, un administrateur de compte doit activer l’aperçu Enhanced Unity Gateway à partir de la page Aperçus de la console de compte. Unity Gateway lui-même est généralement disponible. Consultez Gérer les aperçus du compte.

Pour les choix d’identité, voir Authentification sortante prise en charge. Pour les exigences de connectivité, voir Réseautage MCP.

Étape 1 : Installer et se connecter​

  1. Si vous n’avez pas installé la CLI Databricks, exécutez cette commande sur macOS ou Linux :

    Bash
    curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sh

    Pour Windows ou d’autres méthodes d’installation, consultez Installer la CLI Databricks.

  2. Connectez-vous à votre workspace :

    Bash
    databricks auth login --host https://<workspace-hostname> --profile DEFAULT
  3. Installez les bibliothèques Python :

    Bash
    pip install --upgrade databricks-mcp databricks-sdk "mcp>=1.24,<2"

Les exemples utilisent MCP Python 1.x, qui est compatible avec les frameworks d’agents ci-dessous.

Étape 2 : Connectez-vous à votre serveur​

Enregistrez le code suivant sous mcp_agent.py. Remplacez <mcp-server-url> par l'URL de votre serveur :

  • MCP fourni par Databricks ou MCP enregistré : https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>.
  • Server on Databricks Apps : copiez l’URL de l’application depuis sa page de présentation et ajoutez /mcp à la fin.
  • Endpoint MCP du Workspace: https://<workspace-hostname> suivi de l'un de ces chemins :
    • Fonctions Unity Catalog : /api/2.0/mcp/functions/{catalog}/{schema}/{function_name}
    • Recherche IA : /api/2.0/mcp/ai-search/{catalog}/{schema}/{index_name}
    • Genie Agent : /api/2.0/mcp/genie/{genie_space_id}
    • Databricks SQL : /api/2.0/mcp/sql
Python
from databricks_mcp import DatabricksMCPClient
from databricks.sdk import WorkspaceClient

workspace_client = WorkspaceClient()
server_url = "<mcp-server-url>"
mcp_client = DatabricksMCPClient(
server_url=server_url,
workspace_client=workspace_client,
)

tools = mcp_client.list_tools()
for tool in tools:
print(tool.name, tool.description, tool.inputSchema, sep="\n")

Exécutez le script :

Bash
python mcp_agent.py

Vous devriez voir les outils de votre serveur, avec leurs descriptions et leurs schémas d'entrée. Choisissez une tâche en lecture seule prise en charge par l'un de ces outils pour l'étape suivante. Si la liste est vide ou si la connexion échoue, consultez l'authentification MCP.

Utilisez un autre serveur​

Pour trouver les MCP accessibles dans un catalogue et un schéma, exécutez :

Bash
databricks ai-gateway list-mcp-services --parent schemas/system.ai

Remplacez system.ai par votre <catalog>.<schema> pour répertorier les MCP enregistrés. La CLI gère la pagination.

Étape 3 : Exécutez un agent avec ces outils​

Choisissez votre framework, installez son package et ajoutez son exemple Python à mcp_agent.py. Chaque exemple utilise les mêmes paramètres server_url et la même connexion au workspace de l'étape 2.

L’exemple utilise un intergiciel de modèle qui convertit les blocs de contenu MCP au format de message de chat du modèle avec convert_to_openai_messages.

Bash
pip install --upgrade "databricks-langchain==0.22.0" "langgraph==1.2.20" "mcp>=1.24,<2"
Python
import asyncio
from databricks_langchain import (
ChatDatabricks,
DatabricksMCPServer,
DatabricksMultiServerMCPClient,
)
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call
from langchain_core.messages import convert_to_messages, convert_to_openai_messages

@wrap_model_call
async def convert_mcp_content(request, handler):
messages = convert_to_messages(convert_to_openai_messages(request.messages))
return await handler(request.override(messages=messages))

async def main():
client = DatabricksMultiServerMCPClient([
DatabricksMCPServer(
name="my-mcp-server",
url=server_url,
workspace_client=workspace_client,
),
])
agent = create_agent(
model=ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
tools=await client.get_tools(),
middleware=[convert_mcp_content],
)
task = input("Ask the agent to use a tool: ")
result = await agent.ainvoke({
"messages": [{"role": "user", "content": task}],
})
for message in result["messages"]:
print(message)

asyncio.run(main())

Notebook de déploiement (facultatif)

Pour le déploiement de Model Serving, adaptez ce notebook afin d’utiliser l’URL de votre serveur :

LangGraph MCP tool-calling agent

Exécutez de nouveau python mcp_agent.py. Lorsque vous y êtes invité, demandez la tâche en lecture seule que vous avez choisie, en incluant les entrées requises. Par exemple, si votre serveur dispose d'un outil de recherche de tickets, demandez-lui de trouver les tickets ouverts dans un projet spécifique.

Vérifiez la conversation imprimée pour y trouver l'appel d'outil, son résultat et la réponse de l'agent. Une réponse sans appel d'outil ne confirme pas que le serveur MCP a été utilisé.

Call a tool directly to troubleshoot​

Utilisez le nom de l'outil et le schéma d'entrée affichés à l'étape 2. Cet exemple demande le nom et les arguments afin de fonctionner avec les outils de votre serveur. Exécutez-le après le code de connexion de l'étape 2 :

Python
import json

tool_name = input("Read-only tool name: ")
arguments = json.loads(input("Tool arguments as a JSON object: "))
result = mcp_client.call_tool(tool_name, arguments)
print(result)

Vérifiez que le résultat ne comporte pas d'erreur d'outil et qu'il contient les données attendues.

Découvrez les noms d’outils et les schémas d’entrée avec list_tools() avant d’appeler un outil. Les formats de résultat varient selon l’outil :

  • Si structuredContent est présent, utilisez directement ce résultat structuré. Un outil peut décrire sa forme avec outputSchema.
  • Sinon, inspectez les blocs content. Analysez un bloc de texte au format JSON uniquement si l'outil renvoie du JSON. MCP prend également en charge le texte brut et d'autres types de contenu.
  • Vérifiez isError et inspectez un exemple de réponse avant de vous fier à des champs de sortie particuliers.

Déployez et partagez lorsque vous êtes prêt​

L'exemple local s'exécute en tant que vous-même. Lorsque vous déployez l'agent sur Databricks Apps, choisissez l'identité qu'il utilise: le service principal de l'application pour un accès partagé, ou l'utilisateur appelant pour un accès par utilisateur.

Pour les MCP fournis ou enregistrés par Databricks :

Pour les endpoints MCP de Workspace ou les serveurs hébergés sur Databricks Apps, accordez l'accès aux ressources ou à l'application sous-jacentes. Consultez Authentification de l'agent.

Ressources supplémentaires​