Blog

Guide de Test Serveur MCP : Manuel & Automatisé avec Apidog

Ashley Innocent

Ashley Innocent

11 May 2026

Guide de Test Serveur MCP : Manuel & Automatisé avec Apidog

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

Un article Show HN « Ableton Live MCP » a grimpé à 118 points et 78 commentaires plus tôt cette semaine. Le schéma est désormais familier : quelqu'un a écrit un serveur Model Context Protocol pour un outil improbable, la communauté de Claude Desktop l'a adoré, et une vague de publications « Devrais-je en écrire un pour X ? » a suivi. Le MCP est passé d'une expérience uniquement Anthropic à une couche d'intégration d'agent par défaut en moins d'un an.

Ce que cette croissance cache est un manque d'outillage : personne n'a proposé une méthode claire pour tester les serveurs MCP. Exécuter manuellement du JSON-RPC sur stdio avec un débogueur est acceptable pour un "hello-world" ; cela s'effondre dès que votre serveur a 12 outils, 3 invites et une API en amont instable. Ce guide vous offre un manuel pratique pour tester les serveurs MCP manuellement et automatiser ces tests avec Apidog, afin que vous puissiez déployer des serveurs MCP comme vous le feriez pour toute autre API : avec un contrat, une maquette et une suite de régression.

Si vous venez d'un contexte d'agent plus général, notre guide agents.md se marie bien avec cela ; les conventions qui y sont définies facilitent la communication des contrats de serveur MCP à votre équipe.

button

En bref

Ce qu'est réellement le MCP, en deux minutes

La spécification du Model Context Protocol définit un format de données JSON-RPC 2.0 avec une surface réduite. Un client (Claude Desktop, Cursor, votre propre agent) démarre un serveur MCP, effectue un handshake initialize, puis émet des appels.

Les cinq appels que vous testerez 90 % de votre temps :

Le transport est soit stdio (frames JSON-RPC délimitées par des nouvelles lignes sur stdin/stdout) soit HTTP streamable (généralement POST / avec SSE pour le streaming). La plupart des serveurs locaux utilisent stdio ; les serveurs distants utilisent HTTP.

Pourquoi les tests sont importants : chaque utilisateur de Claude Desktop, chaque utilisateur de Cursor, chaque IDE qui ajoute le support MCP va appeler votre serveur. Les bugs dans la structure de tools/list cassent tous les clients simultanément. Le coût d'une régression est élevé.

Ce que vous devriez tester

Une suite de tests solide pour un serveur MCP couvre six dimensions.

Le reste de ce guide passe en revue chacun de ces points, d'abord manuellement, puis de manière automatisée.

Tests manuels avec stdio

Commencez avec la configuration la plus simple possible : un terminal, votre binaire de serveur, et l'inspecteur MCP ou du JSON-RPC brut à la main.

Si vous n'avez pas encore construit de serveur, échafaudez-en un avec le démarrage rapide officiel du SDK MCP en Python ou TypeScript. L'exemple météo à deux outils est suffisant pour les tests.

Exécutez le serveur en mode inspecteur :

npx @modelcontextprotocol/inspector node your-server.js

L'inspecteur démarre une interface utilisateur web locale qui communique en MCP avec votre serveur et vous montre chaque requête et réponse. C'est le moyen le plus rapide de confirmer que le serveur démarre, annonce ses capacités et répond à tools/list.

Une fois que la vue de l'inspecteur semble correcte, exécutez le même flux avec du stdio brut afin de pouvoir capturer les trames pour Apidog :

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Vous obtiendrez une réponse JSON-RPC sur stdout. Enregistrez la requête et la réponse. Répétez l'opération pour tools/list, tools/call, resources/list, et le reste. À la fin de cet exercice, vous aurez entre 6 et 12 paires requête-réponse canoniques qui définissent le contrat au niveau du protocole de votre serveur.

Deux choses à surveiller.

Premièrement, les blocs de contenu. Le résultat d'un outil renvoie content: [{ type: "text", text: "..." }] ou content: [{ type: "image", data: "...", mimeType: "image/png" }]. Le mélange des types dans une seule réponse est autorisé ; les clients diffèrent sur la façon dont ils les affichent.

