# Serveurs MCP et Claude Code : guide pratique de connexion et de création > Comment étendre les capacités de Claude Code grâce au Model Context Protocol : connexion du système de fichiers, GitHub, PostgreSQL, Brave Search et développement d'un serveur personnalisé en TypeScript. Claude Code « out of the box » sait déjà lire des fichiers locaux, exécuter des commandes dans le terminal et modifier le code source du projet. Cependant, pour les tâches de développement réelles, cela s'avère souvent insuffisant : il devient nécessaire d'extraire des informations d'une base de données PostgreSQL, de vérifier les Pull Requests ouvertes sur GitHub, de récupérer la documentation à jour depuis le cloud ou d'envoyer des requêtes vers une API interne d'entreprise. C'est précisément pour répondre à ce besoin qu'a été créé le **Model Context Protocol (MCP)** — un standard ouvert qui transforme Claude Code d'un simple assistant local en un véritable centre d'orchestration de systèmes et services externes. Dans ce guide pratique, nous décortiquerons l'architecture MCP, apprendrons à connecter des serveurs officiels prêts à l'emploi, examinerons la création de votre propre serveur en TypeScript et consoliderons ces compétences avec des exercices concrets. --- ## 1. Qu'est-ce qu'un MCP Server ? Le **Model Context Protocol (MCP)** est un protocole de communication ouvert, développé par Anthropic, qui standardise les interactions entre les modèles de langage (LLM) et les outils externes ou sources de données. Au lieu d'écrire des plugins uniques pour chaque service, MCP introduit une interface client-serveur uniforme. ```text ┌─────────────────────────────────────────────────────────────┐ │ Claude Code (Client) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Serveur MCP (Adaptateur) │ └──────┬───────────────────────┼───────────────────────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Système │ │ API GitHub │ │ Base de │ │ de fichiers │ │ et Issues │ │ données │ └─────────────┘ └─────────────┘ │ PostgreSQL │ └─────────────┘ ``` Tout MCP Server expose trois primitives fondamentales au modèle : - **Tools (Outils)** — fonctions exécutables avec des paramètres typés via JSON Schema, que Claude Code peut appeler autonomement lors de la résolution d'une tâche (par exemple, `create_issue`, `execute_query`). - **Resources (Ressources)** — données passives ou schémas que l'assistant peut lire comme contexte d'entrée (fichiers, schémas de BD, logs). - **Prompts (Modèles de prompts)** — scénarios contextuels prêts à l'emploi qui simplifient l'exécution de tâches répétitives courantes. ### Comparaison des capacités de Claude Code | Scénario d'utilisation | Sans MCP (Claude Code de base) | Avec des MCP Servers connectés | | :--- | :--- | :--- | | **Gestion des fichiers** | Uniquement dans le répertoire courant du projet | Accès à tout dossier autorisé et aux notes | | **Données du dépôt** | Fichiers locaux via `git diff` / `git log` | Lecture des issues, PR, code review et API GitHub | | **Bases de données** | Seulement si un client CLI local est installé | Lecture directe des schémas, tables et exécution SQL | | **Recherche d'informations** | grep / ripgrep local dans les fichiers | Recherche web actualisée en temps réel via Brave/Tavily | | **Services internes** | Inaccessibles sans écrire des scripts bash complexes | Appel de fonctions d'API internes via un SDK typé | --- ## 2. Architecture et principe de fonctionnement de MCP L'architecture d'interaction repose sur le protocole standard **JSON-RPC 2.0**. Dans la plupart des scénarios locaux, la communication se fait via les flux standards d'entrée/sortie (`stdio`), tandis que pour les serveurs distants, elle utilise Server-Sent Events (`SSE`) ou HTTP. ### Cycle de vie étape par étape d'une requête 1. **Initialisation et Handshake :** Au démarrage de la session, Claude Code lit le fichier de configuration, lance les processus des serveurs indiqués et demande la liste des outils pris en charge (`tools/list`). 2. **Publication des capacités :** Chaque MCP Server retourne la liste de ses méthodes accompagnée des JSON Schemas des paramètres et d'une description détaillée de leur usage. 3. **Évaluation de l'intention :** Lorsque vous formulez une tâche en langage naturel, Claude confronte votre requête aux outils disponibles. 4. **Appel de l'outil :** Si la tâche nécessite des données externes, le modèle envoie une requête structurée `tools/call` au serveur avec des arguments valides. 5. **Exécution côté serveur :** Le serveur interagit avec l'API externe, la base de données ou le disque et renvoie le résultat au client. 6. **Génération de la réponse :** Une fois les données brutes reçues, Claude les interprète et vous fournit une réponse finale structurée. > [!NOTE] > L'interaction est transparente pour le développeur : vous n'avez pas besoin de mémoriser les noms de fonctions ni la syntaxe de l'API. Claude sélectionne automatiquement l'outil le plus approprié en fonction du contexte de la tâche. --- ## 3. Comment connecter un MCP Server à Claude Code La connexion des serveurs s'effectue via une configuration JSON dans le bloc `mcpServers`. Claude Code prend en charge deux niveaux de configuration : 1. **Configuration du projet (`.claude/settings.json`)** — s'applique uniquement au répertoire courant et peut être versionnée dans le dépôt pour toute l'équipe. 2. **Configuration globale (`~/.claude/settings.json`)** — disponible pour tous les projets de l'utilisateur courant sur la machine. :::tabs === Projet (.claude/settings.json) ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "./docs" ] } } } ``` === Global (~/.claude/settings.json) ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` ::: ### Structure des paramètres de configuration Chaque entrée de serveur dans la section `mcpServers` comprend trois champs clés : | Paramètre | Type | Obligatoire | Description et usage | Exemples de valeurs | | :--- | :--- | :--- | :--- | :--- | | `command` | `string` | Oui | Commande exécutable pour lancer le processus du serveur | `"npx"`, `"node"`, `"uvx"`, `"docker"` | | `args` | `string[]` | Oui | Tableau des arguments de lancement (nom du paquet, chemins, options) | `["-y", "@anthropic-ai/mcp-filesystem", "/path"]` | | `env` | `object` | Non | Dictionnaire des variables d'environnement pour l'authentification et les clés API | `{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}` | > [!TIP] > Si vous utilisez des outils Python, vous pouvez remplacer `npx` par `uvx` (issu du gestionnaire de paquets `uv`), par exemple : `"command": "uvx", "args": ["mcp-server-git"]`. --- ## 4. Catalogue des MCP Servers prêts à l'emploi Anthropic et la communauté open-source ont développé des serveurs prêts à l'emploi pour les outils les plus populaires. Il n'est pas nécessaire de coder from scratch — il suffit de connecter le paquet npm ou python correspondant. | Serveur | Paquet officiel | Accès / Authentification | Fonctionnalités principales | | :--- | :--- | :--- | :--- | | **Filesystem** | `@anthropic-ai/mcp-filesystem` | Chemins vers les dossiers locaux autorisés | Lecture, écriture et recherche dans les répertoires externes | | **GitHub** | `@anthropic-ai/mcp-github` | Personal Access Token (`GITHUB_TOKEN`) | Recherche dans les dépôts, analyse des issues, ouverture de PR | | **PostgreSQL** | `@anthropic-ai/mcp-postgres` | Chaîne de connexion (`connectionString`) | Inspection des schémas, lecture des tables, exécution de requêtes SQL | | **Brave Search** | `@anthropic-ai/mcp-brave-search` | Clé API de recherche (`BRAVE_API_KEY`) | Accès à l'information actuelle sur internet sans hallucinations | ### 1. Filesystem Server Donne à Claude Code accès aux dossiers situés hors du dépôt actuel (par exemple, un dossier global de documentation ou des notes Obsidian). ```json { "mcpServers": { "docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Developer/knowledge-base" ] } } } ``` ### 2. GitHub Server Permet à l'assistant d'interagir directement avec les dépôts de l'organisation : lire les issues, commenter les PR et vérifier l'état des pipelines. ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } } ``` ### 3. PostgreSQL Server Offre la possibilité à Claude d'exécuter des requêtes analytiques ou diagnostiques directement sur votre base de données locale ou distante. ```json { "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-postgres", "postgresql://postgres:password@localhost:5432/my_app_db" ] } } } ``` ### 4. Brave Search Server Intègre un moteur de recherche web, permettant à l'assistant de trouver la documentation fraîche, les correctifs de bugs récents ou les changements dans les bibliothèques. ```json { "mcpServers": { "brave-search": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-brave-search" ], "env": { "BRAVE_API_KEY": "BSAu_your_brave_search_api_key" } } } } ``` --- ## 5. Comment Claude Code utilise MCP dans le dialogue Une fois le serveur ajouté à la configuration, aucune commande spéciale ni préfixe n'est requis. Claude Code analyse votre requête en langage naturel et décide seul quand faire appel à un outil. ### Exemple de scénario : travail avec GitHub **Requête utilisateur :** > "Vérifie quelles issues ouvertes me sont assignées dans le dépôt acme/platform, et affiche une courte liste des plus prioritaires." **Processus interne de Claude Code :** 1. Le modèle reconnaît que les fichiers locaux sont insuffisants pour répondre. 2. Il forme un appel `mcp__github__search_issues` avec les filtres `repo:acme/platform state:open assignee:@me`. 3. Il reçoit une réponse JSON structurée du serveur GitHub. 4. Il formate la réponse sous une forme lisible. ```markdown 3 tâches ouvertes vous sont assignées : 1. **#42 — Fix login redirect loop** (Priorité : Haute, Créée il y a 2 jours) 2. **#38 — Add rate limiting to auth API** (Priorité : Moyenne, Créée il y a 5 jours) 3. **#35 — Update user profile settings page** (Priorité : Basse, Créée il y a 1 semaine) Souhaitez-vous analyser plus en détail le code afin de corriger l'erreur dans la tâche #42 ? ``` --- ## 6. Création d'un MCP Server personnalisé en TypeScript Si les solutions prêtes ne suffisent pas et que vous avez besoin d'un outil spécifique pour la logique métier ou les microservices internes, vous pouvez écrire un MCP Server vous-même en quelques minutes grâce au SDK officiel `@modelcontextprotocol/sdk`. ### Étape 1. Initialisation et installation des dépendances Créez un répertoire dédié et installez les bibliothèques : ```bash mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx ``` ### Étape 2. Implémentation du serveur (`server.ts`) Créez le fichier `server.ts` avec la définition du serveur et d'un outil custom : ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 1. Ініціалізуємо сервер з метаданими const server = new McpServer({ name: "internal-crm-server", version: "1.0.0", }); // 2. Реєструємо інструмент пошуку користувача server.tool( "lookup-user", "Отримати профіль клієнта за його адресою електронної пошти", { email: z.string().email().describe("Email адреса зареєстрованого користувача"), }, async ({ email }) => { // Тут може бути реальний запит до CRM, Redis чи внутрішнього API const mockUser = { id: "usr_99812", email, name: "Олександр Коваленко", plan: "Enterprise", status: "active", createdAt: "2024-03-15T10:00:00Z", }; return { content: [ { type: "text", text: JSON.stringify(mockUser, null, 2), }, ], }; } ); // 3. Запускаємо сервер через стандартний stdio транспорт async function run() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Internal CRM MCP server started on stdio"); } run().catch((error) => { console.error("Server startup error:", error); process.exit(1); }); ``` ### Étape 3. Connexion du serveur à Claude Code Ajoutez le serveur créé dans `.claude/settings.json` de votre projet : ```json { "mcpServers": { "crm": { "command": "npx", "args": [ "tsx", "/Users/username/Developer/my-mcp-server/server.ts" ] } } } ``` > [!TIP] > L'utilisation de l'utilitaire `tsx` permet d'exécuter des fichiers TypeScript directement, sans compilation préalable via `tsc`. --- ## 7. Sécurité et isolation lors de l'utilisation de MCP MCP augmente considérablement l'autonomie de Claude Code, mais donne aussi au code la capacité d'interagir avec votre système d'exploitation et vos services externes. Pour préserver la sécurité de l'environnement de travail, respectez les règles suivantes : ### 1. Le serveur s'exécute avec vos droits système Le MCP Server fonctionne dans le contexte de l'utilisateur courant du système d'exploitation. Si le serveur contient des erreurs ou du code malveillant, il peut lire les fichiers auxquels votre utilisateur a accès. ### 2. Protection des secrets et clés API Ne stockez jamais de clés de production dans le dépôt. Utilisez la configuration globale `~/.claude/settings.json` pour les tokens sensibles ou passez les variables d'environnement via des fichiers `.env` inclus dans `.gitignore`. ### 3. Audit des paquets tiers avant connexion Auditez toujours le dépôt ou le paquet npm d'un MCP Server tiers avant de l'ajouter à la configuration : - Vérifiez la disponibilité du code source ouvert. - Contrôlez le nombre de téléchargements et l'activité du dépôt. - Faites attention aux requêtes réseau effectuées par le serveur au démarrage. ### 4. Séparation des niveaux de configuration ```text ┌─────────────────────────────────────────────────────────────┐ │ ~/.claude/settings.json │ │ Outils globaux : GitHub, Recherche Web, Navigateur │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ .claude/settings.json │ │ Outils locaux : Dev PostgreSQL, scripts spécifiques │ └─────────────────────────────────────────────────────────────┘ ``` > [!WARNING] > Évitez de connecter des serveurs avec des droits d'écriture sur les bases de données de production (Production DB) en mode développement. Pour les tests, utilisez des répliques Read-Only dédiées ou des conteneurs Docker locaux. --- ## 8. Atelier pratique : configuration pas à pas Effectuez deux exercices pratiques pour consolider le matériel et vérifier la bonne connexion des serveurs. ### Exercice 1. Connexion du GitHub MCP Server 1. Créez un nouveau Personal Access Token (classic ou fine-grained) sur GitHub dans la section `Settings` → `Developer settings` avec les permissions `repo` et `read:org`. 2. Ouvrez ou créez le fichier de configuration `~/.claude/settings.json` : ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_ваш_токен_тут" } } } } ``` 3. Lancez une nouvelle session Claude Code et exécutez le prompt de vérification : ```bash claude ``` > **Prompt de test :** > "Affiche mes 5 derniers dépôts mis à jour sur GitHub et leur statut." - [ ] Claude Code a appelé l'outil GitHub avec succès sans erreurs d'authentification. - [ ] La liste actuelle des dépôts a été récupérée. --- ### Exercice 2. Connexion du Filesystem Server pour des notes externes Donnez à Claude accès à un dossier externe contenant de la documentation ou des notes d'architecture : 1. Ajoutez le serveur `filesystem` dans `.claude/settings.json` : ```json { "mcpServers": { "external-docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/шлях/до/вашої/папки/з_документами" ] } } } ``` 2. Testez le fonctionnement avec une requête à Claude : > **Prompt de test :** > "Trouve dans le dossier external-docs tous les fichiers markdown décrivant l'architecture de l'API, et fais-en un bref résumé." - [ ] Claude a lu les fichiers situés hors du répertoire de travail du projet. - [ ] Il a synthétisé les informations trouvées sans perte de contexte. --- ## 9. Auto-évaluation rapide des connaissances Vérifiez à quel point vous maîtrisez les principes fondamentaux de l'architecture Model Context Protocol. ### Question 1. Quelle est la fonction principale d'un MCP Server ? - **A.** Une VM cloud pour héberger les modèles Claude - **B.** Un programme adaptateur qui offre au modèle de langage un accès standardisé aux outils et données externes - **C.** Une bibliothèque pour la compression automatique des embeddings vectoriels - **D.** Un serveur web pour publier le code compilé du projet > [!TIP] > **Réponse correcte : B.** > Un MCP Server est un processus local ou distant agissant comme un pont entre le modèle et les services tiers, fournissant au modèle des Tools, Resources et Prompts standardisés. --- ### Question 2. Dans quel fichier conserve-t-on la configuration des serveurs destinée uniquement à un dépôt spécifique ? - **A.** `~/.claude/settings.json` - **B.** `package.json` - **C.** `.claude/settings.json` à la racine du projet - **D.** `CLAUDE.md` > [!TIP] > **Réponse correcte : C.** > Pour la configuration au niveau d'un projet individuel, on utilise `.claude/settings.json`. Le fichier dans le répertoire personnel `~/.claude/settings.json` gère les outils globaux du développeur. --- ### Question 3. Comment Claude Code détermine-t-il quel outil utiliser pour répondre à une question ? - **A.** L'utilisateur doit explicitement spécifier le flag `--tool=name` avant chaque requête - **B.** Il faut préalablement appeler la commande `/mcp select` - **C.** Le modèle analyse la sémantique de la requête et les descriptions des JSON Schemas des outils, choisissant le pertinent de manière autonome - **D.** Tous les outils sont appelés simultanément, et les résultats superflus sont rejetés > [!TIP] > **Réponse correcte : C.** > Grâce aux descriptions et schémas de paramètres standardisés, Claude évalue l'intention de l'utilisateur et appelle de manière autonome l'outil requis, en transmettant des arguments valides. --- ## 10. Conclusion et checklist d'architecture Le Model Context Protocol rend Claude Code flexible et agentique. Plutôt que de copier manuellement le contenu des fichiers ou les schémas de bases de données dans le dialogue, vous configurez une fois pour toutes des canaux de communication permanents. ### Checklist de préparation de votre environnement - [x] **Niveaux de configuration :** Les services globaux (GitHub, Web Search) sont placés dans `~/.claude/settings.json`, tandis que ceux spécifiques au projet (BD, docs) sont dans `.claude/settings.json`. - [x] **Sécurité :** Les tokens et mots de passe ne sont pas commités dans le dépôt public ; les bases de données sont connectées avec des droits minimaux (Read-Only pour l'analyse). - [x] **Test des outils :** Le fonctionnement des serveurs est vérifié par des requêtes ciblées après le lancement de la session. - [x] **Extensibilité :** Un template de serveur personnalisé en TypeScript via `@modelcontextprotocol/sdk` a été créé pour les tâches internes spécifiques.