La plupart des guides sur le Model Context Protocol (MCP) vous expliquent comment installer un serveur écrit par quelqu’un d’autre. Celui-ci vous montre comment créer votre propre serveur MCP en Python : un petit serveur doté de deux outils, que n’importe quelle application d’IA compatible MCP peut appeler. Vous allez le construire, le tester sans aucune application d’IA, l’inspecter avec MCP Inspector, l’outil officiel, puis le connecter à un éditeur ou à un assistant.
À retenir
- Le SDK Python officiel de MCP, en version 2.x, a renommé la classe serveur en MCPServer : de nombreux tutoriels plus anciens ne fonctionnent donc plus tels quels.
- Il suffit de décorer une fonction avec @mcp.tool() pour en faire un outil ; son nom, sa description et son schéma d’entrée sont tirés de votre code.
- Testez le serveur en mémoire avec la classe Client du SDK, puis via stdio avec MCP Inspector, l’outil officiel.
- Connectez-le à Cursor, VS Code ou Claude Desktop en fournissant à l’application une commande de lancement uv avec un chemin absolu.
Au 15 novembre 2026, le SDK Python officiel en est à la version 2.3.0 (publiée le 2 octobre 2026) et MCP Inspector à la version 2.15.0 (publiée le 12 novembre 2026). Le SDK 2.x a renommé la classe serveur principale, si bien que de nombreux tutoriels plus anciens ne fonctionnent plus tels quels. Les commandes de projet, de test et d’Inspector ci-dessous ont été exécutées avec ces versions.
Qu’est-ce qu’un serveur MCP ?
MCP est un standard open source qui permet de connecter des applications d’IA à des systèmes externes. Trois termes tirés de la documentation du SDK suffisent pour suivre :
- L’hôte (host) est l’application d’IA avec laquelle vous dialoguez, par exemple un assistant conversationnel ou un éditeur de code.
- Le client se trouve à l’intérieur de l’hôte et parle MCP.
- Le serveur est ce que vous construisez. Il peut proposer des outils (des fonctions que le modèle appelle), des ressources (des données que l’application charge) et des prompts (des modèles que l’utilisateur choisit).
Ce guide se concentre sur les outils. Les deux que vous allez écrire, un compteur de mots et un calculateur de dates, font un travail exact, que du code accomplit mieux qu’une estimation du modèle.
Ce dont vous avez besoin
- uv, le gestionnaire de projets Python utilisé dans le tutoriel MCP officiel. Il télécharge Python pour vous s’il manque une version adaptée. Le SDK exige Python 3.10 ou plus récent.
- Node.js, uniquement pour l’Inspector à l’étape 4. Inspector 2.15.0 requiert Node
^22.23.4 || ^24.22.1 || >=26.12.1. - Une application compatible MCP pour l’étape 5 (facultatif).
Installer uv sur macOS ou Linux :
curl -LsSf https://astral.sh/uv/install.sh | sh
Sous Windows, dans PowerShell :
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Redémarrez ensuite votre terminal pour que la commande uv soit trouvée.
En chiffres
2.3.0version du SDK Python utilisée
2.15.0version de MCP Inspector utilisée
3.10version minimale de Python
Étape 1 : créer le projet
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"
--bare crée uniquement un fichier pyproject.toml, ce qui suffit pour ce projet. L’extra cli ajoute l’outil en ligne de commande mcp. Vérifiez l’installation :
uv run mcp version
Résultat attendu :
MCP version 2.3.0
Étape 2 : écrire le serveur
Créez un fichier nommé server.py dans le dossier du projet :
from datetime import date
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("Handy Tools")
@mcp.tool()
def count_words(text: str) -> int:
"""Count the words in a piece of text."""
return len(text.split())
@mcp.tool()
def days_between(start: str, end: str) -> int:
"""Count the days from one date to another. Dates use YYYY-MM-DD format."""
try:
first = date.fromisoformat(start)
second = date.fromisoformat(end)
except ValueError:
raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
return (second - first).days
if __name__ == "__main__":
mcp.run()
Le rôle de chaque partie :
MCPServer("Handy Tools")crée le serveur. Dans le SDK 2.x, on l’importe depuismcp.server.@mcp.tool()transforme une fonction en outil. Le SDK tire le nom de l’outil du nom de la fonction, sa description de la docstring et son schéma d’entrée des annotations de type. Vous n’écrivez pas une ligne de JSON.ToolErrorrenvoie au modèle un message lisible, afin qu’il puisse corriger ses arguments et réessayer.mcp.run()sans argument démarre le serveur via stdio : l’hôte lance votre fichier comme sous-processus et communique avec lui par stdin et stdout.

