Créer un serveur MCP : tutoriel pas à pas en Python et TypeScript (2026)

Vous pouvez créer un serveur MCP que Claude appelle réellement en environ 15 minutes. Nous l'avons chronométré sur Node 20 et Python 3.11 : un outil add fonctionnel, tournant sur stdio et détecté par Claude Desktop, a pris 14 minutes la première fois et moins de 5 une fois la structure connue. Ce tutoriel construit le même serveur deux fois, une fois en Python avec FastMCP 2.x, une fois en TypeScript avec @modelcontextprotocol/sdk 1.x, pour que vous choisissiez votre stack et copiiez du vrai code. Si vous voulez d'abord l'architecture et la théorie du protocole, notre guide du Model Context Protocol la couvre ; ici, on construit.

Serveur MCP, démarrage rapide : ce que vous construisez

Un serveur MCP est un petit programme qui expose des outils, des données et des modèles de prompt à des clients IA comme Claude, Cursor ou VS Code via le Model Context Protocol. Vous écrivez le serveur une fois, et tout client compatible MCP peut l'appeler. Dans ce tutoriel, vous construisez un serveur avec deux outils (un calculateur add et un assistant fetch_url), vous le faites tourner localement sur stdio, vous le testez et vous le connectez à un vrai client.

Voici tout ce qu'il vous faut avant de commencer.

Les deux voies produisent un serveur au comportement identique. Choisissez le langage que votre équipe utilise déjà. Si vous n'avez pas de préférence, commencez par Python, car FastMCP rend le premier serveur plus court.

Qu'expose réellement un serveur MCP ?

Avant d'écrire du code, il est utile de connaître les trois choses qu'un serveur peut offrir. Un serveur MCP expose des tools (fonctions que le modèle peut appeler, comme « interroger la base de données »), des resources (données en lecture seule que le modèle peut charger, comme un fichier ou un enregistrement) et des prompts (modèles de prompt réutilisables). La plupart des serveurs que vous construirez seront centrés sur les outils ; les resources et prompts sont optionnels.

Serveur MCP, défini : un processus qui parle le Model Context Protocol et annonce une liste d'outils, de resources et de prompts qu'un client IA peut découvrir et invoquer à l'exécution.

Le client (Claude Desktop, par exemple) agit comme hôte. Il lance votre serveur ou s'y connecte, demande « quels outils as-tu ? », puis les appelle quand le modèle décide qu'un outil est utile. Vous n'appelez jamais le modèle depuis le serveur. Le flux va dans l'autre sens.

Cette direction compte. Votre serveur est un fournisseur passif. Il attend que le client se connecte, répond à la requête de découverte et exécute l'outil appelé. Gardez ce modèle mental en tête, et le reste de ce tutoriel devient évident.

Comment créer un serveur MCP en Python (pas à pas)

Python est la voie la plus rapide vers un serveur fonctionnel, car FastMCP gère la plomberie du protocole et transforme de simples fonctions en outils avec un décorateur. Tout ce qui suit utilise le SDK Python officiel. Voici les quatre étapes.

Étape 1 : configurer le projet. Utilisez uv, désormais le standard pour les projets MCP en Python :

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Si vous préférez pip : python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Étape 2 : écrire le serveur. Créez server.py :

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

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

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Deux choses à remarquer. La docstring devient la description de l'outil que le modèle lit, alors écrivez-la comme une instruction. Et les annotations de type (a: int) deviennent automatiquement le schéma d'entrée, FastMCP génère donc le schéma JSON pour vous.

Étape 3 : l'exécuter. mcp.run() démarre le serveur sur stdio, le transport que les clients lancent localement. Vous ne l'exécutez pas directement pendant le développement ; le client le lance. Pour un test rapide, utilisez le runner de dev :

uv run mcp dev server.py

Étape 4 : renvoyer une sortie propre. Un piège qu'il vaut mieux signaler maintenant : renvoyez une chaîne ou une valeur typée, pas un dict imbriqué en espérant qu'il s'affiche. Nous y reviendrons dans la section production, mais en bref, les types de retour ambigus peuvent être tronqués silencieusement dans certains clients.

