Anthropic Agent SDK avec TypeScript : architecture et sécurité MCP

Un agent TypeScript sécurisé fondé sur les outils Anthropic doit traiter les serveurs MCP et les résultats des outils comme des domaines de confiance distincts. Gardez les identifiants hors des prompts, n'autorisez que les serveurs et outils approuvés, validez chaque argument, exigez une approbation pour les écritures aux conséquences importantes et vérifiez les postconditions. Les API exactes du SDK et les versions des paquets peuvent évoluer : confirmez donc les détails d'implémentation dans la documentation officielle à jour.

Cartographiez l'environnement d'exécution avant d'écrire du code

Commencez par dessiner les composants : interface utilisateur, environnement d'exécution de l'agent, fournisseur du modèle, clients MCP, serveurs MCP, outils locaux ou distants, magasins de données et service d'approbation. Indiquez où l'identité est établie, où résident les secrets et quel composant peut produire des effets externes. Ce modèle de menaces est plus utile que de commencer par une longue liste d'outils.

En TypeScript, définissez des types métier pour les requêtes, les entrées d'outils, les résultats, les erreurs et les justificatifs d'approbation. La validation à l'exécution reste nécessaire, car les types statiques disparaissent aux frontières entre processus. Un schéma JSON ou une bibliothèque de validation doit refuser les champs inconnus, les énumérations invalides, les valeurs trop volumineuses et les URL inattendues avant l'exécution d'un outil.

Frontières MCP et confiance accordée aux serveurs

MCP standardise l'échange de contexte, mais une connexion au protocole ne constitue pas une recommandation. Répertoriez chaque serveur, son propriétaire, son transport, sa version, ses outils disponibles et l'accès aux données requis. Préférez une configuration explicite à la découverte automatique. Épinglez les dépendances et examinez les changements apportés aux descriptions des outils, car ces descriptions influencent la sélection du modèle.

Appliquez le principe du moindre privilège. Un lecteur de dépôt n'a pas besoin d'un accès shell ; un outil qui résume des tickets n'a pas besoin de pouvoir les modifier. Séparez les serveurs de lecture et d'écriture lorsque c'est possible. Pour les transports distants, vérifiez l'authentification, TLS, l'audience et les frontières entre tenants selon les recommandations officielles actuelles. Pour les transports locaux, protégez les chemins exécutables, les variables d'environnement et les répertoires de travail.

Schémas d'outils, approbations et transactions

Le nom d'un outil doit décrire une seule action. Les entrées doivent utiliser des énumérations strictes et des chaînes limitées plutôt que des commandes libres. Résolvez les identifiants de ressources dans du code de confiance. Ne laissez pas le modèle construire des chemins de fichiers, du SQL, des fragments shell ou des URL de callback arbitraires. Pour les écritures, renvoyez un aperçu afin que l'utilisateur puisse inspecter précisément la cible et la charge utile.

Liez l'approbation à cet aperçu avec un nonce, une expiration, un acteur et un hash. Si la charge utile change, l'approbation devient invalide. Utilisez des clés d'idempotence et vérifiez l'état après l'écriture. Lorsqu'un délai d'attente réseau laisse le résultat incertain, consultez l'état actuel avant de réessayer. Vous éviterez ainsi les commentaires, commandes, déploiements ou suppressions en double.

Secrets, contexte et prompt injection

Les secrets doivent rester dans un gestionnaire de secrets ou un environnement de processus protégé et être injectés uniquement dans l'outil qui en a besoin. Ne placez jamais de clés API dans le contexte du modèle ni dans les journaux. Masquez les en-têtes, jetons, données utilisateur et résultats d'outils avant la télémétrie. Appliquez des règles de sortie par outil afin qu'un serveur compromis ne puisse pas envoyer des données vers des destinations arbitraires.

Considérez comme non fiable tout texte fourni par MCP. Un document peut demander à l'agent d'ignorer des instructions ou d'appeler un autre outil. Conservez les libellés de source et les limites des citations. La politique système, l'approbation de l'utilisateur et l'autorisation de l'outil doivent primer sur le contenu récupéré. Exigez des preuves pour les décisions sensibles au lieu d'accepter l'autorité que s'attribue un document.

Observabilité et échecs sécurisés

Enregistrez une trace structurée : identifiant de requête, décision du modèle, outil sélectionné, paramètres validés, résultat de la politique, référence d'approbation, reçu de l'outil et postcondition. Les journaux doivent permettre l'analyse d'un incident sans conserver du contenu de prompt inutile. Séparez les événements de sécurité du débogage applicatif et définissez la durée de conservation selon la sensibilité.

Échouez de manière fermée en cas d'identité manquante, d'approbation expirée, d'incompatibilité de schéma, de serveur inconnu ou de postcondition ambiguë. Ne réessayez que les erreurs transitoires classifiées. Limitez le débit par utilisateur et par outil, plafonnez le nombre d'itérations et exposez un bouton d'arrêt d'urgence. Un agent qui ne peut pas prouver l'achèvement doit signaler l'incertitude au lieu d'affirmer que l'opération a réussi.

Testez le plan de contrôle

Testez les validateurs et l'autorisation indépendamment du modèle avec des tests unitaires. Ajoutez des tests d'intégration avec des serveurs MCP simulés qui renvoient des schémas malformés, des instructions injectées, des charges trop volumineuses, des réponses lentes et de faux succès. Testez les identifiants inter-tenants et la réutilisation d'approbations périmées. Réalisez des tests red team sur les descriptions comme sur le contenu renvoyé.

Avant la mise en production, confirmez la documentation actuelle d'Anthropic Agent SDK et de MCP, les versions des paquets, les exigences de transport et les recommandations de sécurité. Ce guide définit un modèle d'architecture ; il ne prétend pas qu'une version donnée du SDK applique automatiquement chaque contrôle.

Feuille de travail d'implémentation

Construisez un banc de test minimal avant de connecter des données de production. Enregistrez un serveur MCP en lecture seule, validez les entrées à l'exécution et capturez une trace assainie. N'ajoutez un outil d'écriture qu'après avoir représenté la préparation, l'approbation, le commit et la vérification comme des opérations distinctes. Testez ensuite un serveur inconnu, un schéma d'outil modifié, un jeton expiré, du texte de document injecté, une requête en double et un délai d'attente incertain. Consultez la documentation officielle actuelle du SDK et du protocole pendant l'implémentation, car les noms de paquets, les API et les recommandations de transport peuvent changer.