Introduction

Connecter MCP à un agent IA consiste à fournir à celui-ci un moyen contrôlé de découvrir et d’utiliser des capacités qui résident en dehors du modèle. Le modèle n’exécute pas directement une requête de base de données, ne lit pas un fichier privé et n’appelle pas une API métier. À la place, un client MCP intégré à l’agent se connecte à un serveur MCP, obtient les définitions des outils du serveur, transmet ces définitions au modèle en tant que capacités disponibles, puis exécute l’appel d’outil sélectionné par le modèle.

Cette séparation crée une frontière importante. Le modèle est chargé d’interpréter la demande de l’utilisateur et de proposer un nom d’outil avec des arguments structurés. Le client MCP est chargé de maintenir la session du protocole, d’invoquer l’outil sélectionné, de retourner le résultat et de signaler les erreurs. Un workflow fiable comporte donc trois étapes distinctes : découverte, sélection et invocation. Le même modèle fonctionne que le modèle soit hébergé par une API commerciale, un modèle auto-hébergé ou un framework d’agents interne.

MCP ne dispense pas des exigences de sécurité au niveau de l’application. Un agent ne doit se connecter qu’à des serveurs de confiance, appliquer une authentification lorsque cela est nécessaire, vérifier les autorisations de l’utilisateur et éviter d’approuver automatiquement les opérations dangereuses. La description d’un outil aide le modèle à choisir une capacité, mais ne constitue pas une politique de sécurité.

Le workflow agentique

Au démarrage, le client MCP ouvre une connexion de transport avec le serveur et initialise une session MCP. Le client appelle ensuite l’opération de découverte des outils définie par le protocole. La réponse contient les noms des outils, leurs descriptions et leurs schémas d’entrée. Ces schémas décrivent les arguments acceptés par un outil, ce qui permet à l’agent de fournir au modèle des informations structurées plutôt qu’un paragraphe informel.

Le modèle utilise les définitions découvertes avec la demande de l’utilisateur. Par exemple, si le serveur expose un outil search_documents et un outil create_ticket, une demande visant à trouver un rapport d’incident devrait normalement produire un appel à search_documents, et non à create_ticket. La sortie du modèle doit être considérée comme un appel d’outil proposé, contenant un nom et des arguments. L’application hôte doit néanmoins vérifier que le nom a bien été découvert et que les arguments respectent la politique locale avant de l’invoquer.

Après validation, le client MCP appelle l’outil sélectionné et reçoit un contenu structuré, du texte ou une erreur. L’application hôte peut renvoyer ce résultat au modèle afin de générer une réponse finale en langage naturel. Un agent exécutant plusieurs étapes répète ce cycle lorsque le résultat du premier outil fournit les informations nécessaires à un second outil. L’application doit imposer des limites au nombre d’étapes, au temps d’exécution et aux opérations sensibles afin d’éviter les boucles incontrôlées.

Un client MCP minimal

Le programme Python suivant présente la découverte, la sélection et l’invocation via Streamable HTTP. Il utilise les interfaces officielles du client Python MCP pour établir une session client et un transport. Installez le package Python MCP dans l’environnement qui exécute l’agent, puis remplacez l’URL par celle d’un serveur MCP déjà démarré et configuré pour accepter ce transport.

import argparse
import asyncio
import json

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


async def run(url: str, tool_name: str, arguments: dict) -> None:
    async with streamable_http_client(url) as streams:
        read_stream, write_stream, _ = streams

        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            discovered = await session.list_tools()

            print("Discovered tools:")
            for tool in discovered.tools:
                description = tool.description or "No description"
                print(f"- {tool.name}: {description}")

            selected = next(
                (tool for tool in discovered.tools if tool.name == tool_name),
                None,
            )
            if selected is None:
                available = ", ".join(tool.name for tool in discovered.tools)
                raise ValueError(
                    f"Unknown tool '{tool_name}'. Available tools: {available}"
                )

            print(f"Invoking {selected.name} with {json.dumps(arguments)}")
            result = await session.call_tool(
                selected.name,
                arguments=arguments,
            )
            print("Tool result:")
            if hasattr(result, "model_dump_json"):
                print(result.model_dump_json(indent=2))
            else:
                print(result)


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("url", help="MCP Streamable HTTP endpoint")
    parser.add_argument("tool", help="Discovered tool name to invoke")
    parser.add_argument(
        "--arguments",
        default="{}",
        help="JSON object containing tool arguments",
    )
    args = parser.parse_args()

    try:
        arguments = json.loads(args.arguments)
    except json.JSONDecodeError as error:
        raise SystemExit(f"Arguments must be valid JSON: {error}") from error

    if not isinstance(arguments, dict):
        raise SystemExit("Arguments must be a JSON object")

    try:
        asyncio.run(run(args.url, args.tool, arguments))
    except Exception as error:
        raise SystemExit(f"MCP request failed: {error}") from error


