Un guide pratique pour configurer des serveurs MCP (Model Context Protocol) avec Claude Code : installation, configuration, modes de transport, définitions d’outils et connexion des modèles d’IA à des API et services réels. Des exemples concrets que vous pouvez copier et exécuter dès aujourd’hui.
Si vous avez passé du temps dans Claude Code et remarqué la section MCP dans les paramètres, vous vous êtes probablement demandé ce qu’elle fait réellement, à quel point elle est difficile à mettre en place et si l’effort en vaut la peine. Réponse courte : oui, l’effort en vaut nettement la peine. MCP (Model Context Protocol) est le mécanisme qui permet à Claude de sortir de sa fenêtre de contexte pour appeler de vraies fonctions, interroger de vraies bases de données et interagir avec de vraies API, le tout depuis une conversation.
Cet article passe en revue tout ce qu’il faut savoir, de la compréhension de ce qu’est MCP jusqu’à l’exécution de votre premier serveur personnalisé avec Claude Code, avec de vrais exemples de configuration que vous pouvez copier immédiatement.
MCP est un protocole ouvert développé par Anthropic qui standardise la manière dont les modèles d’IA communiquent avec des outils et des sources de données externes. Imaginez une poignée de main structurée : votre serveur déclare les outils qu’il propose, et Claude les appelle avec les bons arguments puis traite les résultats.
Avant MCP, chaque intégration était sur mesure. Vous rédigiez des prompts système spécifiques, bricoliez des schémas d’appel de fonctions et espériez que le modèle suive la spécification. MCP regroupe tout cela dans une couche unique et prévisible.
Le protocole définit trois primitives de base :
| Primitive | Description |
|---|---|
| Outils | Fonctions que le modèle peut appeler (par exemple recherche, récupération, écriture de fichier) |
| Ressources | Données que le modèle peut lire (par exemple fichiers, enregistrements de base de données) |
| Prompts | Modèles de prompts réutilisables exposés par le serveur |
Ces trois primitives couvrent pratiquement tous les scénarios d’intégration que vous rencontrerez. Les outils gèrent les actions, les ressources gèrent l’accès aux données et les prompts gèrent les schémas d’interaction réutilisables. Le protocole est indépendant du transport : le même code de serveur fonctionne via stdio pour le développement local et via HTTP pour les déploiements en production.
Les serveurs MCP fonctionnent selon l’un de deux modes de transport. Savoir les distinguer vous fera gagner des heures de débogage.
Le client (Claude Code) lance votre serveur comme sous-processus et communique via stdin/stdout. C’est la configuration la plus simple pour les outils locaux et les flux de travail personnels. Pas de ports, pas de réseau, pas d’authentification nécessaire.
{
"mcpServers": {
"my-tool": {
"command": "node",
"args": ["/absolute/path/to/server/dist/index.js"]
}
}
}
Votre serveur tourne comme un processus HTTP indépendant. Claude Code s’y connecte via le réseau. C’est le bon choix pour les serveurs partagés en équipe, les déploiements cloud ou tout serveur qui doit rester actif entre les sessions.
{
"mcpServers": {
"my-tool": {
"url": "http://localhost:3000/sse"
}
}
}
💡 Commencez par stdio. Il ne demande aucune configuration réseau et il est beaucoup plus facile à déboguer. Passez au transport HTTP seulement lorsque vous avez besoin d’un accès partagé ou d’un état de serveur persistant.
Chaque serveur MCP commence de la même façon : installer le SDK officiel et configurer TypeScript pour ESM.
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
Initialisez TypeScript :
npx tsc --init
Modifiez tsconfig.json pour cibler les modules ESM :
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"strict": true
}
}
Ajoutez des scripts dans package.json :
{
"type": "module",
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts"
}
}
Le champ "type": "module" n’est pas facultatif. Sans lui, Node traite vos fichiers comme du CommonJS et chaque import ESM échoue au démarrage.
Créez src/index.ts et définissez votre premier outil avec un schéma Zod typé :
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "my-first-server",
version: "1.0.0",
});
server.tool(
"get_weather",
"Get current weather for a city",
{
city: z.string().describe("City name"),
units: z.enum(["celsius", "fahrenheit"]).optional().default("celsius"),
},
async ({ city, units }) => {
const temp = units === "celsius" ? "22°C" : "72°F";
return {
content: [
{
type: "text",
text: `Weather in ${city}: ${temp}, partly cloudy`,
},
],
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Compilez-le et vérifiez qu’il se compile sans erreur :
npx tsc
node dist/index.js
Voilà un serveur MCP fonctionnel. Il expose un outil avec un schéma typé que Claude valide avant de l’appeler.
Ouvrez les paramètres de Claude Code et accédez à la section MCP. Ajoutez l’entrée de votre serveur en utilisant le chemin absolu vers la sortie compilée :
{
"mcpServers": {
"my-first-server": {
"command": "node",
"args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
}
}
}
Redémarrez Claude Code. Ouvrez une nouvelle conversation et posez la question : « Quel temps fait-il à Paris ? »
Si tout est correctement configuré, Claude appellera get_weather avec city: "Paris" et affichera le résultat dans sa réponse. Vous verrez l’appel de l’outil apparaître dans la conversation.
💡 Utilisez toujours des chemins absolus dans votre configuration MCP. Les chemins relatifs échouent silencieusement selon la façon dont Claude Code résout son répertoire de travail au lancement.
Les vrais serveurs ont besoin d’une séparation nette entre les définitions de schémas, les gestionnaires et la logique métier. Voici la structure de fichiers qui passe à l’échelle sans devenir ingérable :
src/
index.ts # Entry point and server setup
tools/
definitions.ts # Zod schemas for each tool input
handlers.ts # Business logic per tool
services/
api.ts # External API calls
db.ts # Database access layer
definitions.ts contient tous les schémas Zod :
import { z } from "zod";
export const searchInputSchema = {
query: z.string().min(1).describe("Search query text"),
limit: z.number().int().min(1).max(50).optional().default(10),
};
handlers.ts contient l’implémentation :
export async function handleSearch(
args: { query: string; limit?: number }
) {
const results = await searchApi(args.query, args.limit ?? 10);
return {
content: [{ type: "text" as const, text: JSON.stringify(results, null, 2) }],
};
}
index.ts assemble le tout dans un seul appel server.tool() par outil. Cette séparation vous permet de tester les gestionnaires sans serveur en cours d’exécution et de modifier les schémas sans toucher à la logique métier.
Ce sont les erreurs qui piègent presque tout le monde lors de la création de leur premier serveur MCP.
1. Extensions de fichier .js manquantes dans les imports
La résolution de modules Node16 exige des extensions .js explicites, même dans les fichiers source TypeScript. Les omettre provoque des échecs d’import à l’exécution, déroutants car le compilateur TypeScript ne les détecte pas.
// This fails at runtime with ERR_MODULE_NOT_FOUND
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
// This works correctly
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2. Utiliser console.log() dans les serveurs stdio
En mode stdio, stdout est le canal du protocole. Tout appel à console.log() écrit du texte arbitraire dans ce canal et corrompt le flux MCP. Utilisez console.error() pour toute sortie de débogage.
3. await manquant lors de la connexion du serveur
// Wrong: process may exit before connection completes
server.connect(transport);
// Correct: wait for connection handshake
await server.connect(transport);
4. Chemins relatifs dans la configuration de Claude Code
Claude Code se lance depuis des répertoires de travail variables. Utilisez toujours des chemins absolus codés en dur, ou résolvez-les au démarrage à l’aide de import.meta.url.
5. Descriptions d’outils trop générales
Claude se base sur la description de votre outil pour décider quand l’appeler. Des descriptions vagues comme « fait des choses » conduisent à un outil appelé trop souvent, ou jamais. Soyez précis : « Récupère une pull request GitHub à partir du propriétaire, du dépôt et du numéro de PR. »
Lorsque votre serveur doit être partagé au sein d’une équipe ou exécuté dans un environnement cloud, HTTP avec SSE est le transport adapté :
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import express from "express";
const app = express();
const server = new McpServer({ name: "team-server", version: "1.0.0" });
const transports: Record<string, SSEServerTransport> = {};
app.get("/sse", async (req, res) => {
const transport = new SSEServerTransport("/messages", res);
transports[transport.sessionId] = transport;
await server.connect(transport);
});
app.post("/messages", express.json(), async (req, res) => {
const sessionId = req.query.sessionId as string;
const transport = transports[sessionId];
if (transport) await transport.handlePostMessage(req, res);
});
app.listen(3000, () => console.error("MCP server listening on :3000"));
Chaque client Claude Code stocke son propre transport de session, afin que plusieurs utilisateurs puissent se connecter simultanément sans interférence.
Les ressources permettent à Claude de lire des données structurées sans appels d’outils explicites. Ce sont la primitive adaptée pour la configuration, la documentation ou l’état en cache que Claude doit connaître, sans que vous ayez besoin de définir un outil de récupération dédié.
server.resource(
"config://app",
"Application configuration and feature flags",
async (uri) => ({
contents: [
{
uri: uri.toString(),
mimeType: "application/json",
text: JSON.stringify({
version: "2.1.0",
features: { darkMode: true, betaSearch: false },
limits: { maxResults: 50, timeoutMs: 5000 },
}),
},
],
})
);
Claude peut consulter config://app dans son contexte et lire ces données de manière proactive, ce qui réduit le nombre d’appels d’outils nécessaires dans une conversation.
MCP Inspector est indispensable pendant le développement. Il vous offre une interface visuelle pour appeler directement vos outils sans passer par Claude Code :
npx @modelcontextprotocol/inspector node dist/index.js
Ouvrez http://localhost:5173. Vous verrez tous les outils enregistrés, leurs schémas et un formulaire pour appeler chacun directement avec des entrées arbitraires. Le JSON brut de la requête et de la réponse est visible, ce qui permet de repérer facilement les incompatibilités de types ou les champs manquants.
Pour les serveurs HTTP :
npx @modelcontextprotocol/inspector http://localhost:3000/sse
💡 Surveillez les incohérences de schéma. Si Claude Code indique qu’un outil est enregistré mais ne l’appelle jamais, la cause la plus fréquente est un schéma Zod qui rejette les arguments fournis par le modèle. L’Inspector vous permet de reproduire ce problème sans impliquer Claude.
L’un des schémas à plus forte valeur ajoutée consiste à créer des serveurs MCP qui orchestrent des appels vers plusieurs modèles d’IA. Votre serveur devient la couche intermédiaire, et Claude Code devient le coordinateur.
Vous pouvez exposer un outil qui route les requêtes vers Deepseek R1 pour le raisonnement approfondi, GPT 5 pour l’écriture créative, ou Llama 4 Scout Instruct pour le traitement rapide de documents. Claude décide quel outil appeler en fonction de la tâche à accomplir.
server.tool(
"route_to_model",
"Route a task to the most suitable language model for the job",
{
task: z.enum(["reasoning", "creative", "summarize"]),
input: z.string().describe("The text input to process"),
},
async ({ task, input }) => {
const modelMap = {
reasoning: "deepseek-r1",
creative: "gpt-5",
summarize: "llama-4-scout",
};
const result = await callModelApi(modelMap[task], input);
return { content: [{ type: "text", text: result }] };
}
);
Avec Claude Opus 4.7 comme orchestrateur et votre serveur MCP comme couche de répartition, vous obtenez un système multi-modèles qui route intelligemment, sans infrastructure complexe.
Picasso IA fournit un accès API à des modèles dont Claude 4.5 Sonnet, Gemini 2.5 Flash et Claude 4 Sonnet, ce qui permet de créer facilement des outils MCP multi-modèles, sans gérer des clés API et des bibliothèques clientes distinctes pour chaque fournisseur.
Les outils MCP ne doivent jamais lever d’exceptions non gérées. Renvoyez un contenu d’erreur structuré afin que Claude puisse signaler les échecs proprement et décider de la suite à donner :
server.tool(
"safe_fetch",
"Fetch content from an external URL",
{ url: z.string().url() },
async ({ url }) => {
try {
const response = await fetch(url);
if (!response.ok) {
return {
content: [
{
type: "text",
text: `Request failed: HTTP ${response.status} from ${url}`,
},
],
isError: true,
};
}
return { content: [{ type: "text", text: await response.text() }] };
} catch (err) {
return {
content: [{ type: "text", text: `Network error: ${String(err)}` }],
isError: true,
};
}
}
);
Le drapeau isError: true signale à Claude que l’appel a échoué. Claude décidera alors s’il doit réessayer, utiliser une solution de secours ou remonter l’erreur à l’utilisateur.
Une fois les bases maîtrisées, le champ des possibles s’ouvre. Voici les schémas que les équipes déploient aujourd’hui avec MCP :
| Cas d’usage | Ce qu’il fait |
|---|---|
| Outil de base de données | Claude écrit et exécute des requêtes SQL à portée limitée, en toute sécurité |
| Explorateur de système de fichiers | Accès en lecture et écriture à des répertoires de projet précis |
| Wrapper d’API | Expose Jira, GitHub ou Slack sous forme d’outils appelables |
| Pipeline d’images | Connecte Claude aux API de génération de texte vers image |
| Bac à sable de code | Exécute et teste des extraits de code dans un conteneur isolé |
| Récupérateur RAG | Recherche dans une base vectorielle et renvoie les fragments pertinents |
Le cas d’usage du pipeline d’images est particulièrement puissant. Vous construisez un serveur MCP qui accepte un prompt textuel de Claude, appelle un modèle texte vers image, importe le résultat dans un stockage cloud et renvoie l’URL, le tout en un seul appel d’outil que Claude enchaîne naturellement dans la conversation, sans code d’orchestration supplémentaire.
Pour les équipes qui construisent des flux de travail incluant la génération d’images, plus de 90 modèles disponibles sur des plateformes comme Picasso IA peuvent être intégrés comme outils MCP, ce qui donne à Claude un accès direct aux modèles de diffusion, aux upscalers et aux pipelines d’édition depuis une conversation.
Si vous voulez découvrir ce que permettent les modèles d’IA avant de construire vos propres intégrations MCP, Picasso IA met plus de 90 modèles de texte vers image et des dizaines de grands modèles de langage directement dans votre navigateur. Exécutez Claude Opus 4.6, GPT 5, Deepseek R1 ou Llama 4 Maverick Instruct sans aucune configuration.
C’est le moyen le plus rapide de tester le résultat d’un modèle avant de vous engager dans une intégration API. Choisissez un modèle, envoyez un prompt et voyez exactement avec quoi vous allez travailler dans votre chaîne d’outils MCP. Que vous génériez des images pour un projet, que vous testiez des structures de prompts ou que vous compariez la façon dont différents modèles traitent la même entrée, la plateforme vous donne un accès rapide, sans la charge d’une infrastructure.
Créez un compte, choisissez un modèle et commencez à générer des images ou du texte dès aujourd’hui, sans fichier de configuration.
Choisissez votre langue
