Ejemplo completo: servidor remoto con autenticación
En esta página
Actualización 2 de noviembre de 2026 — Le Chat pasa a llamarse Vibe. Desde el 28 de mayo de 2026, Le Chat se ha renombrado como Vibe (sigue en chat.mistral.ai): un único agente para trabajo y código que conserva tus conversaciones, configuraciones y suscripciones. La experiencia heredada de Le Chat sigue accesible en el modo Chat; en el modo Work, los agentes son ahora habilidades (se invocan con
@), las memorias actúan como base de conocimientos y la búsqueda profunda es la habilidad Deep Research. Los planes se llaman ahora Mistral Free, Pro, Team y Enterprise. Esta lección usa el nombre Vibe; algunos menús descritos aquí pueden haber cambiado de nombre o ubicación. Addendum 3 de noviembre: los resultados derun_asyncse leen desderesult.output_as_text; el SDKmistralai3.7.0 no tiene un atributooutput.
Actualización 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):MCPServerreemplaza aFastMCP, la configuración del transporte se mueve arun()ostreamable_http_app(), y una aplicación expuesta bajo un nombre de host real debe declarar dicho nombre de host (transport_security). Esta es también la versión requerida por el SDK de Mistral: el extramistralai[agents]requieremcp>=2.2.0,<3.0. Fuentes: Novedades en v2 · Guía de migración · Despliegue y escalado.
Escenario: un servidor MCP de gestión de tareas
Las lecciones anteriores han cubierto las piezas individuales: transporte HTTP, middleware y autenticación por token. Ahora las ensamblarás en un proyecto totalmente funcional. El servidor expone cuatro herramientas de gestión de tareas —crear, listar, completar y eliminar— y el cliente se conecta de forma remota, presentando un token de portador en cada petición. Este mismo servidor se ejecutará luego desde Vibe sin una sola línea de código adicional: esa es toda la ventaja de un servidor remoto frente a un servidor STDIO.
El servidor: task_server.py
Tres elementos coexisten en este único archivo. FastAPI gestiona el transporte HTTP y el middleware de autenticación, MCPServer gestiona el protocolo MCP y las herramientas, y un diccionario de Python sirve como base de datos. El orden del archivo importa: declara primero el servidor MCP y sus herramientas, crea después la aplicación FastAPI con el lifespan que inicia el gestor de sesiones y monta el servidor al final. Ten en cuenta que el middleware protege la ruta /tasks, que es exactamente donde se monta el servidor MCP: estos dos valores deben coincidir, o acabarás con una puerta abierta o con un camino bloqueado.
# task_server.py
"""Servidor MCP remoto con autenticación por token."""
import json
import os
import uuid
from contextlib import asynccontextmanager
from datetime import datetime
from fastapi import FastAPI, Request, HTTPException
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings
# --- Configuración ---
API_TOKEN = "mcp-secret-token-2026"
# --- Base de datos en memoria ---
tasks_db: dict[str, dict] = {}
# --- Servidor MCP ---
mcp = MCPServer("Task Manager")
@mcp.tool()
def create_task(title: str, description: str = "", priority: str = "medium") -> str:
"""Crea una nueva tarea en el gestor.
Args:
title: Título de la tarea (obligatorio, máx. 200 caracteres)
description: Descripción detallada (opcional)
priority: Nivel de prioridad: low, medium, high (predeterminado: medium)
Returns:
JSON con el ID y los detalles de la tarea creada
"""
task_id = str(uuid.uuid4())[:8]
task = {
"id": task_id,
"title": title[:200],
"description": description,
"priority": priority if priority in ("low", "medium", "high") else "medium",
"status": "open",
"created_at": datetime.now().isoformat(),
}
tasks_db[task_id] = task
return json.dumps({"success": True, "task": task}, ensure_ascii=False)
@mcp.tool()
def list_tasks(status: str = "all", priority: str = "all") -> str:
"""Lista las tareas con filtros opcionales.
Args:
status: Filtrar por estado: all, open, completed (predeterminado: all)
priority: Filtrar por prioridad: all, low, medium, high (predeterminado: all)
Returns:
JSON con la lista de tareas y el recuento total
"""
filtered = list(tasks_db.values())
if status != "all":
filtered = [t for t in filtered if t["status"] == status]
if priority != "all":
filtered = [t for t in filtered if t["priority"] == priority]
return json.dumps({
"total": len(filtered),
"tasks": filtered,
}, ensure_ascii=False)
@mcp.tool()
def complete_task(task_id: str) -> str:
"""Marca una tarea como completada.
Args:
task_id: El identificador único de la tarea
Returns:
Confirmación de la actualización o un mensaje de error
"""
if task_id not in tasks_db:
return json.dumps({"error": f"Task {task_id} not found"})
tasks_db[task_id]["status"] = "completed"
tasks_db[task_id]["completed_at"] = datetime.now().isoformat()
return json.dumps({"success": True, "task": tasks_db[task_id]}, ensure_ascii=False)
@mcp.tool()
def delete_task(task_id: str) -> str:
"""Elimina una tarea del gestor.
Args:
task_id: El identificador único de la tarea a eliminar
Returns:
Confirmación de la eliminación o un mensaje de error
"""
if task_id not in tasks_db:
return json.dumps({"error": f"Task {task_id} not found"})
deleted = tasks_db.pop(task_id)
return json.dumps({"success": True, "deleted_task": deleted["title"]}, ensure_ascii=False)
# --- Montar el servidor MCP en FastAPI ---
# streamable_http_app() produce la aplicación ASGI para el servidor MCP.
# Su gestor de sesiones debe iniciarse mediante el lifespan de FastAPI,
# de lo contrario el servidor responde pero cada llamada a herramienta falla.
@asynccontextmanager
async def lifespan(app: FastAPI):
async with mcp.session_manager.run():
yield
api = FastAPI(title="Task Manager MCP", lifespan=lifespan)
# --- Middleware de autenticación ---
@api.middleware("http")
async def auth_middleware(request: Request, call_next):
"""Verifica el token para todas las rutas /tasks."""
if request.url.path.startswith("/tasks"):
auth = request.headers.get("Authorization", "")
if auth != f"Bearer {API_TOKEN}":
raise HTTPException(status_code=401, detail="Invalid token")
return await call_next(request)
# Nombre de host público (ngrok, dominio de producción) declarado al servidor MCP
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
securite = TransportSecuritySettings(
allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*", "localhost:*", "127.0.0.1:*"]
)
api.mount("/tasks", mcp.streamable_http_app(transport_security=securite))
if __name__ == "__main__":
import uvicorn
uvicorn.run(api, host="0.0.0.0", port=8000)
Dos detalles de implementación merecen tu atención. En create_task, el título se trunca a 200 caracteres y la prioridad toma por defecto medium si el valor recibido no está en la lista permitida: el modelo a veces propone valores plausibles pero fuera de contrato, y la herramienta debe mantenerse robusta sin fallar. En complete_task y delete_task, un ID desconocido no lanza una excepción, sino que devuelve un mensaje de error en JSON; el modelo puede leerlo, entender su error y reformular, mientras que un fallo abrupto impediría hacerlo.
Lanzar y exponer el servidor
# En un primer terminal, abre el túnel de ngrok
ngrok http 8000
# URL pública: https://xyz789.ngrok-free.app
# En un segundo terminal, lanza el servidor declarando este nombre de host
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
El punto final de MCP queda entonces en https://xyz789.ngrok-free.app/tasks/mcp. Observa la composición de esta dirección: la URL pública proporcionada por ngrok, seguida de la ruta de montaje /tasks y luego el sufijo /mcp añadido por el SDK. La confusión sobre esta concatenación es la causa principal de fallos de conexión.
El cliente: client_tasks.py
En el lado del cliente, nada cambia respecto a un servidor local salvo el tipo de cliente MCP y la adición de la cabecera de autenticación. El agente, en cambio, recibe instrucciones que describen su rol en lenguaje natural; esto le anima a confirmar cada acción en lugar de encadenar llamadas en silencio.
# client_tasks.py
"""Cliente MCP para el servidor remoto de tareas con autenticación."""
import asyncio
import os
from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.mcp.streamable_http import (
MCPClientStreamableHTTP,
StreamableHTTPServerParams,
)
API_TOKEN = "mcp-secret-token-2026"
SERVER_URL = "https://xyz789.ngrok-free.app/tasks/mcp"
async def main():
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Crear el agente con instrucciones adaptadas
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="task-manager",
instructions=(
"You are an intelligent task manager. "
"Use the available tools to create, list, and manage "
"the user's tasks. Respond in English. "
"Confirm every action performed."
),
)
# Configurar el cliente MCP remoto con autenticación
mcp_client = MCPClientStreamableHTTP(
params=StreamableHTTPServerParams(
url=SERVER_URL,
headers={"Authorization": f"Bearer {API_TOKEN}"},
timeout=30,
)
)
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)
# Conversación con el gestor
conversations = [
"Create a high priority task: Prepare the MCP presentation",
"Create a medium priority task: Review the documentation",
"List all ongoing tasks",
"Mark the first task as completed",
"Show me the remaining tasks",
]
for msg in conversations:
print(f"\n> {msg}")
result = await client.beta.conversations.run_async(
run_ctx=run_ctx,
inputs=msg,
)
print(f"Agent: {result.output_as_text}")
asyncio.run(main())
La secuencia de mensajes es deliberada: encadena dos creaciones, una lectura, una actualización y una relectura. Este es el escenario mínimo para verificar que el estado sobrevive de una llamada a la siguiente y que el modelo puede recuperar el ID de una tarea creada antes en la conversación. Si la cuarta instrucción falla, tu problema rara vez está en el servidor: suele deberse a que la respuesta de list_tasks no hace los IDs lo bastante visibles.
Prueba en Mistral Vibe
El mismo punto final puede añadirse directamente como conector personalizado, lo que te da una interfaz de prueba sin escribir un cliente. Esta es también la mejor forma de validar tus docstrings: Vibe las muestra tal cual durante el descubrimiento, así que ves de inmediato qué tendrá el modelo delante para decidir qué herramienta llamar.
- Ve a la pestaña Connectors en Vibe
- Haz clic en Add Custom Connector
- Introduce Name como
Task Manager, URL comohttps://xyz789.ngrok-free.app/tasks/mcpy elige Auth: Token; pegamcp-secret-token-2026 - Haz clic en Connect
Vibe descubre automáticamente las cuatro herramientas y puedes conversar en lenguaje natural con tu propio servidor.
Organización del proyecto y siguientes pasos
task-mcp-project/
├── task_server.py # Servidor MCP + FastAPI + autenticación
├── client_tasks.py # Cliente Python con agente
├── requirements.txt # fastapi, uvicorn, mcp>=2.2,<3, mistralai[agents]
└── .env # MISTRAL_API_KEY, API_TOKEN
Este esqueleto sirve para prototipar, pero dos cosas lo descalifican para producción. El token en texto plano en el código fuente debe moverse a .env, y la URL de ngrok cambia en cada reinicio, rompiendo todos los conectores configurados. ngrok sigue siendo la herramienta ideal para validar una idea en minutos; el alojamiento permanente, con sus opciones de Docker, nube y Hugging Face Spaces, es el tema de la lección 12.
Puntos clave
- Un servidor remoto combina FastAPI (HTTP) +
MCPServer(MCP) + middleware (autenticación), con el nombre de host público declarado entransport_security - La autenticación por token se gestiona mediante la cabecera
Authorization: Bearer ... - El cliente
MCPClientStreamableHTTPacepta cabeceras personalizadas para autenticación - El mismo servidor es usable tanto desde el SDK de Python como desde Mistral Vibe
- ngrok permite un prototipado rápido antes del despliegue en producción