if __name__ == "__main__":
    main()

L’entrée se compose d’un endpoint MCP, du nom d’un outil et d’un objet JSON contenant les arguments. Le programme affiche d’abord les outils renvoyés par la découverte, puis vérifie que le nom demandé est bien présent. Cette vérification est importante, car un modèle peut inventer un nom d’outil ou conserver un ancien nom d’une session précédente. La sortie inclut le résultat du serveur, que l’agent environnant peut transmettre au modèle pour interprétation.

Relier la découverte à la sélection du modèle

Dans un agent de production, un adaptateur de modèle est placé entre la découverte et l’invocation. Une fois que list_tools a renvoyé son résultat, l’hôte convertit le nom, la description et le schéma d’entrée de chaque outil au format d’appel d’outils du fournisseur du modèle. Le format exact de la requête dépend de l’API du modèle ; le client MCP ne doit donc pas supposer que tous les fournisseurs utilisent la même structure de messages. L’agent reçoit la réponse du modèle, extrait le nom proposé et les arguments JSON, puis effectue une validation locale avant d’appeler session.call_tool.

L’hôte doit rejeter un appel d’outil lorsque le nom est absent de la réponse de découverte actuelle, lorsque les arguments ne sont pas un objet, lorsque des champs obligatoires sont manquants ou lorsqu’une valeur enfreint la politique de l’application. La validation du schéma est utile, mais les contrôles d’autorisation doivent être effectués séparément. Par exemple, un appel valide à delete_record peut malgré tout être interdit à un utilisateur disposant d’un accès en lecture seule. Une confirmation est également appropriée pour les actions irréversibles, les opérations financières, les messages externes ou les modifications de données en production.

Après l’invocation, le résultat peut être ajouté à la conversation avec le modèle sous la forme d’un message de résultat d’outil. Le modèle peut alors résumer le résultat ou déterminer si un autre outil autorisé est nécessaire. Conservez le résultat brut pour la journalisation, mais masquez les identifiants, les données personnelles et les diagnostics internes avant d’envoyer le contenu à un modèle tiers.

Échecs courants et pratiques fiables

Un échec de connexion signifie généralement que l’endpoint est incorrect, que le serveur est indisponible, que le transport ne correspond pas à la configuration ou que l’authentification est absente. Vérifiez que le serveur prend en charge le transport sélectionné et que les paramètres réseau, proxy et TLS autorisent la connexion. Ne résolvez pas un problème de transport en basculant silencieusement vers un protocole inconnu ; rendez le transport configuré explicite et signalez l’erreur d’origine.

Une erreur d’outil inconnu se produit lorsque l’agent invoque un nom qui n’a pas été renvoyé lors de l’étape de découverte actuelle. Actualisez la découverte lorsque les sessions ou les capacités du serveur peuvent changer, et comparez toujours le nom demandé avec l’ensemble actuel des outils. Des arguments invalides résultent souvent de propriétés obligatoires manquantes, de types incorrects ou du renvoi par le modèle d’un JSON encodé sous forme de chaîne au lieu d’un objet. Validez et normalisez les arguments avant l’invocation, puis conservez le message d’erreur utile du serveur pour faciliter le débogage.

Une autre erreur courante consiste à exposer les outils de tous les serveurs connectés à chaque utilisateur. Les noms et descriptions des outils peuvent se chevaucher, et un serveur malveillant ou mal configuré peut présenter une capacité dangereuse. Utilisez une liste blanche explicite de serveurs, isolez les identifiants, appliquez une autorisation par outil, définissez des délais d’expiration, limitez les appels répétés et enregistrez l’utilisateur, la décision du modèle, le serveur et l’outil concernés. Ces contrôles rendent le comportement de l’agent observable et facilitent sa revue.

Résumé

Un agent compatible avec MCP se comprend au mieux comme une application hôte composée de deux éléments coopérants. Le modèle interprète l’intention de l’utilisateur et propose un appel structuré, tandis que le client MCP découvre les capacités disponibles et exécute les opérations conformément au protocole. Le client ne doit jamais supposer qu’un outil existe simplement parce que le modèle l’a mentionné ; il doit découvrir les outils actuels, valider la sélection et les arguments, puis appliquer la politique locale avant l’invocation.

Le flux de travail pratique consiste à initialiser la session, lister les outils, présenter leurs schémas au modèle, valider l’appel proposé par le modèle, invoquer l’outil sélectionné et renvoyer le résultat pour le raisonnement final. Une fois cette boucle fonctionnelle avec un serveur, elle peut être étendue à plusieurs serveurs et à des tâches en plusieurs étapes sans modifier la limite fondamentale. Les choix d’implémentation les plus importants restent une configuration explicite du transport, une validation stricte, une autorisation sûre, une exécution limitée et des rapports d’erreur utiles.