Exemple complet : serveur local avec agent
Na ovoj stranici
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) :MCPServerremplaceFastMCP, les paramètres de transport migrent versrun()oustreamable_http_app(), et une application exposée sous un nom d’hôte réel doit déclarer ce nom d’hôte (transport_security). C’est aussi la version requise par le SDK Mistral : l’extramistralai[agents]exigemcp>=2.2.0,<3.0. Sources : Quoi de neuf dans la v2 · Guide de migration · Déploiement et mise à l’échelle. Addendum du 3 novembre : lis le résultat d’unrun_asyncdepuisresult.output_as_text(le SDKmistralai3.7.0 n’a pas d’attributoutput), et en mode streaming, le dernier événement est unRunResult, identifié viaisinstance, comme dans l’exemple officiel du SDK.
Assemblage des pièces
Les leçons précédentes ont présenté les briques séparément : le serveur et ses outils, le client et son RunContext. Tu vas maintenant les assembler dans un projet fonctionnel : un serveur MCP local fournissant des informations météorologiques, piloté par un agent Mistral capable de répondre à des questions en langage naturel. Lis le code, mais porte une attention particulière aux décisions de chaque partie : le serveur décide de ce qui est possible, l’agent décide de ce qui est pertinent.
Le serveur : weather_server.py
Ce serveur comporte trois outils. Le premier renvoie la météo d’une ville, le second compare deux villes, et le troisième liste le contenu de la base de données. Ce dernier n’est pas décoratif : il offre au modèle un moyen de découvrir le périmètre disponible au lieu de deviner des noms de villes.
# weather_server.py
"""Local MCP server providing weather tools."""
from mcp.server.mcpserver import MCPServer
import json
app = MCPServer("Weather Service")
# Simulated database
WEATHER_DATA = {
"paris": {"temp": 18.5, "condition": "Cloudy", "humidity": 72},
"lyon": {"temp": 22.0, "condition": "Sunny", "humidity": 45},
"marseille": {"temp": 25.3, "condition": "Sunny", "humidity": 38},
"lille": {"temp": 14.2, "condition": "Rainy", "humidity": 88},
"bordeaux": {"temp": 20.1, "condition": "Partly cloudy", "humidity": 55},
}
@app.tool()
def get_weather(city: str) -> str:
"""Retrieves current weather for a French city.
Args:
city: City name in lowercase (paris, lyon, marseille, etc.)
Returns:
JSON with temperature, condition, and humidity.
Returns an error if the city is unknown.
"""
city_lower = city.lower().strip()
if city_lower in WEATHER_DATA:
data = WEATHER_DATA[city_lower]
return json.dumps({
"city": city.capitalize(),
"temperature_celsius": data["temp"],
"condition": data["condition"],
"humidity_percent": data["humidity"],
}, ensure_ascii=False)
return json.dumps({"error": f"City {city} not found. Available cities: {', '.join(WEATHER_DATA.keys())}"})
@app.tool()
def compare_weather(city_a: str, city_b: str) -> str:
"""Compares weather between two French cities.
Args:
city_a: First city (lowercase)
city_b: Second city (lowercase)
Returns:
Comparison of temperatures and conditions for both cities
"""
a = WEATHER_DATA.get(city_a.lower().strip())
b = WEATHER_DATA.get(city_b.lower().strip())
if not a:
return f"Unknown city: {city_a}"
if not b:
return f"Unknown city: {city_b}"
diff = a["temp"] - b["temp"]
warmer = city_a if diff > 0 else city_b
return json.dumps({
"city_a": {"name": city_a.capitalize(), **a},
"city_b": {"name": city_b.capitalize(), **b},
"temperature_difference": abs(diff),
"warmer_city": warmer.capitalize(),
}, ensure_ascii=False)
@app.tool()
def list_cities() -> str:
"""Lists all cities available in the weather database.
Returns:
List of cities with their current temperature
"""
cities = [
{"city": k.capitalize(), "temp": v["temp"], "condition": v["condition"]}
for k, v in WEATHER_DATA.items()
]
return json.dumps(cities, ensure_ascii=False)
Deux détails de conception méritent ton attention. Les outils normalisent l’entrée avec .lower().strip() car le modèle pourrait écrire „Paris“ ou „paris“ selon la formulation de l’utilisateur. Et lorsqu’une ville est manquante, get_weather ne lève pas d’exception : il renvoie un JSON d’erreur énumérant les villes connues, transformant ainsi l’échec en information exploitable par le modèle.
Le client : main.py
Le client effectue quatre actions dans l’ordre : instancier Mistral, créer l’agent, décrire comment lancer le serveur, puis ouvrir le RunContext pour enchaîner les conversations.
# main.py
"""MCP client with Mistral agent for weather queries."""
import asyncio
import os
from pathlib import Path
from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from mcp import StdioServerParameters
from pydantic import BaseModel
# Configuration
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
SERVER_PATH = Path(__file__).parent / "weather_server.py"
# Structured output format (optional)
class WeatherResponse(BaseModel):
summary: str
details: dict | None = None
async def main():
# 1. Initialize Mistral client
client = Mistral(api_key=MISTRAL_API_KEY)
# 2. Create the agent
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="weather-assistant",
instructions=(
"You are a weather assistant for France. "
"Use available tools to answer questions. "
"Always respond in French with metric units."
),
)
# 3. Configure local MCP server
server_params = StdioServerParameters(
command="python",
args=[str(SERVER_PATH)],
env=None,
)
mcp_client = MCPClientSTDIO(stdio_params=server_params)
# 4. Open context and register MCP client
async with RunContext(
agent_id=agent.id,
continue_on_fn_error=True,
) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
# 5. Launch conversations
questions = [
"What's the weather like in Paris?",
"Compare the weather between Marseille and Lille.",
"Which city is the warmest right now?",
]
for question in questions:
print(f"\n{'='*60}")
print(f"Question: {question}")
print(f"{'='*60}")
result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs=question,
)
print(f"Response: {result.output_as_text}")
# 6. Automatic cleanup upon exiting context manager
print("\nAgent and MCP server closed cleanly.")
if __name__ == "__main__":
asyncio.run(main())
Remarque le chemin du serveur : Path(__file__).parent / "weather_server.py" localise le fichier relativement au script plutôt qu’au répertoire courant. C’est le seul moyen de garantir que le lancement fonctionne, peu importe l’endroit depuis lequel tu exécutes python main.py.
Exécution du projet
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Tu ne lances qu’un seul processus. Le client crée l’agent Mistral, le RunContext lance weather_server.py en tant que processus STDIO, découvre les trois outils — get_weather, compare_weather et list_cities — puis, question par question, laisse le modèle choisir lesquels appeler avant d’intégrer les résultats dans sa réponse. La troisième question de l’exemple est la plus intéressante à observer : pour savoir quelle ville est la plus chaude, le modèle n’a d’autre choix que de passer par list_cities, même si aucun mot dans la question ne le suggère.
Observer la construction de la réponse
Attendre la réponse complète convient pour un script ; face à un utilisateur, le mode streaming offre une bien meilleure expérience.
from mistralai.extra.run.result import RunResult
async with RunContext(agent_id=agent.id) as run_ctx:
await run_ctx.register_mcp_client(mcp_client=mcp_client)
events = await client.beta.conversations.run_stream_async(
run_ctx=run_ctx,
inputs="What's the weather like in Lyon?",
)
async for event in events:
if isinstance(event, RunResult):
# Last event: complete run result
print(event.output_as_text)
else:
# Intermediate events (tool calls, etc.)
print(f"[Event] {event}")
Le flux d’événements ne sert pas seulement à l’affichage : c’est aussi ton meilleur outil de débogage, car il expose en temps réel les appels d’outils et les arguments choisis par le modèle.
Lorsqu’un outil échoue
Grâce à continue_on_fn_error=True, une demande hors périmètre ne casse rien. Si l’utilisateur demande la météo de Tokyo, get_weather renvoie son JSON d’erreur, le modèle le lit et rebondit en proposant les villes réellement disponibles.
# If the user requests a non-existent city:
# → get_weather returns {"error": "City tokyo not found..."}
# → The model reads the error and reformulates its response
# → "I'm sorry, Tokyo is not in my database. Here are the available cities..."
Au final, le projet tient en quatre fichiers, dont deux seulement contiennent de la logique :
weather-mcp-project/
├── weather_server.py # MCP server (3 tools)
├── main.py # Client with Mistral agent
├── requirements.txt # mcp>=2.2,<3, mistralai[agents], pydantic
└── .env # MISTRAL_API_KEY=...
Ključne točke
- Un projet MCP complet = serveur (outils) + client (agent + RunContext)
- Le serveur définit les outils avec
MCPServeret les décorateurs@app.tool() - Le client crée l’agent, ouvre le RunContext et lance les conversations
- Le mode streaming permet un affichage progressif
continue_on_fn_error=Truegère les erreurs d’outils avec souplesse- Tout le code est asynchrone — utilise
asyncio.run()comme point d’entrée