Étape 3 : le tester depuis Python
Le SDK inclut une classe Client capable de se connecter à votre objet serveur en mémoire, sans sous-processus, sans port et sans IA. Créez check.py à côté de server.py :
import asyncio
from mcp import Client
from server import mcp
async def main() -> None:
async with Client(mcp) as client:
tools = await client.list_tools()
print([tool.name for tool in tools.tools])
result = await client.call_tool("count_words", {"text": "the quick brown fox"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
print(result.is_error, result.content[0].text)
asyncio.run(main())
Lancez-le :
uv run check.py
Résultat attendu :
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).
Vous verrez aussi une ligne de journal INFO concernant l’appel en échec : c’est le serveur qui journalise la ToolError. Remarquez que la date invalide n’a pas levé d’exception côté client : un appel d’outil en échec revient sous la forme d’un résultat normal, avec is_error à True.
Le saviez-vous ?
Un appel d’outil en échec ne lève pas d’exception côté client. Il revient sous la forme d’un résultat normal, avec is_error à True, et contient le message de la ToolError.
Étape 4 : l’inspecter avec MCP Inspector
MCP Inspector est l’outil de test du projet MCP lui-même. Son mode CLI lance votre serveur comme le ferait un véritable hôte et affiche ce qui revient. Depuis le dossier du projet :
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list
Au premier lancement, l’outil demande l’autorisation de télécharger le paquet. Vous devriez ensuite voir du JSON listant count_words et days_between, chacun avec le schéma d’entrée que le SDK a généré à partir de vos annotations de type.
Appelez maintenant un outil :
npx @modelcontextprotocol/inspector --cli uv run server.py \
--method tools/call --tool-name days_between \
--tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'
Résultat attendu :
{
"content": [
{
"type": "text",
"text": "47"
}
],
"structuredContent": {
"result": 47
},
"isError": false
}
Le SDK peut aussi démarrer l’interface web de l’Inspector :
uv run mcp dev server.py
Elle affiche une adresse locale comme http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=... et l’ouvre dans votre navigateur. Sur l’écran Servers, activez l’interrupteur de connexion à côté de votre serveur, ouvrez Tools (outils), choisissez count_words, saisissez un texte et cliquez sur Execute Tool (exécuter l’outil). Appuyez sur Ctrl+C dans le terminal quand vous avez terminé.
Étape 5 : le connecter à une application d’IA
Connecter le serveur à un hôte revient à indiquer à celui-ci la commande qui démarre votre serveur. Pour ce projet, cette commande est :
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py
Lancez pwd dans le dossier du projet pour obtenir le vrai chemin. Essayez d’abord la commande vous-même. Rien ne s’affiche et elle ne rend pas la main, et c’est normal : le serveur attend qu’un hôte lui parle. Appuyez sur Ctrl+C pour l’arrêter.
De nombreuses applications acceptent le même bloc JSON pour cette commande :
{
"mcpServers": {
"handy-tools": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
}
}
}
Son emplacement dépend de l’application :
- Cursor : enregistrez-le sous
.cursor/mcp.jsondans un projet, ou sous~/.cursor/mcp.jsonpour l’utiliser partout, selon la documentation MCP de Cursor. Cette documentation mentionne aussi un champ"type": "stdio"pour les serveurs locaux, même si ses propres exemples l’omettent. - VS Code : lancez MCP: Add Server depuis la palette de commandes, choisissez Command (stdio) et saisissez la commande de lancement, selon la documentation de VS Code.
- Claude Desktop : lancez
uv run mcp install server.py, qui écrit l’entrée pour vous. C’est le seul hôte que le SDK configure automatiquement.
Redémarrez l’application, puis posez une question du genre :
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?
La réponse devrait être 47. Gardez à l’esprit que les outils s’exécutent sur votre ordinateur avec les droits de votre compte : n’exposez que des actions que vous acceptez de voir déclenchées par un modèle. Pour un exemple de serveur plus complet et prêt à l’emploi, consultez notre guide sur Chrome DevTools MCP.

Erreurs courantes et solutions
ModuleNotFoundError: No module named 'mcp.server.fastmcp': le code a été écrit pour le SDK 1.x. En 2.x, la classe s’appelleMCPServeret s’importe avecfrom mcp.server import MCPServer. Mettez l’import à jour, ou épinglezmcp<2pour continuer à faire tourner l’ancien code.TypeError: The @tool decorator was used incorrectly: vous avez écrit@mcp.toolsans parenthèses. Utilisez@mcp.tool().- L’application n’affiche pas votre serveur : la cause habituelle est un chemin relatif. Utilisez le chemin absolu du projet et, si l’application ne trouve pas
uv, remplacezuvpar le chemin complet donné parwhich uv(macOS et Linux) ouwhere uv(Windows). Quittez complètement l’application et rouvrez-la après avoir modifié sa configuration. - La connexion tombe ou la liste d’outils est vide : via stdio, stdout transporte le protocole lui-même. Un
print()égaré peut le corrompre. Utilisez le moduleloggingde Python, qui écrit sur stderr. npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated, ou un appel d’outil échoue avecField required: votre Node.js est trop ancien pour Inspector 2.x. Lors d’un test sous Node 20,npxa discrètement installé l’ancienne version 0.15.0, qui ignore--tool-args-json. Vérifieznode --versionet passez à une version prise en charge.npx not founden lançantmcp dev: l’Inspector est une application Node.js. Installez d’abord Node.js.Error executing tool <name>sans message : l’outil a planté sur une exception que vous n’aviez pas prévue. La trace d’appels se trouve dans le journal du serveur, pas dans le résultat.
Le saviez-vous ?
Via stdio, stdout transporte le protocole lui-même : un print() égaré dans votre serveur peut donc corrompre la connexion. Le module logging de Python, lui, écrit sur stderr.
En résumé
Un serveur MCP fonctionnel, c’est un fichier Python avec quelques fonctions décorées. Écrivez l’outil, vérifiez-le en mémoire avec Client(mcp), confirmez-le via stdio avec l’Inspector, puis donnez la commande de lancement à n’importe quel hôte. À partir de là, vous pouvez ajouter des ressources et des prompts, ou servir le même code en HTTP avec mcp.run(transport="streamable-http"). Si votre agent a davantage besoin d’instructions écrites que de nouvelles fonctions, notre guide sur les agent skills dans Claude Code couvre cet aspect.
Questions fréquentes
Quelle est la différence entre un hôte, un client et un serveur MCP ?
L’hôte est l’application d’IA avec laquelle vous dialoguez, par exemple un assistant conversationnel ou un éditeur de code. Le client se trouve à l’intérieur de l’hôte et parle MCP. Le serveur est ce que vous construisez, et il peut proposer des outils, des ressources et des prompts.
Pourquoi ai-je l’erreur No module named mcp.server.fastmcp ?
Ce code a été écrit pour le SDK 1.x. En 2.x, la classe s’appelle MCPServer et s’importe avec from mcp.server import MCPServer. Mettez l’import à jour, ou épinglez mcp<2 pour continuer à faire tourner l’ancien code.
Peut-on tester un serveur MCP sans application d’IA ?
Oui. La classe Client du SDK se connecte à votre objet serveur en mémoire, sans sous-processus, sans port et sans IA. Le mode CLI de MCP Inspector lance ensuite le serveur via stdio, comme le ferait un véritable hôte.
Quelle version de Node.js faut-il pour MCP Inspector ?
Inspector 2.15.0 requiert Node ^22.23.4, ^24.22.1 ou >=26.12.1. Avec un Node plus ancien, npx risque d’installer discrètement l’ancienne version 0.15.0, qui ignore –tool-args-json.
Petit quiz
Dans le SDK 2.x, quelle classe crée un serveur MCP ?
- FastMCP
- ToolError
- MCPServer
Le SDK 2.x a renommé la classe serveur principale en MCPServer, importée depuis mcp.server.
Que peut provoquer un print() égaré dans un serveur MCP en stdio ?
- La corruption du flux du protocole
- Rien, la sortie est ignorée
- Le redémarrage du serveur
Via stdio, stdout transporte le protocole lui-même : toute sortie supplémentaire peut donc le corrompre.
Où le SDK trouve-t-il le schéma d’entrée d’un outil ?
- Dans un fichier JSON que vous écrivez
- Dans les annotations de type de la fonction
- Dans le fichier de configuration de l’hôte
Le SDK lit le schéma d’entrée dans les annotations de type : vous n’écrivez pas de JSON.
Sources
Liens vérifiés pour la dernière fois le 15 novembre 2026.
- Build an MCP server (official tutorial)
- What is the Model Context Protocol?
- MCP Python SDK README, v2.3.0
- Python SDK: First steps
- Python SDK: Connect to a real host
- Python SDK: Testing
- Python SDK: Running your server
- Python SDK: Handling errors
- Python SDK: Troubleshooting
- mcp on PyPI
- MCP Inspector README, 2.15.0
- Inspector: smoke-testing an MCP server from the shell
- Installing uv
- uv: creating projects
- Cursor: Model Context Protocol
- VS Code: add and manage MCP servers





Écrire une réponse