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

Un article Show HN « Ableton Live MCP » a atteint 118 points et 78 commentaires cette semaine. Le schéma est désormais familier : quelqu’un écrit un serveur Model Context Protocol pour un outil inattendu, la communauté Claude Desktop l’adopte, puis une vague de posts « Devrais-je en écrire un pour X ? » apparaît. En moins d’un an, le MCP est passé d’une expérimentation centrée sur Anthropic à une couche d’intégration d’agents utilisée par défaut.

Essayez Apidog aujourd’hui

Cette croissance masque un problème concret : il manque une méthode claire pour tester les serveurs MCP. Envoyer manuellement du JSON-RPC sur stdio suffit pour un hello-world, mais devient fragile dès que votre serveur expose 12 outils, 3 invites et dépend d’une API amont instable.

Ce guide propose une approche pratique pour tester un serveur MCP manuellement, puis automatiser ces tests avec Apidog, afin de traiter votre serveur MCP comme n’importe quelle API : avec un contrat, des mocks et une suite de régression.

Si vous travaillez déjà avec des agents, notre guide agents.md complète bien cette approche : les conventions qu’il définit facilitent la communication des contrats MCP dans une équipe.

En bref

• Le MCP est le Model Context Protocol d’Anthropic : du JSON-RPC 2.0 sur stdio ou HTTP, avec trois primitives principales : outils, ressources et invites.
• Tester un serveur MCP revient à vérifier les réponses initialize, tools/list, tools/call, resources/read et prompts/get par rapport à un contrat.
• Commencez manuellement avec l’inspecteur MCP ou du JSON-RPC brut sur stdio.
• Capturez ensuite les échanges dans Apidog, transformez chaque appel en requête sauvegardée, ajoutez des assertions, puis exécutez la suite en CI.
• Utilisez le serveur de mock d’Apidog pour simuler les API amont et rendre les tests déterministes.
• Téléchargez Apidog pour regrouper requêtes, mocks et runner CI dans un seul workflow.

Ce qu’est réellement le MCP

La spécification du Model Context Protocol définit un protocole JSON-RPC 2.0 avec une surface volontairement réduite. Un client — Claude Desktop, Cursor ou votre propre agent — démarre un serveur MCP, effectue un handshake initialize, puis appelle les primitives exposées.

Les appels à tester en priorité :

• initialize : négociation de version et déclaration des capacités.
• tools/list : liste des outils exposés, avec leur schéma JSON d’arguments.
• tools/call : invocation d’un outil par son nom avec des arguments.
• resources/list et resources/read : exposition et lecture de contenus adressés par URI.
• prompts/list et prompts/get : exposition et rendu de modèles d’invites.

Le transport est généralement :

• stdio pour les serveurs locaux ;
• HTTP streamable, souvent POST / avec SSE, pour les serveurs distants.

Pourquoi tester ? Parce qu’une erreur dans tools/list ou dans le schéma d’un outil casse simultanément tous les clients MCP qui consomment votre serveur.

Ce que vous devez tester

Une suite de tests MCP utile couvre six axes.

1. Conformité au protocole

Vérifiez que initialize retourne :

• la bonne protocolVersion ;
• les capacités réellement supportées ;
• une structure JSON-RPC valide.

Exemple d’appel :

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

2. Validité des schémas

Pour chaque outil retourné par tools/list, contrôlez que :

• name existe ;
• description est exploitable ;
• inputSchema est un JSON Schema valide ;
• les champs requis sont bien déclarés.

Les descriptions vides ou trop vagues peuvent nuire à la sélection d’outils côté client.

3. Comportement des outils

Pour chaque tools/call, testez :

• le chemin nominal ;
• les arguments manquants ;
• les types invalides ;
• les erreurs d’API amont.

Un résultat valide doit retourner des blocs content du bon type :

{
  "content": [
    {
      "type": "text",
      "text": "Résultat de l’outil"
    }
  ]
}

Pour une erreur métier ou d’exécution, retournez un résultat normal avec isError: true, pas une erreur JSON-RPC de protocole.

