AI SDK + MCP : guide pratique d’intégration pour des systèmes d’agents en production

Points clés

• Une intégration AI SDK + MCP ne se résume pas à "connecter et appeler". Le vrai travail porte sur le scope, le transport, les retries, l’auth et l’observabilité.
• Le meilleur point de départ reste une discovery étroite, des allowlists explicites et des budgets d’exécution stricts.
• MCP améliore discovery et invocation, mais l’application doit toujours décider quelles capacités exposer à quel workflow.
• Un système d’agents en production a besoin de choix explicites sur timeout, fallback et logging avant le premier incident.
• puppyone devient utile quand un même workflow a besoin à la fois de contexte gouverné et de tools exposés via MCP.

Pourquoi c’est simple en démo et plus difficile en production

Le scénario de démo est toujours séduisant :

1. connecter l’AI SDK à un serveur MCP
2. exposer quelques tools
3. laisser le modèle les appeler

C’est un bon prototype. Ce n’est pas encore une intégration de production.

En production, ce ne sont pas les lignes de code qui augmentent le plus, mais les décisions à assumer :

• quels tools cet agent peut-il voir ?
• quel transport est acceptable dans cet environnement ?
• comment gère-t-on l’authentification et la rotation ?
• que se passe-t-il si le serveur MCP est lent ?
• quel fallback appliquer en cas d’échec ?
• quels appels exigent une approbation humaine ?
• comment expliquer un run après un problème ?

L’architecture minimale qui compte vraiment

user request
  -> agent runtime dans votre application
  -> politique d’outils par workflow
  -> client MCP
  -> un ou plusieurs serveurs MCP
  -> systèmes externes ou contexte gouverné
  -> assemblage du résultat
  -> logs, approbations et traces

La ligne que beaucoup sautent est la politique d’outils.

La discovery relève du protocole. L’exposition relève du produit.

Les cinq décisions les plus importantes

1. Discovery n’est pas permission

Ce n’est pas parce que le SDK découvre vingt tools qu’un workflow doit en voir vingt.

Il faut traiter la discovery comme le superset et l’allowlist runtime comme la vraie frontière d’exécution.

2. Le transport est un choix de fiabilité

La documentation actuelle de l’AI SDK recommande HTTP pour la production et réserve plutôt stdio aux serveurs locaux. Cela change la façon de penser les firewalls, les retries, le proxying et l’ownership opérationnel.

La règle la plus saine est souvent la plus simple :

• utiliser le transport le plus simple que l’environnement sait opérer proprement
• borner les retries
• rendre explicite le comportement au timeout

3. Les descriptions de tools changent le comportement du modèle

Des descriptions vagues donnent un usage vague. Si deux tools se chevauchent, le modèle dépense ses tokens à arbitrer au lieu de résoudre la tâche.

Il faut décrire un tool comme un opérateur prudent :

• ce qu’il fait
• ce qu’il ne fait pas
• quand l’utiliser
• quelles entrées sont requises
• à quoi ressemble un échec

4. Chaque appel doit avoir un budget

Le modèle ne devrait pas pouvoir :

• appeler dix tools quand deux suffisent
• réessayer à l’infini
• tirer des payloads gigantesques dans le prompt
• mélanger sans garde-fou des tools en lecture seule et des tools d’écriture

5. Les logs font partie de la fonctionnalité

Il faut plus que "le modèle a mal choisi". Il faut au minimum :

• un request ID
• la liste des tools exposés
• le tool réellement choisi
• les arguments envoyés
• la latence et les erreurs
• l’état d’approbation si besoin

Un tableau qui évite beaucoup d’erreurs

La règle pratique est simple :

• discovery large pour explorer
• bundles explicites par workflow pour produire

Où puppyone s’insère

Quand le système a besoin à la fois de contexte gouverné et de tool calling, puppyone se place au bon niveau :

• préparer une fois un contexte structuré
• l’exposer via MCP ou API
• ne rendre visibles que les capacités nécessaires au workflow
• garder le chemin de décision inspectable

Une séquence de rollout raisonnable

Déployez AI SDK + MCP dans cet ordre :

1. un workflow en lecture seule
2. un serveur MCP
3. une allowlist explicite
4. un budget de latence
5. un chemin de logging

Puis ajoutez :

• les actions d’écriture
• les approbations
• les fallbacks
• le routage multi-serveur
• les bundles par rôle

FAQs

Q1: MCP remplace-t-il les tools natifs du SDK ?

Non. MCP fournit une manière standard de découvrir et d’utiliser des capacités externes. Les tools natifs de l’application peuvent rester en place.

Q2: Faut-il exposer tous les tools MCP découverts à chaque intégration AI SDK ?

Non. La discovery doit être resserrée en allowlist runtime. Exposer tout le catalogue nuit généralement à la fiabilité.

Q3: Quel signal de production surveiller en premier ?

Commencez par la qualité de sélection des tools et la latence. Si le modèle choisit mal ou attend trop longtemps, la qualité perçue baisse très vite.