Outil MCP : appeler des serveurs MCP distants depuis vos requêtes

Ajoutez une entrée type: "mcp" au tableau tools d'une requête POST /v1/responses. Donnez-lui un server_label, qui nomme le serveur dans la sortie, et la server_url d'un serveur MCP distant utilisant le transport HTTP en streaming. Une server_description facultative aide le modèle à juger quand le serveur est utile.

À l'exécution, l'API récupère la liste des outils du serveur et la met à disposition du modèle. Si le modèle choisit un outil, l'API appelle le serveur, transmet le résultat au modèle et poursuit jusqu'à obtenir une réponse. Les appels partent de notre infrastructure dans l'UE.

La plupart des serveurs exigent des identifiants. Passez-les dans headers, par exemple un en-tête Authorization avec un jeton propre au service. Les en-têtes servent à l'appel et ne sont pas renvoyés dans la réponse, mais utilisez un jeton aux droits aussi restreints que possible.

allowed_tools limite les outils du serveur visibles par le modèle, ce qui allège le prompt et rend le comportement prévisible. require_approval indique si un appel doit d'abord être validé : never exécute les appels automatiquement, always suspend chacun d'eux, et un objet avec des listes always et never règle cela outil par outil. Exigez une validation pour les outils qui modifient des données, comme créer un ticket ou envoyer un message.

Le tableau output retrace les étapes dans l'ordre. Un élément mcp_list_tools consigne les outils proposés par le serveur. Chaque appel apparaît comme élément mcp_call avec le server_label, le name de l'outil, les arguments JSON et l'output renvoyé par le serveur, ou une error. L'élément final message contient la réponse, également accessible via output_text dans les SDK.

Lorsqu'une validation est requise, la réponse contient à la place un élément mcp_approval_request. Pour poursuivre, envoyez une nouvelle requête avec previous_response_id et un élément d'entrée de type mcp_approval_response qui reprend l'id de la demande et règle approve sur true ou false.

Si le serveur est injoignable, refuse les identifiants ou renvoie une liste d'outils invalide, la requête échoue avec une erreur qui cite le server_label, ou l'élément mcp_call porte l'erreur pour que le modèle puisse l'expliquer. Vérifiez que l'URL est publique en HTTPS et que le jeton est valide.

Le modèle voit tout ce que renvoie le serveur : ne connectez que des serveurs de confiance, car une sortie d'outil peut contenir des instructions cherchant à orienter le modèle. Les longues listes d'outils et les gros résultats consomment des tokens d'entrée, filtrez donc avec allowed_tools. Les données envoyées à un serveur MCP tiers sont traitées par ce service selon ses propres conditions ; vérifiez où il est hébergé.