Deuxièmement, les erreurs. La spécification MCP est claire : les erreurs d'exécution d'outils renvoient un résultat normal avec isError: true et un bloc de contenu décrivant l'échec. Ne lancez pas de réponses d'erreur JSON-RPC depuis l'intérieur d'un outil ; cela signale une défaillance au niveau du protocole, et non au niveau de l'outil. De nombreux clients coupent la connexion en cas d'erreurs de protocole.

Du manuel à l'automatisé : construire la suite de tests dans Apidog

Les tests manuels révèlent les bugs évidents. Vous passez à l'automatisation lorsque vous commencez à vous demander « ma dernière modification a-t-elle cassé le schéma des arguments de l'outil 7 ? » et que vous ne voulez pas taper 12 commandes curl pour le savoir.

Le modèle : prenez chaque paire requête-réponse que vous avez enregistrée lors des tests manuels, collez-la dans Apidog en tant que requête sauvegardée, ajoutez des assertions et exécutez la suite à chaque push.

1. Créer un projet Apidog pour le serveur MCP

Ouvrez Apidog, créez un nouveau projet, définissez l'URL de base sur le point de terminaison HTTP de votre serveur MCP (ou l'URL du pont stdio ; voir ci-dessous). Les projets Apidog prennent en charge à la fois REST et JSON-RPC ; créez un environnement JSON-RPC.

Pour les serveurs stdio qui n'ont pas d'interface HTTP, exécutez-les derrière un mince wrapper HTTP pour les tests. L'inspecteur officiel en fournit un ; alternativement, un script Node de 30 lignes qui lit le JSON-RPC sur HTTP et le transmet à stdio fonctionne très bien. Nous utilisons le même modèle dans Tests d'API sans Postman en 2026 pour les backends non-HTTP.

2. Enregistrer les requêtes canoniques

Pour chacun des éléments initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, enregistrez le corps JSON-RPC comme une requête. Apidog les stocke avec le corps, les en-têtes et le statut attendu.

Une requête tools/call ressemble à ceci dans la vue du corps de requête d'Apidog :

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

3. Ajouter des assertions

Le but de l'automatisation est d'asserter la réponse, pas d'envoyer la requête. Apidog prend en charge nativement les assertions JSONPath. Pour tools/list, vous voulez au moins :

Pour tools/call sur une entrée valide connue, vous voulez :

Pour tools/call sur une entrée invalide connue (argument requis manquant), vous voulez :

Apidog stocke ces assertions par requête. Les échecs apparaissent dans le rapport d'exécution.

4. Simuler les API en amont

La plupart des serveurs MCP encapsulent une API externe : données météorologiques, GitHub, Linear, une base de données interne. Vous ne voulez pas que les exécutions de CI frappent les API en direct à chaque commit. Deux raisons : le coût et l'instabilité.

Le serveur de maquette intégré d'Apidog résout ce problème. Définissez chaque point de terminaison en amont comme une route simulée renvoyant un corps JSON réaliste. Orientez la configuration de votre serveur MCP vers l'URL de maquette pendant les tests et vers la production pendant les exécutions réelles. Nous couvrons le flux de travail de maquette en détail dans le développement d'API contract-first.

Le résultat : une suite de tests qui s'exécute en quelques secondes, ne nécessite aucun réseau externe et détecte les régressions de schéma bien avant qu'elles ne soient déployées.

5. Exécuter la suite en CI

Les projets Apidog s'exportent vers des runners CLI. La commande apidog run prend un ID de projet, exécute chaque requête sauvegardée, évalue les assertions et quitte avec un code non nul en cas d'échec. Intégrez-le à vos GitHub Actions ou à tout fournisseur de CI que vous utilisez déjà.

Un workflow minimal :

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &
      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN:   ${{ secrets.APIDOG_TOKEN }}

Chaque push exécute l'intégralité du contrat MCP. Une régression de schéma de l'outil 7 ne peut pas passer inaperçue.

À quoi ressemble une bonne couverture de test

Un plan de test complet pour un serveur MCP dans Apidog comprend généralement :

Pour un serveur de 10 outils avec 3 ressources et 4 invites, la suite exécute 50 à 70 requêtes. Apidog les exécute localement en moins de 10 secondes avec le serveur de maquette préchauffé.

Erreurs courantes lors du test des serveurs MCP

Voici les schémas que nous rencontrons le plus souvent.

Cas d'utilisation réels

Une équipe développant un serveur MCP interne pour l'API de gestion d'incidents de leur entreprise a détecté trois régressions en une semaine en utilisant les assertions Apidog sur la forme de tools/list. Sans ce test, les bugs auraient été déployés simultanément à chaque ingénieur utilisant Claude Desktop.

