# Le glossaire des erreurs MCP les plus fréquentes : ce que chaque code veut dire

> Schéma refusé, méthode inconnue, capacité manquante : un tour des erreurs renvoyées par un serveur MCP et de leur cause la plus probable, code par code.

- Auteur : Clément Hadrot
- Publié le : 2025-09-16
- Mis à jour le : 2025-09-16
- Catégorie : IA & MCP
- URL : https://wpmoderne.dev.wordpress-developpement.fr/ia-mcp/glossaire-erreurs-mcp-frequentes/

## L’essentiel

- Les erreurs MCP reposent sur les codes JSON-RPC standard, pas sur un format propriétaire
- Un code générique -32603 cache presque toujours une cause plus précise à chercher côté serveur
- Distinguer erreur de protocole et erreur d'exécution accélère le diagnostic

« Method not found », « Invalid params », « Internal error » : la documentation du Model Context Protocol, publié fin 2024, s'appuie directement sur la spécification JSON-RPC 2.0 pour son format d'erreurs plutôt que d'inventer son propre vocabulaire. Cette parenté simplifie beaucoup le diagnostic, à condition de savoir associer chaque code à sa cause la plus probable côté serveur MCP.

Ce glossaire reprend les erreurs les plus souvent rencontrées en développant et en exploitant des serveurs MCP, avec pour chacune le code JSON-RPC concerné, sa signification littérale, et la cause la plus fréquente observée en pratique. Il ne traite pas des erreurs HTTP génériques (401, 403, 500) qui peuvent survenir en amont, au niveau du transport, avant même que le message JSON-RPC ne soit interprété.

## Erreurs de protocole : le message lui-même est en cause

Ces erreurs surviennent avant que le serveur n'essaie d'exécuter quoi que ce soit : la requête reçue ne respecte pas la structure attendue par le protocole.

- **-32700, Parse error** : le message reçu n'est pas un JSON valide. Cause la plus fréquente : un client MCP mal implémenté qui tronque la réponse ou ajoute un caractère parasite en fin de flux.
- **-32600, Invalid Request** : le JSON est valide mais ne respecte pas la structure JSON-RPC attendue (absence du champ `jsonrpc`, ou d'un identifiant de requête). Cause fréquente : un client construit à la main sans passer par un SDK MCP officiel.

> L'essentiel à retenir : Les erreurs MCP reposent sur les codes JSON-RPC standard, pas sur un format propriétaire ; Un code générique -32603 cache presque toujours une cause plus précise à chercher côté serveur ; Distinguer erreur de protocole et erreur d'exécution accélère le diagnostic

## Erreurs de méthode et de paramètres

Une fois le message reconnu comme une requête JSON-RPC valide, deux erreurs reviennent particulièrement souvent lors des premières intégrations d'un serveur MCP.

### -32601, Method not found

Le client demande une méthode que le serveur n'expose pas, ou plus. C'est l'erreur typique lorsqu'un outil a été renommé côté serveur sans que le client n'ait rafraîchi sa liste d'outils disponibles via un nouvel appel de découverte.

### -32602, Invalid params

La méthode existe, mais les paramètres envoyés ne respectent pas le schéma d'entrée déclaré par l'outil. C'est le cas le plus fréquent en pratique : un agent envoie un type de donnée inattendu (une chaîne là où un entier est attendu), ou omet un champ marqué comme obligatoire dans le schéma.

| Code | Nom | Cause la plus fréquente observée |
| --- | --- | --- |
| -32700 | Parse error | Client mal implémenté, flux JSON tronqué |
| -32600 | Invalid Request | Structure JSON-RPC non respectée |
| -32601 | Method not found | Outil renommé, liste client non rafraîchie |
| -32602 | Invalid params | Type ou champ obligatoire non respecté |
| -32603 | Internal error | Exception non gérée côté serveur |

## L'erreur générique -32603, la plus difficile à diagnostiquer seule

Le code -32603, Internal error, signale simplement qu'une exception non gérée s'est produite pendant l'exécution de l'outil, sans préciser laquelle. Cette généralité est volontaire dans la spécification : elle évite de renvoyer au client des détails d'implémentation potentiellement sensibles. En pratique, la cause se trouve presque toujours dans les journaux du serveur lui-même : appel réseau échoué vers une dépendance externe, division par zéro sur une valeur non validée en amont, ou dépassement d'un délai fixé par le serveur.

```
server.tool(
  'rechercher_produit',
  { reference: z.string() },
  async ( { reference } ) => {
    try {
      const produit = await depot.trouverParReference( reference );
      return { content: [ { type: 'text', text: JSON.stringify( produit ) } ] };
    } catch ( erreur ) {
      // Sans ce bloc, l'exception remonte comme -32603 sans contexte utile
      return {
        content: [ { type: 'text', text: `Référence introuvable : ${reference}` } ],
        isError: true,
      };
    }
  }
);
```

## Une catégorie qui n'est pas dans la spécification : la capacité manquante

Un agent qui tente d'appeler un outil que le serveur n'a jamais déclaré ne reçoit pas nécessairement -32601 : selon l'implémentation, il peut simplement ne jamais voir cet outil apparaître dans sa liste de découverte, ce qui n'est pas une erreur au sens du protocole, mais une absence de déclaration. Confondre les deux cas retarde souvent le diagnostic : avant de chercher une erreur, mieux vaut vérifier que l'outil attendu apparaît bien dans la réponse de découverte du serveur.

> Un code d'erreur générique n'est jamais une réponse en soi, seulement une invitation à regarder ailleurs : dans les journaux du serveur, jamais dans le message renvoyé au client.

## En résumé

La quasi-totalité des erreurs MCP rencontrées en pratique se ramène à cinq codes JSON-RPC standard, dont la signification littérale ne suffit presque jamais à elle seule : -32602 pointe vers le schéma d'entrée, -32601 vers une désynchronisation entre client et serveur sur la liste d'outils, et -32603 vers les journaux du serveur plutôt que vers le message d'erreur lui-même. Connaître cette correspondance de tête accélère nettement le diagnostic dès les premiers symptômes.