4. Accès aux ressources

Vérifiez que les URI retournées par resources/list se résolvent via resources/read.

Testez aussi :

• les ressources inexistantes ;
• la pagination ;
• les permissions ;
• les formats de réponse.

5. Rendu des invites

Pour prompts/get, assurez-vous que :

• le tableau messages est bien formé ;
• les arguments sont interpolés au bon endroit ;
• les messages générés respectent le format attendu par les clients.

6. Modes de défaillance

Testez explicitement :

• API amont indisponible ;
• timeout ;
• argument absent ;
• réponse amont malformée ;
• appels concurrents.

Ce sont ces cas qui provoquent les régressions en production.

Tests manuels avec stdio

Commencez avec la configuration la plus simple :

• un terminal ;
• votre serveur MCP ;
• l’inspecteur MCP ou du JSON-RPC brut.

Si vous n’avez pas encore de serveur, utilisez le démarrage rapide officiel du SDK MCP en Python ou TypeScript. L’exemple météo à deux outils suffit pour construire une première suite.

Lancez le serveur avec l’inspecteur :

npx @modelcontextprotocol/inspector node your-server.js

L’inspecteur ouvre une interface web locale qui communique avec votre serveur en MCP. Utilisez-le pour vérifier rapidement que le serveur :

• démarre correctement ;
• répond à initialize ;
• expose ses capacités ;
• retourne une liste d’outils cohérente.

Ensuite, exécutez le même flux avec du stdio brut afin de capturer les trames que vous importerez dans Apidog :

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

Enregistrez la requête et la réponse. Répétez l’opération pour :

• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

À la fin, vous devez disposer de 6 à 12 paires requête-réponse qui décrivent le contrat réel de votre serveur MCP.

Points à vérifier pendant les tests manuels

Blocs de contenu

Un résultat d’outil peut contenir du texte :

{
  "content": [
    {
      "type": "text",
      "text": "Température actuelle : 21°C"
    }
  ]
}

Ou une image :

{
  "content": [
    {
      "type": "image",
      "data": "...",
      "mimeType": "image/png"
    }
  ]
}

Le mélange de plusieurs types dans une même réponse est autorisé, mais tous les clients ne les affichent pas de la même manière.

Erreurs d’outil

Pour une erreur interne à l’outil, utilisez :

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "La ville est obligatoire."
    }
  ]
}

Évitez de retourner une erreur JSON-RPC si le protocole lui-même n’est pas en cause. De nombreux clients interprètent les erreurs JSON-RPC comme une défaillance de connexion ou de protocole.

Automatiser les tests dans Apidog

Les tests manuels trouvent les erreurs évidentes. L’automatisation devient nécessaire dès que vous voulez répondre à cette question : « Est-ce que ma dernière modification a cassé le schéma de l’outil 7 ? »

Le workflow :

1. Capturez vos échanges JSON-RPC.
2. Créez un projet dans Apidog.
3. Sauvegardez chaque appel MCP comme requête.
4. Ajoutez des assertions JSONPath.
5. Simulez les API amont.
6. Exécutez la suite en CI.

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

Dans Apidog :

1. Créez un nouveau projet.
2. Configurez l’URL de base de votre serveur MCP.
3. Créez un environnement pour les tests.
4. Ajoutez vos requêtes JSON-RPC.

Pour un serveur HTTP MCP, utilisez directement son endpoint.

Pour un serveur stdio, ajoutez un wrapper HTTP uniquement pour les tests. L’inspecteur officiel peut aider, ou vous pouvez écrire un petit script Node qui reçoit du JSON-RPC en HTTP et le transmet au processus stdio.

Ce même modèle est utilisé dans Tests d’API sans Postman en 2026 pour tester des backends non HTTP.

2. Enregistrer les requêtes canoniques

Créez une requête sauvegardée pour chaque méthode importante :

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Exemple de corps pour tools/call :

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

Sauvegardez aussi les en-têtes, l’environnement et le statut attendu.

3. Ajouter des assertions

Le but n’est pas seulement d’envoyer des requêtes, mais de valider automatiquement les réponses.

