Przykład kompletny: Serwer lokalny z agentem
Na tej stronie
Zaktualizowano 2 listopada 2026 — MCP Python SDK v2. Ten kurs opiera się na wersji 2 SDK
mcp(2.3.0 na dzień 2 października 2026):MCPServerzastępujeFastMCP, ustawienia transportu przeniesiono dorun()lubstreamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi ją zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatekmistralai[agents]wymagamcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie. Dodatkowa uwaga z 3 listopada: wynik wywołaniarun_asyncodczytujesz zresult.output_as_text(SDKmistralaiw wersji 3.7.0 nie ma atrybutuoutput), a w trybie strumieniowania ostatnim zdarzeniem jestRunResult, co identyfikujesz za pomocąisinstance, zgodnie z oficjalnym przykładem w SDK.
Składanie elementów w całość
Poprzednie lekcje przedstawiły poszczególne bloki konstrukcyjne osobno: serwer i jego narzędzia, klienta oraz jego kontekst wykonania (RunContext). Teraz połączysz je w działający projekt — lokalny serwer MCP udostępniający informacje o pogodzie, sterowany przez agenta Mistral zdolnego odpowiadać na pytania w języku naturalnym. Przeczytaj kod, ale zwróć szczególną uwagę na decyzje podejmowane przez każdą część: serwer decyduje, co jest możliwe, natomiast agent decyduje, co jest istotne.
Serwer: weather_server.py
Ten serwer składa się z trzech narzędzi. Pierwsze zwraca pogodę dla danego miasta, drugie porównuje dwa miasta, a trzecie wymienia zawartość bazy danych. To ostatnie nie jest ozdobnikiem: daje modelowi możliwość odkrycia dostępnego zakresu danych, zamiast zgadywania nazw miast.
# 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)
Dwa szczegóły projektowe zasługują na uwagę. Narzędzia normalizują dane wejściowe za pomocą .lower().strip(), ponieważ model może zapisać „Paris“ lub „paris“ w zależności od sformułowania użytkownika. Gdy miasto nie istnieje, get_weather nie zgłasza wyjątku: zwraca JSON z błędem, który wymienia znane miasta, zamieniając niepowodzenie w informację użyteczną dla modelu.
Klient: main.py
Klient wykonuje cztery czynności po kolei: inicjalizuje Mistral, tworzy agenta, opisuje sposób uruchomienia serwera, a następnie otwiera RunContext, aby łączyć rozmowy w sekwencje.
# 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())
Zwróć uwagę na ścieżkę do serwera: Path(__file__).parent / "weather_server.py" lokalizuje plik względem skryptu, a nie względem bieżącego katalogu. To jedyny sposób, aby zagwarantować poprawne uruchomienie niezależnie od tego, z jakiego katalogu wywołasz python main.py.
Uruchamianie projektu
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Uruchamiasz tylko jeden proces. Klient tworzy agenta Mistral, RunContext uruchamia weather_server.py jako proces STDIO, wykrywa trzy narzędzia — get_weather, compare_weather i list_cities — a następnie, pytanie po pytaniu, pozwala modelowi wybrać, których z nich użyć, zanim zintegruje wyniki ze swoją odpowiedzią. Trzecie pytanie w przykładzie jest najbardziej interesujące do obserwacji: aby wiedzieć, które miasto jest najcieplejsze, model nie ma wyboru i musi skorzystać z list_cities, mimo że żadne słowo w pytaniu tego nie sugeruje.
Obserwowanie budowania odpowiedzi
Oczekiwanie na pełną odpowiedź sprawdza się w skryptach; w interakcji z użytkownikiem tryb strumieniowania zapewnia znacznie lepsze doświadczenie.
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}")
Strumień zdarzeń służy nie tylko do wyświetlania: to także najlepsze narzędzie do debugowania, ponieważ ujawnia w czasie rzeczywistym wywołania narzędzi i argumenty wybrane przez model.
Gdy narzędzie zawiedzie
Dzięki continue_on_fn_error=True żądanie wykraczające poza zakres nie powoduje awarii. Jeśli użytkownik zapyta o pogodę w Tokio, get_weather zwróci swój JSON z błędem, model go odczyta i zareaguje, proponując faktycznie dostępne miasta.
# 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..."
Podsumowując, projekt mieści się w czterech plikach, z których tylko dwa zawierają logikę:
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=...
Kluczowe wnioski
- Kompletny projekt MCP = serwer (narzędzia) + klient (agent + RunContext)
- Serwer definiuje narzędzia za pomocą
MCPServeri dekoratorów@app.tool() - Klient tworzy agenta, otwiera RunContext i uruchamia rozmowy
- Tryb strumieniowania umożliwia progresywne wyświetlanie
continue_on_fn_error=Truezapewnia eleganckie obsługiwanie błędów narzędzi- Cały kod jest asynchroniczny — użyj
asyncio.run()jako punktu wejścia