C'est un serveur MCP Python complet. Deux outils, de vrais appels réseau, un schéma automatique. Ensuite, la même chose en TypeScript.

Comment créer un serveur MCP en TypeScript (pas à pas)

La voie TypeScript utilise directement le SDK TypeScript officiel et zod pour la validation des entrées. Elle est un peu plus verbeuse que FastMCP, mais les types sont excellents et elle se déploie proprement sur des hôtes Node.

Étape 1 : configurer le projet.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Étape 2 : écrire le serveur. Créez 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: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

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

Étape 3 : l'exécuter. Pendant le développement : npx tsx server.ts. Pour la production, compilez avec tsc et exécutez le .js construit avec Node. Notez la forme de retour : chaque outil renvoie { content: [{ type: "text", text: ... }] }. Ce tableau content explicite est l'équivalent TypeScript de la règle « renvoyez une chaîne propre » de Python. Le SDK veut des blocs de contenu typés, pas des objets bruts.

Étape 4 : valider les entrées avec zod. Le schéma z.string().url() rejette les entrées invalides avant l'exécution de votre handler, ce qui est exactement ce que vous voulez quand un modèle génère les arguments.

Les deux mêmes outils, le même comportement, du TypeScript idiomatique. Décidons maintenant comment les clients doivent atteindre votre serveur.

stdio vs Streamable HTTP : quel transport choisir ?

Les serveurs MCP communiquent via l'un de deux transports. stdio fait tourner le serveur comme un sous-processus local que le client lance et avec lequel il communique via l'entrée/sortie standard. Streamable HTTP fait tourner le serveur comme un service réseau auquel les clients se connectent via HTTP. Choisissez selon l'endroit où le serveur doit vivre.

La règle empirique : construisez et testez sur stdio, passez à Streamable HTTP seulement quand plus d'une personne ou machine a besoin du serveur. La plupart des serveurs n'ont jamais besoin de quitter stdio. Les appels mcp.run() et StdioServerTransport() ci-dessus sont déjà en stdio, vous êtes donc prêt pour le développement.

Comment tester votre serveur MCP avec l'Inspector

Avant d'intégrer votre serveur dans Claude, testez-le isolément avec le MCP Inspector. C'est une interface navigateur qui se connecte à votre serveur, liste ses outils et vous laisse les appeler à la main. Lancez-le contre votre serveur :

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

L'Inspector ouvre une page locale où vous voyez vos outils add et fetch_url, déclenchez un appel de test et lisez la réponse brute. C'est la meilleure habitude pour le développement MCP. Si le schéma d'un outil est mal formé ou une valeur de retour incorrecte, vous le voyez ici en quelques secondes plutôt que de fixer un échec silencieux dans Claude. Nous avons attrapé ainsi un schéma d'entrée erroné qui nous aurait sinon coûté un aller-retour complet de débogage par le client. Testez d'abord dans l'Inspector, à chaque fois.

Comment connecter votre serveur MCP à Claude Desktop, Claude Code et Cursor

Une fois l'Inspector satisfait, pointez un vrai client vers votre serveur. Chaque client lit un fichier de configuration qui lui indique comment lancer votre serveur sur stdio.

Claude Desktop. Modifiez claude_desktop_config.json (sur macOS : ~/Library/Application Support/Claude/claude_desktop_config.json) :

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Redémarrez Claude Desktop et vos outils apparaissent sous l'icône des connecteurs.

Claude Code. Ajoutez le serveur avec une commande depuis votre projet : claude mcp add demo-server -- uv run server.py. Claude Code l'enregistre dans la config du projet et le charge au lancement. Si vous utilisez aussi des hooks pour scripter Claude Code, notre guide des hooks de Claude Code se marie bien avec des outils MCP personnalisés.

Cursor. Ajoutez le même bloc mcpServers à .cursor/mcp.json à la racine du projet. La forme correspond à celle de Claude Desktop. Pour un exemple concret de serveur MCP tournant dans Claude Code, voyez comment nous avons branché Higgsfield dans Claude Code.

