Créer un Serveur MCP pour Claude Code : Tutoriel Python & TypeScript 2026

Sommaire

Qu'est-ce qu'un serveur MCP et pourquoi en créer un personnalisé ? {#introduction}

Créer un serveur MCP pour Claude Code, c'est exposer une fonctionnalité de votre métier (API interne, base de données, workflow propriétaire, outil spécifique) directement à l'IA pour qu'elle puisse l'appeler comme un outil natif. Le Model Context Protocol (MCP) est devenu en 18 mois le standard de facto pour connecter les LLM aux données du monde réel, avec plus de 2 000 serveurs communautaires publiés au registre officiel et un téléchargement quotidien moyen d'un million pour FastMCP.

Plutôt que de tout coder à la main dans un script ad hoc, vous publiez un serveur MCP qui décrit ses capacités (tools, resources, prompts) et Claude Code les découvre automatiquement. C'est la suite logique après avoir maîtrisé l'usage des serveurs MCP existants : nous avons déjà couvert [comment connecter Claude Code à des outils via MCP](/blog/mcp-model-context-protocol-claude-code) ; ce tutoriel s'attaque à l'étape suivante.

Pourquoi créer un serveur MCP custom plutôt qu'utiliser ceux existants ?

Trois raisons reviennent systématiquement chez les équipes qui passent au stade custom :

Prérequis pour créer un serveur MCP Claude Code {#prerequis}

Avant de coder, vérifiez :

Installez uv rapidement :

curl -LsSf https://astral.sh/uv/install.sh | sh

Créer un serveur MCP en Python avec FastMCP (pas à pas) {#python-fastmcp}

FastMCP 3.x est la voie royale pour créer un serveur MCP en Python en 2026. La librairie est utilisée derrière 70% des serveurs MCP toutes langues confondues et expose une API ultra concise basée sur des décorateurs. Voici comment construire un serveur MCP minimal mais complet exposant les trois primitives.

Étape 1 — Initialiser le projet

mkdir mcp-mon-serveur && cd mcp-mon-serveur
uv init
uv add fastmcp

Étape 2 — Écrire un premier tool

Créez server.py :

from fastmcp import FastMCP

mcp = FastMCP("mon-serveur")

@mcp.tool
def add(a: int, b: int) -> int:
    """Additionne deux nombres entiers."""
    return a + b

if __name__ == "__main__":
    mcp.run()  # transport stdio par défaut

C'est tout. Quatre lignes : un décorateur, des type hints qui deviennent automatiquement un schéma JSON, et Claude Code peut déjà appeler la fonction.

Étape 3 — Ajouter une resource (donnée lecture seule)

Une resource correspond à une URL que Claude peut "lire" comme un fichier. Idéal pour exposer des configs, logs, articles de knowledge base :

@mcp.resource("config://app")
def app_config() -> str:
    return "Mode debug activé, version 1.2.3"

Étape 4 — Ajouter un prompt (slash command réutilisable)

Les prompts apparaissent dans Claude Code comme des templates paramétrables :

@mcp.prompt
def review_code(language: str, code: str) -> str:
    return f"Revois ce code {language} :\n\n{code}"

Étape 5 — Lancer et tester localement

uv run server.py

Le serveur démarre en mode stdio. Pour tester sans Claude Code, vous pouvez utiliser l'inspecteur MCP officiel :

npx @modelcontextprotocol/inspector uv run server.py

Créer un serveur MCP en TypeScript avec le SDK officiel {#typescript-sdk}

Pour les équipes JavaScript, le SDK TypeScript officiel @modelcontextprotocol/sdk (v1.29+) reste la référence. La syntaxe est un peu plus verbeuse que FastMCP mais elle suit la même logique : déclarer tools, resources et prompts via un serveur, puis brancher un transport.

Étape 1 — Initialiser le projet TypeScript

mkdir mcp-server-ts && cd mcp-server-ts
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init

Étape 2 — Écrire un serveur MCP avec un tool

Créez src/server.ts :

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: "mon-serveur-ts",
  version: "1.0.0",
});

server.tool(
  "add",
  "Additionne deux entiers",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

Étape 3 — Compiler et exécuter

npx tsc
node build/server.js

Avec ce squelette, vous pouvez ajouter server.resource() et server.prompt() exactement sur le même modèle pour exposer des données et des templates.

Comment connecter votre serveur MCP à Claude Code ? {#connexion-claude-code}

Une fois votre serveur prêt, l'enregistrement dans Claude Code se fait avec la CLI claude mcp add. Trois cas selon votre transport.

Connexion en stdio (local, le plus simple)

claude mcp add mon-serveur \
  --transport stdio \
  -- uv run /chemin/absolu/vers/server.py

Pour TypeScript :

claude mcp add mon-serveur-ts \
  --transport stdio \
  -- node /chemin/absolu/vers/build/server.js

Connexion en HTTP (serveur distant)

claude mcp add mon-serveur-distant \
  --transport http \
  --url https://mcp.monsite.com/sse \
  --header "Authorization: Bearer $TOKEN"

Vérifier l'installation

claude mcp list
claude mcp get mon-serveur

Dans Claude Code, tapez /mcp pour voir l'état du serveur et la liste des tools/resources/prompts exposés. Si tout est vert, vous pouvez maintenant demander à Claude d'utiliser vos outils en langage naturel.

Choisir entre transport stdio et HTTP : quelle différence ? {#stdio-vs-http}

Le choix du transport conditionne le déploiement, la latence et la sécurité. Voici les arbitrages concrets.

Règle pratique : commencez en stdio pour itérer vite localement. Passez en HTTP dès que plusieurs personnes doivent utiliser le serveur, ou qu'il doit tourner ailleurs que sur votre machine.

Sécuriser et déployer votre serveur MCP en production {#securite-deploiement}

Mettre un serveur MCP en production sans le sécuriser est l'erreur n°1 vue sur les projets MCP custom en 2026. Les bonnes pratiques minimales :

Gestion des secrets

Authentification HTTP

Pour un serveur exposé sur internet, FastMCP 3.x intègre désormais OAuth 2.1. Sans authentification, votre serveur MCP devient accessible à n'importe qui — une faille critique à éviter. À minima, exigez un Bearer token via un header personnalisé.

Déploiement cloud rapide

Pour un déploiement HTTP en quelques minutes :

# avec FastMCP en HTTP streamable
mcp.run(transport="streamable-http", host="0.0.0.0", port=3000)

Puis dockerisez et déployez sur Cloud Run, Fly.io ou Render. Activez OpenTelemetry pour observer les appels (FastMCP 3.x l'intègre nativement). Si vous orchestrez plusieurs serveurs en parallèle, jetez un œil au [tooling de monitoring de processus en arrière-plan](/blog/claude-code-monitor-tool-streaming-background-processes) côté Claude Code.

Erreurs fréquentes à éviter quand on débute {#erreurs}

Sept pièges récurrents repérés dans les questions des utilisateurs Reddit et Discord :

Pour aller plus loin sur la qualité d'écriture des outils exposés, le même esprit que pour les [commandes personnalisées Claude Code (skills)](/blog/claude-code-skills-creer-commandes-personnalisees) s'applique : un bon nom + une bonne description valent mieux qu'un schéma compliqué.

FAQ — Créer un serveur MCP Claude Code {#faq}

Quelle est la différence entre un serveur MCP et un plugin Claude Code ?

Un serveur MCP expose des outils via un processus séparé qui communique en JSON-RPC ; un plugin Claude Code est packagé dans l'écosystème Claude Code et installé via le marketplace. Les deux peuvent coexister : les plugins peuvent eux-mêmes embarquer des serveurs MCP. Voir notre [guide des plugins Claude Code 2026](/blog/claude-code-plugins-marketplace-installer-2026) pour la distinction complète.

Faut-il préférer Python ou TypeScript pour créer un serveur MCP ?

Les deux sont parfaitement supportés. Python (FastMCP) est plus concis et a la plus grosse communauté côté MCP (70% des serveurs déployés). TypeScript s'impose si vous avez déjà un backend Node ou que vous voulez déployer sur des plateformes serverless type Cloudflare Workers. Pour un prototype rapide, FastMCP gagne.

Combien de tools peut-on exposer dans un seul serveur MCP ?

Techniquement il n'y a pas de limite stricte, mais en pratique au-delà de 8-12 tools, Claude commence à mal sélectionner. La bonne pratique est de découper en plusieurs serveurs thématiques (un serveur "facturation", un serveur "support", etc.) plutôt qu'un serveur monolithique. Cela s'aligne avec la philosophie [sub-agents et workflows dynamiques](/blog/claude-code-sub-agents-guide-pratique-2026).

Peut-on tester un serveur MCP sans installer Claude Code ?

Oui — utilisez l'inspecteur MCP officiel : npx @modelcontextprotocol/inspector . Il ouvre une interface web qui permet de lister les tools, de les invoquer manuellement et de visualiser les réponses, sans dépendre de Claude Code.

Quels sont les coûts d'héberger un serveur MCP en production ?

Un serveur MCP simple en mode HTTP tient sur un Cloud Run ou Fly.io à 5-15 € par mois. Le coût explose surtout si votre serveur appelle des APIs payantes ou consomme beaucoup de tokens LLM en interne. Pour comparer les budgets globaux côté Claude, voir [combien coûte Claude Code en 2026](/blog/combien-coute-claude-code-prix-abonnement-api-2026).

Mon serveur MCP fonctionne en local mais pas dans Claude Code, pourquoi ?

99% des cas viennent de chemins relatifs, logs sur stdout ou environnement Python/Node différent entre votre terminal et celui de Claude Code. Vérifiez en lançant exactement la commande inscrite dans claude mcp get depuis un terminal vierge. Si elle échoue, vous tenez le coupable.

Existe-t-il un registre officiel pour publier mon serveur MCP ?

Oui, le registre MCP officiel (registry.modelcontextprotocol.io) recense plus de 2 000 serveurs communautaires. Publier votre serveur le rend découvrable et installable via claude mcp install directement.

Aller plus loin : ressources liées