Exemplu complet: Server la distanță cu autentificare
Pe această pagină
Actualizare 2 noiembrie 2026 — Le Chat devine Vibe. Începând cu 28 mai 2026, Le Chat a fost rebotezat Vibe (rămâne disponibil la chat.mistral.ai): un singur agent pentru muncă și cod, care păstrează conversațiile, setările și abonamentele dumneavoastră. Experiența legacy Le Chat rămâne accesibilă în modul Chat; în modul Work, agenții sunt acum competențe (invocate cu
@), memoriile servesc drept bază de cunoștințe, iar căutarea avansată este competența Deep Research. Planurile se numesc acum Mistral Free, Pro, Team și Enterprise. Această lecție folosește denumirea Vibe; unele meniuri descrise aici își pot fi schimbat numele sau locația. Adendum 3 noiembrie: rezultatelerun_asyncse citesc dinresult.output_as_text; SDK-ulmistralaiversiunea 3.7.0 nu are un atributoutput.
Actualizare 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului
mcp(2.3.0 la data de 2 octombrie 2026):MCPServerînlocuieșteFastMCP, setările de transport se mută înrun()saustreamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ulmistralai[agents]necesitămcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale.
Scenariu: Un server MCP de gestionare a sarcinilor
Lecțiile anterioare au acoperit elementele individuale: transportul HTTP, middleware-ul și autentificarea pe bază de token. Acum le veți asambla într-un proiect complet funcțional. Serverul expune patru instrumente de gestionare a sarcinilor—creare, listare, finalizare, ștergere—iar clientul se conectează la distanță, prezentând un token bearer la fiecare cerere. Același server va rula apoi din Vibe fără nicio linie de cod suplimentară: acesta este întregul avantaj al unui server la distanță față de un server STDIO.
Serverul: task_server.py
Trei elemente coexistă în acest singur fișier. FastAPI gestionează transportul HTTP și middleware-ul de autentificare, MCPServer gestionează protocolul MCP și instrumentele, iar un dicționar Python servește drept bază de date. Ordinea fișierelor contează: declarați mai întâi serverul MCP și instrumentele sale, apoi creați aplicația FastAPI cu lifespan care pornește managerul de sesiune și montați serverul la final. Rețineți că middleware-ul protejează calea /tasks, care este exact locul unde este montat serverul MCP: aceste două valori trebuie să corespundă, altfel veți ajunge fie cu o ușă deschisă, fie cu o cale blocată.
# task_server.py
"""Remote MCP server with token authentication."""
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
# --- Configuration ---
API_TOKEN = "mcp-secret-token-2026"
# --- In-memory database ---
tasks_db: dict[str, dict] = {}
# --- MCP Server ---
mcp = MCPServer("Task Manager")
@mcp.tool()
def create_task(title: str, description: str = "", priority: str = "medium") -> str:
"""Creates a new task in the manager.
Args:
title: Task title (required, max 200 characters)
description: Detailed description (optional)
priority: Priority level: low, medium, high (default: medium)
Returns:
JSON with the ID and details of the created task
"""
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:
"""Lists tasks with optional filters.
Args:
status: Filter by status: all, open, completed (default: all)
priority: Filter by priority: all, low, medium, high (default: all)
Returns:
JSON with the list of tasks and the total count
"""
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:
"""Marks a task as completed.
Args:
task_id: The unique identifier of the task
Returns:
Confirmation of the update or an error message
"""
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:
"""Deletes a task from the manager.
Args:
task_id: The unique identifier of the task to delete
Returns:
Confirmation of deletion or an error message
"""
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)
# --- Mount the MCP server in FastAPI ---
# streamable_http_app() produces the ASGI app for the MCP server.
# Its session manager must be started by the FastAPI lifespan,
# otherwise the server responds but every tool call fails.
@asynccontextmanager
async def lifespan(app: FastAPI):
async with mcp.session_manager.run():
yield
api = FastAPI(title="Task Manager MCP", lifespan=lifespan)
# --- Authentication Middleware ---
@api.middleware("http")
async def auth_middleware(request: Request, call_next):
"""Verifies the token for all /tasks routes."""
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)
# Public hostname (ngrok, production domain) declared to the MCP server
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)
Două detalii de implementare merită atenția dumneavoastră. În create_task, titlul este trunchiat la 200 de caractere, iar prioritatea implicită este medium dacă valoarea primită nu se află în lista permisă: modelul propune uneori valori plauzibile, dar în afara contractului, iar instrumentul trebuie să rămână robust fără a eșua. În complete_task și delete_task, un ID necunoscut nu aruncă o excepție, ci returnează un mesaj de eroare JSON—modelul poate citi acest lucru, își poate înțelege greșeala și poate reformula, în timp ce o blocare ar preveni acest lucru.
Lansarea și expunerea serverului
# Într-un prim terminal, deschideți tunelul ngrok
ngrok http 8000
# Public URL: https://xyz789.ngrok-free.app
# Într-un al doilea terminal, lansați serverul declarând acest nume de gazdă
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
Endpoint-ul MCP se află apoi la https://xyz789.ngrok-free.app/tasks/mcp. Observați compoziția acestei adrese: URL-ul public furnizat de ngrok, urmat de calea de montare /tasks, apoi sufixul /mcp adăugat de SDK. Confuzia legată de această concatenare este cauza principală a eșecurilor de conectare.
Clientul: client_tasks.py
În partea clientului, nimic nu se schimbă față de un server local, cu excepția tipului de client MCP și a adăugării antetului de autentificare. Agentul primește însă instrucțiuni care îi descriu rolul în limbaj natural—acest lucru îl încurajează să confirme fiecare acțiune, în loc să înlănțuie apeluri în tăcere.
# client_tasks.py
"""MCP client for the remote task server with authentication."""
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"])
# Create the agent with adapted instructions
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."
),
)
# Configure the remote MCP client with authentication
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)
# Conversation with the manager
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())
Secvența de mesaje este deliberată: înlănțuie două creări, o citire, o actualizare și o recitire. Acesta este scenariul minim pentru a verifica faptul că starea supraviețuiește de la un apel la altul și că modelul poate recupera ID-ul unei sarcini create mai devreme în conversație. Dacă a patra instrucțiune eșuează, problema dumneavoastră rareori se află la server: de obicei provine din faptul că răspunsul list_tasks nu face ID-urile suficient de vizibile.
Testare în Mistral Vibe
Același endpoint poate fi adăugat direct ca un conector personalizat, oferindu-vă o interfață de testare fără a scrie un client. Aceasta este, de asemenea, cea mai bună modalitate de a valida docstring-urile dumneavoastră: Vibe le afișează ca atare în timpul descoperirii, astfel încât vedeți imediat ce va avea modelul în față pentru a decide ce instrument să apeleze.
- Accesați fila Connectors din Vibe
- Faceți clic pe Add Custom Connector
- Introduceți Name ca
Task Manager, URL cahttps://xyz789.ngrok-free.app/tasks/mcp, apoi alegeți Auth: Token și lipițimcp-secret-token-2026 - Faceți clic pe Connect
Vibe descoperă apoi automat cele patru instrumente, iar dumneavoastră puteți conversa în limbaj natural cu propriul server.
Organizarea proiectului și pașii următori
task-mcp-project/
├── task_server.py # MCP server + FastAPI + auth
├── client_tasks.py # Python client with agent
├── requirements.txt # fastapi, uvicorn, mcp>=2.2,<3, mistralai[agents]
└── .env # MISTRAL_API_KEY, API_TOKEN
Acest schelet funcționează pentru prototipare, dar două lucruri îl descalifică pentru producție. Token-ul în text clar din codul sursă trebuie mutat în .env, iar URL-ul ngrok se schimbă la fiecare repornire, stricând toți conectorii configurați. ngrok rămâne instrumentul ideal pentru validarea unei idei în câteva minute; găzduirea permanentă, cu opțiunile sale Docker, cloud și Hugging Face Spaces, este subiectul lecției 12.
Puncte cheie
- Un server la distanță combină FastAPI (HTTP) +
MCPServer(MCP) + middleware (auth), cu numele de gazdă public declarat întransport_security - Autentificarea pe bază de token este gestionată prin antetul
Authorization: Bearer ... - Clientul
MCPClientStreamableHTTPacceptă anteturi personalizate pentru autentificare - Același server este utilizabil atât din Python SDK, cât și din Mistral Vibe
- ngrok permite prototiparea rapidă înainte de implementarea în producție