Créer son premier serveur MCP, pas à pas

MCP veut dire Model Context Protocol : une façon standard de donner à un modèle comme Claude un accès direct à un service, une base de données, ou n’importe quel outil que tu as écrit toi-même. Si tu as déjà branché un connecteur MCP existant, tu sais déjà à quoi ça sert côté utilisateur. Ici, on passe de l’autre côté : écrire son propre serveur MCP, minimal mais fonctionnel, en suivant uniquement la documentation et les SDK officiels.

MCP, concrètement : qui parle à qui

L’architecture officielle distingue trois rôles. L’hôte MCP (MCP host) est l’application qui utilise l’IA, par exemple Claude Code ou Claude Desktop. Le client MCP est le composant que l’hôte crée pour maintenir une connexion dédiée à un serveur donné. Le serveur MCP, celui que tu vas écrire, est le programme qui fournit du contexte ou des actions aux clients qui s’y connectent. Un serveur local (le cas le plus courant quand tu débutes) communique via l’entrée-sortie standard du processus (le transport « stdio ») ; un serveur distant, hébergé quelque part, communique en HTTP.

Les trois briques que ton serveur peut exposer

La documentation officielle définit trois primitives principales côté serveur :

• Tools (outils) : des fonctions exécutables que l’application IA peut invoquer pour agir (appeler une API, interroger une base de données, manipuler un fichier).
• Resources (ressources) : des sources de données qui apportent du contexte (le contenu d’un fichier, un enregistrement de base de données, une réponse d’API).
• Prompts : des modèles de prompt réutilisables qui structurent une interaction avec le modèle (un prompt système, des exemples few-shot).

Pour un premier serveur, un seul tool suffit largement : c’est la brique la plus simple à comprendre et la plus utile immédiatement.

Écrire un serveur minimal en TypeScript

Crée un dossier de projet, puis installe le SDK officiel TypeScript et la librairie de validation qu’il utilise pour décrire les entrées d’un tool :

npm install @modelcontextprotocol/server
npm install zod

Crée un fichier (par exemple index.ts) avec ce contenu, repris du dépôt officiel du SDK :

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const server = new McpServer({ name: 'greeting-server', version: '1.0.0' });

server.registerTool(
    'greet',
    {
        description: 'Greet someone by name',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => ({
        content: [{ type: 'text', text: `Hello, ${name}!` }]
    })
);

async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
}

main();

Ce code fait trois choses : il crée un serveur nommé greeting-server, il enregistre un tool greet dont l’entrée attendue est validée par un schéma Zod ({ name: string }), puis il connecte le serveur au transport stdio, celui que les hôtes MCP utilisent pour parler à un serveur lancé localement comme un simple processus.

Si tu préfères Python

Le SDK officiel Python propose le même résultat avec une syntaxe à base de décorateurs. Installation :

uv add "mcp[cli]"

(ou pip install "mcp[cli]" si tu n’utilises pas uv). Le serveur minimal tient en quelques lignes :

from mcp.server import MCPServer

mcp = MCPServer("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

Pas de schéma à écrire à la main : les annotations de type Python (a: int, b: int) suffisent au SDK pour générer automatiquement la description de l’outil.

Le tester avec l’inspecteur MCP

Avant de brancher quoi que ce soit à Claude, teste ton serveur avec le MCP Inspector, l’outil de référence officiel pour ça. Il tourne via npx, sans installation préalable (il demande Node 22.19.0 ou plus récent) :

npx @modelcontextprotocol/inspector node chemin/vers/index.js

Cette commande ouvre une interface web locale où tu peux lister les tools exposés par ton serveur, appeler greet avec un nom en paramètre, et voir directement la réponse renvoyée. C’est l’étape qui évite de découvrir une erreur de schéma une fois le serveur branché à Claude. Si tu préfères rester dans le terminal, l’inspecteur propose aussi un mode CLI (--cli) et un mode TUI (--tui) qui font la même vérification sans navigateur.

Pour un serveur Python lancé avec mcp dev, l’inspecteur s’ouvre automatiquement :

uv run mcp dev server.py

Le brancher à Claude

Une fois le serveur validé, tu peux le déclarer dans Claude Code avec claude mcp add, en séparant bien les options de Claude Code (avant le --) de la commande qui lance ton serveur (après le --) :

claude mcp add --transport stdio greeting-server -- node chemin/vers/index.js

Claude Code enregistre le serveur immédiatement. Tu peux vérifier qu’il apparaît bien avec claude mcp list, et le retirer avec claude mcp remove greeting-server si besoin. À partir de là, dans une conversation, Claude peut découvrir ton tool greet et l’appeler exactement comme n’importe quel autre outil MCP.

Aller plus loin : une ressource, et plusieurs clients à la fois

Un tool n’est qu’une des trois briques possibles. Le SDK Python expose une resource de façon très proche d’un tool, avec un décorateur dédié :

@mcp.resource("config://app-name")
def get_app_name() -> str:
    """Nom de l'application, exposé en lecture seule comme resource."""
    return "greeting-server"

La différence de fond entre les deux : un tool est fait pour agir (il peut avoir des effets de bord), une resource est faite pour être lue, un peu comme une requête GET qui ne modifie rien. Si ton serveur ne fait que donner accès à des données déjà existantes, une resource est souvent plus honnête à exposer qu’un tool.

Deuxième chose à savoir avant d’aller plus loin : un serveur en transport stdio, comme celui de cet article, ne sert qu’un seul client à la fois — parfait pour développer en local ou pour un usage strictement personnel. Le jour où tu veux qu’un même serveur soit interrogeable par plusieurs personnes en même temps, la documentation officielle recommande de passer au transport Streamable HTTP, conçu justement pour ce cas : le serveur tourne alors quelque part en continu (souvent hébergé), et chaque client ouvre sa propre connexion HTTP vers lui, sans avoir besoin d’un processus local dédié à chaque utilisateur.

Si ce serveur MCP fait partie d’un projet noté (un TP, un projet de fin de module), vérifie d’abord les règles d’usage de l’IA de ton établissement : utiliser Claude pour t’aider à écrire ou déboguer ton code n’est pas forcément traité pareil d’un cours à l’autre.

À retenir

• MCP relie un hôte (comme Claude Code), un client, et un serveur que tu écris toi-même.
• Trois primitives possibles côté serveur : tools (actions), resources (données), prompts (modèles d’interaction). Un tool suffit pour commencer.
• SDK TypeScript officiel : npm install @modelcontextprotocol/server, une instance McpServer, un registerTool, un transport stdio.
• SDK Python officiel : uv add "mcp[cli]", une instance MCPServer, un tool déclaré avec @mcp.tool().
• Teste toujours avant de brancher : npx @modelcontextprotocol/inspector node ton-serveur.js.
• Connexion à Claude Code : claude mcp add --transport stdio <nom> -- <commande>, puis claude mcp list pour vérifier.