Brancher un client agentique à un serveur MCP

Ce guide décrit comment configurer un client MCP (assistant de bureau, IDE, ou CLI agentique) pour qu'il consomme un serveur MCP — c'est-à-dire un service qui expose des outils invocables via le protocole MCP (Model Context Protocol), transporté en JSON-RPC 2.0.

Il suppose que le serveur existe déjà et qu'un token vous a été remis. Pour le contrat du serveur (transports, outils, codes d'erreur, scopes), voir la référence Serveur MCP — référence du composant.

Avant de commencer

Rassemblez trois éléments :

• Le point d'entrée du serveur — soit une URL HTTP (transport distant), soit une commande qui démarre le serveur en sous-processus (transport local stdio).
• Le token — une chaîne opaque qui vous authentifie. Elle vous est remise une seule fois ; conservez-la dans un gestionnaire de secrets, jamais en clair dans un fichier versionné.
• Le nom logique que vous donnerez au serveur côté client (libre ; il apparaîtra dans la liste des serveurs de votre client).

1. Choisir le transport

Deux transports existent ; ils ne se configurent pas de la même façon.

Règle simple : si le serveur est distant, utilisez HTTP. Le stdio lance le serveur comme un sous-processus local et n'a de sens que quand le binaire du serveur tourne sur votre propre machine.

2. Déclarer le serveur (transport HTTP)

La plupart des clients agentiques lisent un fichier de configuration JSON avec un objet mcpServers. La forme générale, pour un serveur distant :

{
  "mcpServers": {
    "mon-serveur-mcp": {
      "type": "http",
      "url": "https://votre-serveur/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>"
      }
    }
  }
}

Points de vigilance :

• "type": "http" est souvent obligatoire. Sans lui, certains clients partent du principe qu'il s'agit d'un serveur stdio, cherchent un champ command et rejettent la configuration.
• L'URL pointe sur le chemin /mcp (ou celui documenté par votre serveur), pas sur la racine du domaine.
• Le token voyage dans l'en-tête Authorization, préfixé de Bearer (avec l'espace). C'est la seule façon d'authentifier en HTTP.

Avantages du HTTP : aucun processus local à maintenir, aucune dépendance à l'environnement de la machine, fonctionne depuis n'importe quel répertoire de travail.

Ne pas committer le token

Ce fichier de configuration contient un secret. Assurez-vous qu'il est exclu du versionnement (.gitignore) et, quand le client le permet, préférez une référence à une variable d'environnement plutôt qu'une valeur en clair.

3. Déclarer le serveur (transport stdio)

En stdio, le client lance le serveur en sous-processus et dialogue avec lui en JSON-RPC sur l'entrée/sortie standard. On déclare donc une commande et ses arguments, et on transmet le token par une variable d'environnement (jamais en argument de ligne de commande — il resterait visible dans la liste des processus et l'historique du shell).

{
  "mcpServers": {
    "mon-serveur-mcp": {
      "command": "<interpréteur>",
      "args": ["<chemin vers le point d'entrée du serveur>", "mcp:serve"],
      "env": {
        "MCP_TOKEN": "<TOKEN>"
      }
    }
  }
}

• command + args : la commande qui démarre votre serveur en mode stdio.
• env : le token, transmis à l'environnement du sous-processus sous le nom attendu par le serveur (souvent MCP_TOKEN — vérifiez la référence de votre serveur).
• Après modification, redémarrez le client pour qu'il relance le sous-processus.

Cas particulier : le serveur tourne dans un sous-système (ex. Linux sous Windows)

Si l'interpréteur du serveur vit dans un sous-système Linux alors que le client tourne sous Windows, deux précautions :

• La commande doit passer par le lanceur du sous-système, et le chemin doit être exprimé dans le référentiel du sous-système (montage), pas dans celui de l'hôte.
• Les variables d'environnement ne traversent pas toujours la frontière automatiquement. Vérifiez le mécanisme de propagation propre à votre sous-système : si le token n'arrive pas côté serveur, l'authentification échoue alors que la configuration semble correcte.

Fins de ligne

Le protocole stdio attend un message JSON par ligne, terminé par \n. Sur les plateformes qui produisent des fins de ligne CRLF, veillez à ce que le flux ne contienne pas de \r parasites, sous peine de casser le parsing JSON-RPC.

4. Vérifier que le branchement fonctionne

1. Redémarrez le client après toute modification de configuration.
2. Vérifiez que le serveur apparaît dans la liste et qu'il est connecté (pas d'erreur de démarrage).
3. Demandez à l'assistant : « Quels outils MCP as-tu à disposition ? » — il doit lister les outils exposés par le serveur.
4. Test fonctionnel : posez une question qui doit déclencher un outil, par exemple « Cherche dans la documentation ce qui concerne X. » L'assistant doit appeler l'outil correspondant et répondre avec des passages sourcés.

Sous le capot, le client effectue un handshake initialize → notifications/initialized, puis tools/list pour découvrir le catalogue. Un appel d'outil émis avant la fin de l'initialisation renvoie une erreur JSON-RPC -32600 (requête invalide) : laissez le client terminer son initialisation.

5. Dépannage

Le serveur n'apparaît pas / ne se connecte pas

• stdio : chemin de command/args erroné, ou le serveur écrit autre chose que du JSON-RPC sur la sortie standard (rappel : les logs doivent partir sur la sortie d'erreur, jamais sur stdout).
• HTTP : URL incorrecte, ou champ type absent (le client tente alors du stdio).

Authentification refusée (AUTH_REQUIRED, TOKEN_REVOKED, ou HTTP 401)

• Token absent, erroné, expiré ou révoqué.
• HTTP : vérifiez le préfixe Bearer et l'absence d'espace ou de retour à la ligne parasite dans l'en-tête.
• stdio : vérifiez que la variable d'environnement du token est bien présente dans env et qu'elle atteint réellement le sous-processus (voir le cas sous-système).

Un outil n'apparaît pas / « tool not found » / HTTP 403

• tools/list ne renvoie pas l'outil attendu : votre token n'a peut-être pas les scopes nécessaires. Un serveur MCP peut filtrer le catalogue selon les scopes du token (tool:<nom>, project:<slug>). Vérifiez auprès de l'émetteur du token les scopes qui vous ont été accordés.

Appel d'outil rejeté en -32600

• Appel émis avant la fin du handshake initialize → notifications/initialized. Laissez le client finir son initialisation.

Réponses sans sources

• Un outil de recherche déclaré mais non branché sur son moteur en aval renverra des réponses non sourcées. C'est un défaut côté serveur, pas côté client.

Erreur de parsing JSON (stdio)

• Fins de ligne CRLF parasites dans le flux (voir §3).

Pour aller plus loin

• Contrat complet du serveur (transports, outils, scopes, codes d'erreur) : Serveur MCP — référence du composant.