Ir al contenido principal
Español— Elegir un idioma
Menú

Ejemplo completo: servidor local con agente

Lección 6 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Ensamblaje de las piezas
  2. El servidor: weather_server.py
  3. El cliente: main.py
  4. Ejecución del proyecto
  5. Observación de la construcción de la respuesta
  6. Cuando una herramienta falla
  7. Puntos clave

Actualizado el 2 de noviembre de 2026 — MCP Python SDK v2. Este curso sigue ahora la versión 2 del SDK mcp (2.3.0 a fecha de 2 de octubre de 2026): MCPServer sustituye a FastMCP, la configuración del transporte se traslada a run() o streamable_http_app(), y una aplicación expuesta bajo un nombre de host real debe declarar dicho host (transport_security). Esta es también la versión que requiere el SDK de Mistral: el extra mistralai[agents] necesita mcp>=2.2.0,<3.0. Fuentes: Novedades en la v2 · Guía de migración · Despliegue y escalado. Addendum del 3 de noviembre: lee el resultado de un run_async desde result.output_as_text (el SDK mistralai 3.7.0 no tiene el atributo output), y en modo de streaming el último evento es un RunResult, identificado con isinstance, tal como muestra el ejemplo oficial del SDK.

Ensamblaje de las piezas

Las lecciones anteriores han presentado los bloques de construcción por separado: el servidor y sus herramientas, el cliente y su RunContext. Ahora los ensamblarás en un proyecto funcional: un servidor MCP local que proporciona información meteorológica, impulsado por un agente de Mistral capaz de responder preguntas en lenguaje natural. Lee el código, pero presta especial atención a qué decide cada parte: el servidor decide qué es posible; el agente decide qué es relevante.

El servidor: weather_server.py

Este servidor consta de tres herramientas. La primera devuelve el tiempo de una ciudad, la segunda compara dos ciudades y la tercera lista el contenido de la base de datos. Esta última no es decorativa: ofrece al modelo un mecanismo para descubrir el alcance disponible en lugar de adivinar nombres de ciudades.

# weather_server.py
"""Servidor MCP local que proporciona herramientas meteorológicas."""

from mcp.server.mcpserver import MCPServer
import json

app = MCPServer("Weather Service")

# Base de datos simulada
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:
    """Recupera el tiempo actual de una ciudad francesa.

    Args:
        city: Nombre de la ciudad en minúsculas (paris, lyon, marseille, etc.)

    Returns:
        JSON con temperatura, estado y humedad.
        Devuelve un error si la ciudad es desconocida.
    """
    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:
    """Compara el tiempo entre dos ciudades francesas.

    Args:
        city_a: Primera ciudad (minúsculas)
        city_b: Segunda ciudad (minúsculas)

    Returns:
        Comparación de temperaturas y estados para ambas ciudades
    """
    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:
    """Lista todas las ciudades disponibles en la base de datos meteorológica.

    Returns:
        Lista de ciudades con su temperatura actual
    """
    cities = [
        {"city": k.capitalize(), "temp": v["temp"], "condition": v["condition"]}
        for k, v in WEATHER_DATA.items()
    ]
    return json.dumps(cities, ensure_ascii=False)

Dos detalles de diseño merecen atención. Las herramientas normalizan la entrada con .lower().strip() porque el modelo podría escribir «Paris» o «paris» dependiendo de la formulación del usuario. Además, cuando falta una ciudad, get_weather no lanza una excepción: devuelve un JSON de error que enumera las ciudades conocidas, convirtiendo el fallo en información útil para el modelo.

El cliente: main.py

El cliente realiza cuatro acciones en orden: instanciar Mistral, crear el agente, describir cómo lanzar el servidor y, finalmente, abrir el RunContext para encadenar conversaciones.

# main.py
"""Cliente MCP con agente Mistral para consultas meteorológicas."""

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

# Configuración
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
SERVER_PATH = Path(__file__).parent / "weather_server.py"

# Formato de salida estructurada (opcional)
class WeatherResponse(BaseModel):
    summary: str
    details: dict | None = None

async def main():
    # 1. Inicializar el cliente de Mistral
    client = Mistral(api_key=MISTRAL_API_KEY)

    # 2. Crear el agente
    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. Configurar el servidor MCP local
    server_params = StdioServerParameters(
        command="python",
        args=[str(SERVER_PATH)],
        env=None,
    )
    mcp_client = MCPClientSTDIO(stdio_params=server_params)

    # 4. Abrir contexto y registrar el cliente MCP
    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. Lanzar conversaciones
        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. Limpieza automática al salir del gestor de contexto
    print("\nAgent and MCP server closed cleanly.")

if __name__ == "__main__":
    asyncio.run(main())

Observa la ruta del servidor: Path(__file__).parent / "weather_server.py" localiza el archivo respecto al script y no al directorio actual. Esta es la única forma de garantizar que el lanzamiento funcione sin importar desde dónde ejecutes python main.py.

Ejecución del proyecto

# Establecer la clave de API
export MISTRAL_API_KEY="your_mistral_api_key"

# Lanzar el cliente (iniciará el servidor automáticamente)
python main.py

Solo inicias un proceso. El cliente crea el agente de Mistral, el RunContext lanza weather_server.py como un proceso STDIO, descubre las tres herramientas —get_weather, compare_weather y list_cities— y, pregunta a pregunta, permite que el modelo elija cuáles invocar antes de integrar los resultados en su respuesta. La tercera pregunta del ejemplo es la más interesante de observar: para saber qué ciudad tiene más calor, el modelo no tiene más remedio que pasar por list_cities, aunque ninguna palabra de la pregunta lo sugiera.

Observación de la construcción de la respuesta

Esperar a la respuesta completa funciona para un script; de cara a un usuario, el modo streaming ofrece una experiencia mucho mejor.

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):
            # Último evento: resultado completo de la ejecución
            print(event.output_as_text)
        else:
            # Eventos intermedios (llamadas a herramientas, etc.)
            print(f"[Event] {event}")

El flujo de eventos no sirve solo para mostrar información: es también tu mejor herramienta de depuración, ya que expone en tiempo real las llamadas a herramientas y los argumentos elegidos por el modelo.

Cuando una herramienta falla

Gracias a continue_on_fn_error=True, una petición fuera de alcance no rompe nada. Si el usuario pide el tiempo de Tokio, get_weather devuelve su JSON de error, el modelo lo lee y responde proponiendo las ciudades realmente disponibles.

# Si el usuario solicita una ciudad inexistente:
# → get_weather devuelve {"error": "City tokyo not found..."}
# → El modelo lee el error y reformula su respuesta
# → "I'm sorry, Tokyo is not in my database. Here are the available cities..."

En definitiva, el proyecto cabe en cuatro archivos, de los cuales solo dos contienen lógica:

weather-mcp-project/
├── weather_server.py    # Servidor MCP (3 herramientas)
├── main.py              # Cliente con agente Mistral
├── requirements.txt     # mcp>=2.2,<3, mistralai[agents], pydantic
└── .env                 # MISTRAL_API_KEY=...

Puntos clave

  • Un proyecto MCP completo = servidor (herramientas) + cliente (agente + RunContext)
  • El servidor define herramientas con MCPServer y los decoradores @app.tool()
  • El cliente crea el agente, abre el RunContext y lanza conversaciones
  • El modo streaming permite una visualización progresiva
  • continue_on_fn_error=True gestiona los errores de las herramientas con elegancia
  • Todo el código es asíncrono: usa asyncio.run() como punto de entrada