Pour tools/list, ajoutez au minimum des assertions sur :

• l’existence de $.result.tools ;
• un nombre d’outils supérieur à zéro ;
• la présence de name, description et inputSchema ;
• la validité des schémas JSON.

Exemples d’assertions utiles :

$.result.tools exists
$.result.tools.length > 0
$.result.tools[0].name exists
$.result.tools[0].description exists
$.result.tools[0].inputSchema exists

Pour un tools/call valide :

$.result.isError == false
$.result.content exists
$.result.content[0].type == "text"

Pour un tools/call invalide :

$.result.isError == true
$.result.content[0].text matches /obligatoire|manquant|required/

Évitez les assertions trop strictes sur des messages d’erreur complets. Préférez un code stable ou une expression régulière.

4. Simuler les API amont

La plupart des serveurs MCP encapsulent une API externe : météo, GitHub, Linear, Notion, base interne, etc.

Ne laissez pas votre CI dépendre de ces API en direct :

• les tests deviennent plus lents ;
• les limites de débit peuvent être atteintes ;
• les réponses changent ;
• les pannes externes cassent votre pipeline.

Utilisez le serveur de mock intégré d’Apidog :

1. Déclarez chaque endpoint amont.
2. Ajoutez une réponse JSON réaliste.
3. Configurez votre serveur MCP pour pointer vers l’URL de mock pendant les tests.
4. Utilisez l’URL de production uniquement en environnement réel.

Le workflow de mock est détaillé dans le guide sur le développement d’API contract-first.

Résultat : une suite rapide, déterministe, sans dépendance réseau externe.

5. Exécuter la suite en CI

Les projets Apidog peuvent être exécutés via un runner CLI. La commande apidog run exécute les requêtes sauvegardées, évalue les assertions et retourne un code non nul en cas d’échec.

Exemple de workflow GitHub Actions :

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 valide le contrat MCP complet. Une régression dans le schéma d’un outil ne peut plus passer inaperçue.

À quoi ressemble une bonne couverture de test

Pour un serveur MCP, une couverture raisonnable dans Apidog inclut généralement :

• 1 requête initialize avec assertions de version et capacités ;
• 1 requête tools/list avec assertions de forme et de JSON Schema ;
• 2 à 4 requêtes tools/call par outil :
  • chemin nominal ;
  • argument manquant ;
  • type invalide ;
  • erreur amont ;
• 1 requête resources/list ;
• 1 requête resources/read par famille de ressources ;
• 1 requête prompts/list ;
• 1 requête prompts/get par modèle d’invite.

Pour un serveur avec 10 outils, 3 ressources et 4 invites, cela représente souvent 50 à 70 requêtes. Avec des mocks préchauffés, la suite peut s’exécuter en quelques secondes.

Erreurs courantes lors du test des serveurs MCP

Sauter initialize

Certains serveurs construisent leur registre d’outils pendant le handshake. Si vous appelez tools/list sans initialize, vous testez un état invalide.

Toujours exécuter :

initialize -> tools/list -> tools/call

Tester uniquement le chemin nominal

Un outil qui fonctionne avec des arguments parfaits peut échouer dès qu’un client fournit un argument manquant ou mal typé.

Ajoutez systématiquement des tests négatifs.

Asserter sur des chaînes d’erreur exactes

Les messages changent. Préférez :

• isError: true ;
• un code d’erreur stable ;
• une expression régulière.

Laisser les mocks diverger de la production

Un mock qui ne ressemble plus à l’API réelle donne des tests verts sur une intégration cassée.

Réenregistrez régulièrement les fixtures à partir de réponses réelles.

Oublier le streaming

Les serveurs MCP HTTP peuvent diffuser les résultats via SSE. Activez le streaming dans la requête Apidog lorsque vous testez ce mode.

Ne pas tester la concurrence

Les clients MCP peuvent envoyer plusieurs tools/call en parallèle. Si votre serveur partage un état mutable, les tests unitaires séquentiels ne suffisent pas.

Ajoutez un scénario d’exécution parallèle.