Utilisez des chemins absolus dans chaque config. Les chemins relatifs sont la cause la plus fréquente d'un serveur qui ne démarre pas.

Déployer un serveur MCP en production (auth et hébergement)

Quand votre serveur doit être partagé, faites-le passer de stdio à Streamable HTTP et ajoutez trois choses : l'authentification, la gestion des erreurs et un hébergeur.

• Authentification. Les serveurs MCP distants doivent utiliser OAuth 2.1 selon la spécification d'autorisation MCP. Pour des outils internes, une vérification de token bearer sur l'endpoint HTTP est le minimum pragmatique. Ne livrez jamais un serveur d'outils public et non authentifié, car un outil qui exécute du SQL ou frappe des API internes est une surface d'attaque active.
• Gestion des erreurs. Encadrez le corps des outils avec try/except (ou try/catch) et renvoyez un message d'erreur typé au lieu de lever une exception. Le modèle gère « la requête a échoué, voici pourquoi » bien mieux qu'une connexion coupée.
• Hébergement. Toute plateforme qui exécute un processus Node ou Python de longue durée convient : un petit VPS, Fly.io, Railway ou un conteneur sur votre propre infrastructure. Gardez le processus chaud, car les démarrages à froid ajoutent de la latence au premier appel d'outil.
• Concurrence et coût. Si vos outils appellent un LLM ou une API payante en aval, placez un gateway devant. Notre tour d'horizon des outils de gateway LLM couvre le rate-limiting et le fallback, et les outils de context engineering aident à empêcher les sorties d'outils d'encombrer la fenêtre de contexte du modèle.

Pour Python, changez l'appel run en mcp.run(transport="streamable-http") ; pour TypeScript, remplacez StdioServerTransport par le StreamableHTTPServerTransport du SDK. Les définitions d'outils ne changent pas du tout. C'est tout l'intérêt de l'abstraction de transport.

Ce que nous avons appris en livrant des serveurs MCP en production

Chez Techsy, nous avons construit des serveurs MCP pour un usage interne, et certaines leçons n'apparaissent qu'une fois que du vrai trafic les frappe. Voici ce que nous avons mesuré et où nous nous sommes fait piéger.

Le premier serveur que nous avons livré était un outil de requête Postgres en lecture seule, construit avec FastMCP 2.x sur le SDK Python mcp 1.x, réécrit ensuite en @modelcontextprotocol/sdk 1.x pour comparer. Sur un stack de 2026 (Node 20, Python 3.11), les appels d'outils locaux en stdio ajoutaient environ 8 à 12 ms de surcharge de transport par appel. Une fois ce même serveur passé en Streamable HTTP sur un VPS, le coût par appel est monté à 40 à 70 ms, presque entièrement de l'aller-retour réseau plutôt que du coût de protocole. Le démarrage à froid de FastMCP était d'environ 300 ms pour le processus, raison pour laquelle nous gardons le processus de production chaud.

Le piège qui nous a coûté environ deux heures : un outil qui renvoyait un dict Python brut s'affichait bien dans l'Inspector mais revenait tronqué dans Claude Desktop. Envelopper la valeur de retour en chaîne de texte typée a réglé ça instantanément. C'est pourquoi ce tutoriel renvoie partout des chaînes et des blocs de texte content plutôt que des objets imbriqués. L'autre habitude qui a payé immédiatement était de faire passer chaque serveur par npx @modelcontextprotocol/inspector avant de toucher à une config client, ce qui a révélé un schéma d'entrée mal formé dans la réécriture TypeScript qui aurait sinon échoué silencieusement dans Cursor.

Si vous choisissez quels outils intégrer dans des serveurs en premier lieu, notre liste des meilleurs serveurs MCP en 2026 est une bonne banque d'idées.

Comment Techsy aborde le développement MCP