Un développeur solo publiant un serveur MCP open-source pour Notion utilise les maquettes Apidog pour exécuter la suite de tests sans atteindre les limites de débit de Notion pendant la CI. Leur suite s'exécute sur chaque PR, prend 8 secondes et met en cache les fixtures de maquette d'Apidog dans le dépôt afin que les contributeurs n'aient pas besoin d'accès API pour développer.

Une équipe de plateforme gérant 14 serveurs MCP internes a construit un espace de travail Apidog partagé où réside le contrat de chaque serveur. Les nouveaux serveurs héritent d'une suite de tests de base ; les réviseurs peuvent comparer les différences de schéma côte à côte avant de fusionner. L'équipe rapporte deux pannes évitées au cours du premier trimestre, toutes deux détectées par des assertions de forme tools/list sur une PR qui aurait livré un argument renommé à chaque utilisateur de Claude Desktop au sein de l'entreprise.

Une deuxième équipe construisant un serveur MCP pour une plateforme d'observabilité interne utilise le sélecteur d'environnement d'Apidog pour exécuter la même suite contre la staging et la production. Chaque environnement pointe vers un fichier de maquette différent, de sorte que les mêmes 60 assertions confirment les deux déploiements sans réécrire une seule requête.

Conclusion

Le MCP s'est généralisé cette année, mais l'histoire des tests en est encore là où les tests d'API REST se trouvaient il y a une décennie : ad hoc, manuels, fragiles. Vous n'avez pas à attendre que l'écosystème rattrape son retard. Traitez votre serveur MCP comme l'API qu'il est, concevez un contrat, simulez les API en amont et exécutez des assertions en CI.

Cinq points à retenir :

Étape suivante : ouvrez Apidog, créez un projet, collez les corps de requête que vous avez capturés manuellement, ajoutez des assertions JSONPath pour tools/list et exécutez la suite. Vous saurez en moins d'une heure si le contrat de votre serveur est suffisamment solide pour être déployé.

FAQ

Qu'est-ce que le MCP ?

Le MCP, ou Model Context Protocol, est la spécification ouverte d'Anthropic décrivant comment les clients d'IA (comme Claude Desktop) appellent des outils externes, des ressources et des invites. Il s'agit de JSON-RPC 2.0 sur stdio ou HTTP streamable. La spécification complète du MCP est publiée sur modelcontextprotocol.io.

Puis-je tester un serveur MCP sans wrapper HTTP ?

Oui. L'inspecteur MCP officiel communique directement en stdio et vous offre une interface utilisateur pour les tests manuels. Pour les tests automatisés dans Apidog, enveloppez stdio dans un serveur HTTP léger pendant la CI ; le trafic de production continue de passer par stdio.

Comment simuler les API en amont que mon serveur MCP appelle ?

Définissez chaque point de terminaison en amont comme une maquette dans votre projet Apidog, dirigez la configuration du serveur MCP vers l'URL de maquette pendant les tests, et passez aux URL de production au moment de l'exécution. Nous décrivons le même modèle dans les outils de test d'API pour les ingénieurs QA.

Qu'en est-il des résultats d'outils en streaming ?

Les serveurs MCP HTTP diffusent les résultats des outils via des événements envoyés par le serveur (SSE). Apidog prend en charge le SSE dans les requêtes enregistrées ; activez-le dans les paramètres de la requête et effectuez des assertions sur le flux assemblé.

Dois-je tester la version du protocole ?

Oui. Épinglez la protocolVersion que vous supportez dans initialize et effectuez des assertions sur celle-ci. Les incompatibilités entraînent une incompatibilité client silencieuse.

Puis-je tester mon serveur MCP avec Claude Desktop réel ?

Vous le pouvez, et vous devriez le faire au moins une fois avant chaque version. Mais ne comptez pas sur Claude Desktop comme boucle de test ; c'est lent, manuel et non déterministe. Utilisez Apidog pour la suite de régression et Claude Desktop pour le test de fumée.

Où puis-je voir des exemples réels de serveurs MCP ?

Le répertoire officiel des serveurs MCP contient des implémentations de référence pour les systèmes de fichiers, GitHub, Slack, Postgres, et des dizaines d'autres. Lisez les définitions d'outils ; c'est le moyen le plus simple de comprendre à quoi ressemble une bonne forme MCP.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger