Configurer un Serveur MCP Local (STDIO) — MCP pour Développeurs — Serveurs et Intégrations

Mise à jour du 2 novembre 2026 — SDK Python MCP v2. Ce cours suit désormais la version 2 du SDK mcp (2.3.0 au 2 octobre 2026) : MCPServer remplace FastMCP, les réglages de transport passent à run() ou à streamable_http_app(), et une application exposée sous un vrai nom d’hôte doit déclarer ce nom (transport_security). C’est aussi la version qu’exige le SDK Mistral : l’extra mistralai[agents] demande mcp>=2.2.0,<3.0. Sources : What’s new in v2 · Guide de migration · Deploy & scale.

Votre premier serveur MCP local

Le mode STDIO est le point de départ naturel pour développer et tester un serveur MCP : tout tourne sur votre machine, sans déploiement, sans URL publique et sans certificat à gérer. Vous éditez un fichier, vous relancez, vous observez. Dans cette leçon, vous allez écrire un serveur MCP local en Python, puis le connecter à un client.

Côté prérequis, il vous faut Python 3.10 ou supérieur, un pip à jour, et de préférence un environnement virtuel dédié — ce dernier point n’est pas cosmétique : les paquets MCP évoluent vite, et un venv par projet vous évite de casser un serveur qui fonctionnait en installant une dépendance pour un autre.

# Créer un environnement virtuel
python -m venv mcp-env
source mcp-env/bin/activate  # Linux/Mac
# mcp-env\Scripts\activate   # Windows

# SDK MCP officiel (v2) et SDK Mistral avec son extra agents
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"

Écrire le serveur

Avec MCPServer, la classe de haut niveau du SDK officiel (anciennement FastMCP), un serveur local tient en quelques lignes. Vous instanciez une application en lui donnant un nom descriptif, puis vous décorez vos fonctions Python avec @app.tool() pour les exposer.

# serveur_local.py
from mcp.server.mcpserver import MCPServer

# Initialiser le serveur avec un nom descriptif
app = MCPServer("Serveur Démo Local")

@app.tool()
def greet(name: str) -> str:
    """Salue une personne par son nom.

    Args:
        name: Le prénom de la personne à saluer

    Returns:
        Un message de salutation personnalisé
    """
    return f"Bonjour {name} ! Bienvenue dans le monde MCP."

@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
    """Effectue un calcul mathématique simple.

    Args:
        operation: L'opération à effectuer (add, sub, mul, div)
        a: Premier nombre
        b: Second nombre

    Returns:
        Le résultat du calcul
    """
    ops = {
        "add": a + b,
        "sub": a - b,
        "mul": a * b,
        "div": a / b if b != 0 else "Erreur: division par zéro"
    }
    result = ops.get(operation, "Opération inconnue")
    return f"{a} {operation} {b} = {result}"

Ce fichier expose deux tools. Observez le rôle des docstrings : elles ne servent pas seulement à documenter votre code pour un collègue, elles deviennent littéralement la description que le modèle lira pour décider d’appeler calculate plutôt que greet. Une docstring bâclée ici se paie en appels erratiques plus tard.

Configurer le client STDIO

Côté client, il ne s’agit pas de se connecter à une adresse mais d’expliquer comment démarrer le serveur. C’est le rôle de StdioServerParameters.

# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path

# Chemin vers votre serveur
path_to_server = Path("serveur_local.py")

# Configuration du serveur STDIO
server_params = StdioServerParameters(
    command="python",           # La commande pour lancer le serveur
    args=[str(path_to_server)], # Les arguments (le fichier Python)
    env=None,                   # Variables d'environnement (optionnel)
)

# Créer le client MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)

Trois paramètres méritent d’être détaillés.

`command`

C’est la commande système qui lance le processus serveur : "python" pour un serveur Python, "node" pour un serveur JavaScript, ou directement le chemin d’un binaire si votre serveur est compilé.

# Python
command="python"

# Node.js
command="node"

# Un exécutable compilé
command="./mon_serveur_mcp"

`args`

C’est la liste des arguments transmis à cette commande. Pour un script Python, il s’agit au minimum du chemin du fichier, mais rien ne vous empêche d’y passer les options de votre serveur.

# Script simple
args=["serveur_local.py"]

# Avec des arguments supplémentaires
args=["serveur_local.py", "--port", "8080", "--verbose"]

`env`

C’est le dictionnaire des variables d’environnement transmises au processus serveur : le canal par lequel vous lui passez une clé d’API, une URL de base de données ou un drapeau de debug.

import os

server_params = StdioServerParameters(
    command="python",
    args=["serveur_local.py"],
    env={
        **os.environ,  # Hériter de l'environnement courant
        "API_KEY": "votre_cle_api",
        "DATABASE_URL": "postgresql://...",
        "DEBUG": "true",
    },
)

Le comportement de ce paramètre surprend souvent. Avec env=None, le serveur hérite de la totalité de l’environnement du processus parent ; avec un dictionnaire, il ne verra strictement que les variables listées. Si vous fournissez un dictionnaire sans y déverser os.environ, ne vous étonnez pas que votre serveur ne trouve plus son PATH ni votre clé d’API : le comportement est parfaitement logique, simplement radical.

Tester avant d’intégrer

Avant de brancher votre serveur sur un agent, éprouvez-le seul avec le MCP Inspector. Le raisonnement est simple : si un appel échoue une fois le serveur connecté à un modèle, vous ne saurez pas si le problème vient de votre code ou de la décision du modèle. L’Inspector supprime cette ambiguïté.

npx @modelcontextprotocol/inspector python serveur_local.py

La commande ouvre une interface web locale depuis laquelle vous listez les tools exposés, inspectez la description et les paramètres que le modèle recevra, déclenchez un appel manuel avec les arguments de votre choix et vérifiez le format exact du retour. Prenez l’habitude d’y passer systématiquement : c’est cinq minutes qui en économisent une heure.

Pour finir, une organisation de fichiers qui vieillit bien, avec le serveur, le client, les dépendances, les secrets hors du dépôt et les tests unitaires de vos tools :

mon-projet-mcp/
├── serveur_local.py     # Le serveur MCP
├── client_stdio.py      # Le script client
├── requirements.txt     # Dépendances
├── .env                 # Variables d'environnement (jamais commité)
└── tests/
    └── test_tools.py    # Tests unitaires des tools

Points clés à retenir

Un serveur STDIO se lance comme un processus local
StdioServerParameters configure la commande, les arguments et les variables d’environnement
Les docstrings de vos tools servent de description pour le modèle
L’MCP Inspector (npx @modelcontextprotocol/inspector) est indispensable pour tester
env=None hérite de tout l’environnement ; un dict explicite limite les variables