Chez Techsy, nous construisons des serveurs MCP dans le cadre des systèmes d'agents IA que nous livrons pour des clients, en connectant les agents à des bases de données internes, des CRM et des API via une couche d'outils typée. Notre approche est de commencer étroit (un outil bien testé sur stdio), de le valider dans l'Inspector, puis de le promouvoir en service HTTP authentifié seulement quand plus d'un agent en a besoin. Nous associons des serveurs personnalisés au Claude Agent SDK quand la logique d'agent devient complexe.

Voici la version honnête : la plupart des équipes sur-construisent leur premier serveur. Vous avez rarement besoin de HTTP, d'OAuth et d'une douzaine d'outils dès le premier jour. Si vous voulez un deuxième regard sur une intégration MCP, obtenez une consultation gratuite et nous vous dirons s'il s'agit d'un travail stdio à un seul outil ou de quelque chose qui nécessite vraiment de l'infrastructure.

Foire aux questions

Dois-je créer mon serveur MCP en Python ou en TypeScript ?

Utilisez le langage que votre équipe utilise déjà. Python avec FastMCP est la voie la plus courte vers un premier serveur fonctionnel, car un décorateur transforme une fonction en outil. TypeScript avec le SDK officiel est un peu plus verbeux mais offre d'excellents types et se déploie proprement sur des hôtes Node. Les deux produisent des serveurs au comportement identique pour le client.

Ai-je besoin d'un framework comme FastMCP pour créer un serveur MCP ?

Non, mais ça aide. FastMCP est livré dans le SDK Python mcp officiel et supprime l'essentiel du boilerplate de protocole. Vous pouvez utiliser l'API Server de plus bas niveau pour un contrôle fin, mais pour presque tous les serveurs, FastMCP (Python) ou McpServer (TypeScript) est le bon outil et bien moins de code.

Comment déboguer un serveur MCP qui ne fonctionne pas ?

Faites-le d'abord passer par le MCP Inspector : npx @modelcontextprotocol/inspector suivi de votre commande de lancement. L'Inspector liste vos outils et vous laisse les appeler directement, vous pouvez donc confirmer que le serveur fonctionne avant de blâmer le client. Si l'Inspector est correct mais pas le client, vérifiez que votre config utilise des chemins absolus et que vous avez redémarré le client.

FastMCP fait-il officiellement partie de MCP ?

Oui. FastMCP est fourni avec le SDK Python officiel du Model Context Protocol comme interface serveur de haut niveau. Le décorateur @mcp.tool() que vous utilisez est la manière recommandée de créer des serveurs Python, pas un add-on tiers.

Quelle est la différence entre un serveur MCP local et distant ?

Un serveur local tourne sur votre machine en stdio, lancé par le client comme sous-processus, idéal pour les outils personnels et le développement. Un serveur distant tourne comme service web en Streamable HTTP et est joignable par plusieurs clients, ce qui requiert l'authentification OAuth 2.1. Construisez d'abord en local, passez en distant seulement pour partager.

Dans quels langages puis-je créer un serveur MCP ?

Le Model Context Protocol dispose de SDK officiels pour Python, TypeScript, Java, Kotlin et C#, avec des SDK communautaires dans d'autres langages. Comme MCP est un protocole filaire, tout langage capable de lire et écrire du JSON-RPC sur stdio ou HTTP peut implémenter un serveur, mais les SDK officiels vous épargnent ce travail.

Un serveur MCP fonctionne-t-il avec ChatGPT et Gemini, ou seulement Claude ?

MCP est un standard ouvert adopté dans tout l'écosystème de l'IA agentique, y compris ChatGPT, Gemini, Cursor et VS Code Copilot. Un seul serveur que vous construisez fonctionne avec tout client compatible. Vous n'écrivez pas d'intégration séparée par modèle, ce qui est tout l'intérêt du protocole.

Combien de temps faut-il pour créer un serveur MCP fonctionnel ?

Un premier serveur avec un ou deux outils sur stdio prend environ 15 minutes une fois votre runtime installé. Nous avons mesuré 14 minutes pour un débutant sur Node 20 et moins de 5 minutes pour une construction répétée. L'authentification, le transport HTTP et l'hébergement en production sont ce qui prend du vrai temps, pas le serveur lui-même.