Confondre erreurs de protocole et erreurs d’outil

La spécification MCP sépare les deux. Les mélanger peut pousser Claude Desktop ou un autre client à fermer la connexion.

Ce type de bug de contrat est aussi abordé dans le guide sur le développement d’API contract-first.

Cas d’utilisation réels

Une équipe développant un serveur MCP interne pour une API de gestion d’incidents a détecté trois régressions en une semaine grâce aux assertions Apidog sur tools/list. Sans ce test, les bugs auraient été déployés à tous les ingénieurs utilisant Claude Desktop.

Un développeur solo publiant un serveur MCP open source pour Notion utilise les mocks Apidog pour exécuter la suite sans atteindre les limites de débit de Notion en CI. La suite s’exécute à chaque PR, prend 8 secondes et permet aux contributeurs de travailler sans accès API.

Une équipe plateforme gérant 14 serveurs MCP internes a construit un espace de travail Apidog partagé pour stocker les contrats de chaque serveur. Les nouveaux serveurs héritent d’une suite de base, et les reviewers comparent les différences de schéma avant merge.

Une autre équipe, qui construit un serveur MCP pour une plateforme d’observabilité interne, utilise les environnements Apidog pour exécuter la même suite contre staging et production. Chaque environnement pointe vers un jeu de mocks différent, sans dupliquer les requêtes.

Conclusion

Le MCP s’est généralisé rapidement, mais les pratiques de test restent souvent manuelles et fragiles. Traitez votre serveur MCP comme l’API JSON-RPC qu’il est : définissez un contrat, testez les cas d’erreur, simulez les dépendances amont et exécutez la suite en CI.

À retenir :

• Un serveur MCP est une API JSON-RPC : testez-le avec la même rigueur qu’une API REST.
• Commencez avec l’inspecteur officiel, puis capturez des requêtes canoniques.
• Apidog permet de gérer JSON-RPC, assertions, mocks et CI dans un seul projet.
• Couvrez le protocole, les schémas, les outils, les ressources, les invites et les modes de défaillance.
• Mockez les API amont pour garder une suite rapide et déterministe.

Étape suivante : ouvrez Apidog, créez un projet, collez vos requêtes MCP capturées manuellement, ajoutez des assertions JSONPath sur tools/list, puis exécutez la suite. En moins d’une heure, vous saurez si le contrat de votre serveur MCP est prêt à être déployé.

FAQ

Qu’est-ce que le MCP ?

Le MCP, ou Model Context Protocol, est la spécification ouverte d’Anthropic qui décrit comment les clients d’IA, comme Claude Desktop, appellent des outils externes, des ressources et des invites. Il repose sur JSON-RPC 2.0 via 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 fournit une interface pour les tests manuels.

Pour les tests automatisés dans Apidog, ajoutez un wrapper HTTP léger pendant la CI. Le trafic de production peut continuer à passer par stdio.

Comment simuler les API amont appelées par mon serveur MCP ?

Déclarez chaque endpoint amont comme mock dans votre projet Apidog, pointez votre serveur MCP vers l’URL de mock pendant les tests, puis utilisez les URL réelles en production.

Le même modèle est décrit 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 peuvent diffuser les résultats via SSE. Apidog prend en charge le SSE dans les requêtes enregistrées. Activez le streaming dans les paramètres de la requête, puis effectuez vos assertions sur le flux assemblé.

Dois-je tester la version du protocole ?

Oui. Épinglez la protocolVersion supportée dans initialize et ajoutez une assertion dessus. Les incompatibilités de version peuvent provoquer des erreurs client difficiles à diagnostiquer.

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

Oui, et vous devriez le faire au moins une fois avant chaque version. Mais Claude Desktop ne doit pas être votre boucle principale de régression : c’est manuel, lent et non déterministe.

Utilisez Apidog pour la suite automatisée, puis Claude Desktop pour un smoke test final.

Où 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 d’autres intégrations.

Lisez les définitions d’outils : c’est l’un des moyens les plus rapides de comprendre à quoi ressemble un bon contrat MCP.