Tuto — Brancher le serveur MCP sur Claude Code (CLI)

Public visé : instance Claude Code (Atlas, Lead Tech, Chef…) qui veut accéder aux outils MCP Telaria (list_docs, read_doc, search_docs) depuis son repo de travail.

Prérequis : le serveur tlr-mcp est opérationnel sur la machine locale (cf. serveur MCP en Symfony) et un token d'instance a été émis (cf. gouvernance MCP multi-instances).

Principe

Claude Code (CLI) charge la configuration MCP depuis deux sources, dans cet ordre de priorité :

1. .mcp.json à la racine du projet courant (configuration locale, versionnée avec le repo)
2. ~/.claude/settings.json (configuration globale, toutes sessions)

La méthode recommandée pour l'écosystème Telaria : .mcp.json par repo — chaque instance a son propre fichier avec son propre token scopé, et ce fichier est versionné dans le repo de travail de l'instance.

1. Via .mcp.json (méthode recommandée)

Créer ou compléter .mcp.json à la racine du repo de travail de l'instance :

{
  "mcpServers": {
    "tlr-mcp": {
      "command": "php",
      "args": ["C:/src/telaria-app/bin/console", "mcp:serve"],
      "env": {
        "MCP_TOKEN": "le-token-opaque-de-cette-instance"
      }
    }
  }
}

Adapté par instance :

Chemin en forward slash même sous Windows : Claude Code transmet la commande à un sous-processus via l'API système qui accepte les deux notations, mais les backslash dans un JSON nécessitent un double-escape (\\). Préférer les forward slash.

MCP_TOKEN n'est jamais committé tel quel. Le fichier .mcp.json est versionné mais ne contient que la clé — la valeur réelle est injectée manuellement après clonage ou stockée dans un gestionnaire de secrets local.

2. Via claude mcp add (méthode alternative, config globale)

Pour enregistrer le serveur dans les settings globaux Claude Code (toutes sessions, tous repos) :

claude mcp add tlr-mcp php C:/src/telaria-app/bin/console mcp:serve --env MCP_TOKEN=le-token-de-cette-instance

Vérifier l'enregistrement :

claude mcp list
claude mcp get tlr-mcp

Cette méthode est pratique pour un poste de développement unique mais ne se versionne pas avec le repo. Préférer .mcp.json pour l'écosystème multi-instances.

3. Vérifier le branchement

Au démarrage de session, Claude Code charge les serveurs MCP configurés et lance mcp:serve en sous-processus. Pour vérifier :

1. Ouvrir une session Claude Code dans le repo de travail.
2. Demander : « Quels outils MCP tu as ? » — la réponse doit lister list_docs, read_doc, search_docs.
3. Test fonctionnel : « Cherche dans la documentation ce qui concerne le MCP. » → doit déclencher search_docs et retourner des passages sourcés.

Si le serveur est correctement branché, Claude Code affiche une indication de connexion MCP active dans son interface.

4. Dépannage

Le serveur ne se connecte pas

• Vérifier que php est dans le PATH de la session Claude Code (ou utiliser le chemin absolu dans command).
• Vérifier que bin/console mcp:serve démarre sans erreur : php C:/src/telaria-app/bin/console mcp:serve en terminal (doit bloquer en attente de stdin).

Auth refusée (AUTH_REQUIRED ou -32000)

• MCP_TOKEN absent ou erroné dans .mcp.json. Re-vérifier la valeur du token (le hash en base ne doit pas être confondu avec le token brut).
• Token révoqué ou expiré : re-seed via php bin/console app:mcp:seed et reporter le nouveau token.

tools/list renvoie 0 outil ou erreur de scope

• Le token n'a pas les scopes nécessaires (tool:list_docs, tool:read_doc, tool:search_docs).
• Vérifier les scopes de l'ApiClient en base (cf. gouvernance MCP multi-instances).

Erreur CRLF sous Windows

• StdioTransport attend des lignes terminées par \n. Si le shell injecte des \r\n, le parse JSON-RPC casse. Claude Code gère normalement ce cas ; si le problème persiste, vérifier .gitattributes du repo tlr-mcp.

Pour aller plus loin

• Tuto Desktop + Cursor : brancher-mcp-claude-desktop-cursor.md
• Gouvernance tokens/scopes par instance : mcp-gouvernance-instances.md
• Déploiement VPS (HTTP Streamable V1.1) : mcp-vps.md
• Spec complète : specs/ia-mcp.md