Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Configure un serveur MCP local (STDIO)

Oppitunti 4 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Ton premier serveur MCP local
  2. Écriture du serveur
  3. Configuration du client STDIO
  4. Tester avant d’intégrer
  5. Keskeiset asiat

Mis à jour le 2 novembre 2026 — MCP Python SDK v2. Ce cours suit désormais la version 2 du SDK mcp (2.3.0 au 2 octobre 2026) : MCPServer remplace FastMCP, les paramètres de transport migrent vers run() ou streamable_http_app(), et toute application exposée sous un nom d’hôte réel doit le déclarer (transport_security). C’est aussi la version requise par le SDK Mistral : l’extra mistralai[agents] exige mcp>=2.2.0,<3.0. Sources : Quoi de neuf dans la v2 · Guide de migration · Déploiement et mise à l’échelle.

Ton premier serveur MCP local

Le mode STDIO est le point de départ naturel pour développer et tester un serveur MCP : tout s’exécute sur ta machine, sans déploiement, sans URL publique ni gestion de certificats. Tu modifies un fichier, tu redémarres, tu observes. Dans cette leçon, tu vas écrire un serveur MCP local en Python, puis le connecter à un client.

Côté prérequis, il te 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 séparé par projet t’évite de casser un serveur fonctionnel 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]"

Écriture du serveur

Avec MCPServer, la classe de haut niveau du SDK officiel (anciennement FastMCP), un serveur local tient en quelques lignes. Tu instancies une application en lui donnant un nom descriptif, puis tu décores tes 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("Local Demo Server")

@app.tool()
def greet(name: str) -> str:
    """Greets a person by name.

    Args:
        name: The first name of the person to greet

    Returns:
        A personalized greeting message
    """
    return f"Hello {name}! Welcome to the world of MCP."

@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
    """Performs a simple mathematical calculation.

    Args:
        operation: The operation to perform (add, sub, mul, div)
        a: First number
        b: Second number

    Returns:
        The result of the calculation
    """
    ops = {
        "add": a + b,
        "sub": a - b,
        "mul": a * b,
        "div": a / b if b != 0 else "Error: division by zero"
    }
    result = ops.get(operation, "Unknown operation")
    return f"{a} {operation} {b} = {result}"

Ce fichier expose deux outils. Note le rôle des docstrings : elles ne documentent pas seulement ton code pour un collègue ; elles deviennent littéralement la description que le modèle lit pour décider d’appeler calculate plutôt que greet. Une docstring bâclée ici entraîne des appels erratiques plus tard.

Configuration du client STDIO

Côté client, tu ne te connectes pas à une adresse ; tu expliques 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 ton 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 des détails.

command

C’est la commande système qui lance le processus serveur : "python" pour un serveur Python, "node" pour un serveur JavaScript, ou le chemin direct vers un binaire si ton 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 passés à cette commande. Pour un script Python, c’est au minimum le chemin du fichier, mais rien ne t’empêche d’y passer les options de ton 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 tu lui passes une clé API, une URL de base de données ou un flag de débogage.

import os

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

Le comportement de ce paramètre surprend souvent. Avec env=None, le serveur hérite de tout l’environnement du processus parent ; avec un dictionnaire, il ne voit strictement que les variables listées. Si tu fournis un dictionnaire sans y déverser os.environ, ne sois pas surpris si ton serveur ne trouve plus son PATH ou ta clé API : le comportement est parfaitement logique, simplement radical.

Tester avant d’intégrer

Avant de brancher ton serveur sur un agent, teste-le en isolation avec l’MCP Inspector. Le raisonnement est simple : si un appel échoue une fois le serveur connecté à un modèle, tu ne sauras pas si le problème vient de ton code ou de la décision du modèle. L’Inspector lève cette ambiguïté.

npx @modelcontextprotocol/inspector python serveur_local.py

La commande ouvre une interface web locale où tu peux lister les outils exposés, inspecter la description et les paramètres que le modèle recevra, déclencher un appel manuel avec des arguments de ton choix, et vérifier le format exact de la valeur de retour. Prends l’habitude de l’utiliser systématiquement : ce sont cinq minutes qui font gagner une heure.

Enfin, voici une organisation de fichiers qui vieillit bien, avec le serveur, le client, les dépendances, les secrets gardés hors du dépôt, et des tests unitaires pour tes outils :

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ées)
└── tests/
    └── test_tools.py    # Tests unitaires des outils

Keskeiset asiat

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