Créer son premier serveur MCP : tutoriel TypeScript et Python

Pour créer un serveur MCP en TypeScript, il faut aujourd'hui quatre choses : Node.js 20 ou plus récent, le paquet officiel @modelcontextprotocol/server (version 2.2.0 au 30 septembre 2026), un outil déclaré avec registerTool, et une ligne dans la configuration de Claude Desktop¹. Le code ci-dessous a été compilé et testé avec le MCP Inspector le 30 septembre 2026. Si vous voulez d'abord comprendre ce qu'est un serveur, lisez notre définition du serveur MCP.

Faut-il vraiment créer un serveur, ou en existe-t-il déjà un ?

Commencez par chercher. Le registre officiel (registry.modelcontextprotocol.io) recense les serveurs publiés, et de nombreux éditeurs proposent le leur : Google Analytics, GitHub, Notion, HubSpot, Semrush, Slack². Pour WordPress, le projet officiel est le MCP Adapter, qui transforme les « abilities » de WordPress en outils MCP³. Le dépôt modelcontextprotocol/servers, lui, ne contient plus que quelques serveurs de référence pédagogiques ; il n'y a pas de serveur WordPress à y cloner². Notre sélection de serveurs MCP pour le marketing indique lesquels sont maintenus par l'éditeur.

Créez le vôtre quand l'outil n'a pas de serveur officiel (logiciel métier, API interne) ou quand vous voulez limiter précisément ce que l'IA peut faire. Des standards ouverts peuvent aussi utiliser MCP, comme l'Universal Commerce Protocol (UCP) pour l'achat par agents d'IA.

Étape 1 : préparer le projet

mkdir mon-serveur-mcp && cd mon-serveur-mcp
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript
mkdir src && touch src/index.ts

Dans package.json, ajoutez le type module et un script de compilation :

{
  "type": "module",
  "scripts": {
    "build": "tsc"
  }
}

Puis créez tsconfig.json :

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "types": ["node"],
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Étape 2 : déclarer un outil

Un outil = un nom, une description (c'est elle que le modèle lit pour décider de l'appeler), un schéma de paramètres et une fonction. Exemple : lire la fiche d'un client dans une API interne (adresse fictive à remplacer).

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const server = new McpServer({ name: "mon-serveur-mcp", version: "1.0.0" });

server.registerTool(
  "get_client",
  {
    description: "Retourne la fiche d'un client à partir de son identifiant",
    inputSchema: z.object({
      id: z.string().describe("Identifiant du client"),
    }),
  },
  async ({ id }) => {
    const res = await fetch(`https://api.exemple.be/clients/${encodeURIComponent(id)}`, {
      headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
    });
    if (!res.ok) {
      return { content: [{ type: "text", text: `Erreur API : ${res.status}` }], isError: true };
    }
    return { content: [{ type: "text", text: await res.text() }] };
  },
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Serveur MCP démarré sur stdio");
}

main().catch((error) => {
  console.error("Erreur fatale :", error);
  process.exit(1);
});

Trois points qui font échouer la plupart des premiers essais :

• Jamais de console.log() dans un serveur stdio : il écrit sur la sortie standard et corrompt les messages JSON-RPC. Utilisez console.error()¹.
• Le jeton passe par une variable d'environnement, jamais en dur dans le code.
• Renvoyez isError: true quand l'API échoue : le modèle comprend que l'appel a raté au lieu d'inventer une réponse.

Étape 3 : tester sans Claude

Compilez, puis interrogez le serveur avec le MCP Inspector, l'outil de test officiel :

npm run build
npx @modelcontextprotocol/inspector@latest --cli node build/index.js --method tools/list

La commande doit renvoyer votre outil get_client et son schéma. Sans --cli, l'Inspector ouvre une interface web qui permet d'appeler l'outil à la main. La version 2 de l'Inspector demande Node.js 22.19 ou plus récent.

Étape 4 : brancher le serveur dans Claude Desktop

Dans Claude Desktop, ouvrez le menu Claude de la barre système, puis Settings, onglet Developer, bouton Edit Config. Le fichier se trouve dans ~/Library/Application Support/Claude/claude_desktop_config.json sur macOS et dans %APPDATA%\Claude\claude_desktop_config.json sur Windows⁴. Ajoutez :

{
  "mcpServers": {
    "mon-serveur-mcp": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mon-serveur-mcp/build/index.js"],
      "env": {
        "API_TOKEN": "votre-jeton-de-test"
      }
    }
  }
}

Le chemin doit être absolu. Quittez complètement Claude Desktop et relancez-le. Pour vérifier, cliquez sur le bouton « + » en bas à gauche de la zone de saisie, puis Connectors et Manage connectors : votre serveur et son outil doivent apparaître. Claude demande votre accord avant chaque appel d'outil⁴.

Si rien n'apparaît : vérifiez la syntaxe JSON, le chemin, et lisez les journaux dans ~/Library/Logs/Claude/mcp*.log (macOS) ou %APPDATA%\Claude\logs (Windows)⁴.

Et en Python ?

Le SDK Python officiel (paquet mcp, version 2.2.0, Python 3.10 ou plus récent) s'utilise avec un décorateur ; le type des paramètres et la docstring servent de schéma et de description¹⁵.

uv init mon-serveur && cd mon-serveur
uv venv && source .venv/bin/activate
uv add "mcp[cli]"

# serveur.py
from mcp.server import MCPServer

mcp = MCPServer("mon-serveur")

@mcp.tool()
async def get_client(id: str) -> str:
    """Retourne la fiche d'un client."""
    return f"client {id}"

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

Que faire avant de passer en production ?

• Donner au jeton de l'API cible les droits minimaux (lecture seule si l'outil ne fait que lire).
• Pour un serveur partagé en équipe, passer au transport Streamable HTTP avec authentification ; l'ancien transport HTTP+SSE est déprécié⁶.
• Relire notre guide sur les risques réels de MCP : injection de consignes, jetons, actions irréversibles.

Si vous préférez confier le développement d'un serveur connecté à vos outils métier, c'est un projet type de notre agence IA.