Configurer un Serveur MCP Local (STDIO)

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

# Installer les packages MCP
pip install mcp fastmcp
pip install mistralai  # Pour le client Mistral

Écrire le serveur

Avec 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.fastmcp import FastMCP

# Initialiser le serveur avec un nom descriptif
app = FastMCP("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