Pavyzdys išsamiai: nuotolinis serveris su autentifikavimu
Šiame puslapyje
Atnaujinimas 2026 m. lapkričio 2 d. — „Le Chat“ dabar vadinasi „Vibe“. Nuo 2026 m. gegužės 28 d. „Le Chat“ buvo pervadintas į Vibe (vis tiek adresu chat.mistral.ai): tai vienas agentas darbui ir kodui, perkeliantis jūsų pokalbius, nustatymus ir prenumeratas. Senoji „Le Chat“ patirtis vis dar pasiekiama režimu Chat; režimu Work agentai dabar yra įgūdžiai (kviečiami naudojant
@), atmintys veikia kaip žinių bazė, o giluminė paieška yra „Deep Research“ įgūdis. Planai dabar vadinami „Mistral Free“, „Pro“, „Team“ ir „Enterprise“. Šioje pamokoje naudojamas pavadinimas „Vibe“; kai kurie čia aprašyti meniu punktai galėjo pakeisti pavadinimus arba vietą. Priedas lapkričio 3 d.:run_asyncrezultatai nuskaityti išresult.output_as_text;mistralaiSDK 3.7.0 versija neturioutputatributo.
Atnaujinimas 2026 m. lapkričio 2 d. — MCP Python SDK v2. Šis kursas dabar remiasi 2 versija (
mcpSDK 2.3.0 pagal 2026 m. spalio 2 d. duomenis):MCPServerpakeičiaFastMCP, transporto nustatymai perkelti įrun()arbastreamable_http_app(), o programa, eksponuojama tikru hosto vardu, privalo deklaruoti tą hosto vardą (transport_security). Tai taip pat versija, kurios reikalauja „Mistral SDK“:mistralai[agents]papildinys reikalaujamcp>=2.2.0,<3.0. Šaltiniai: Kas naujo v2 · Migracijos gidas · Diegimas ir mastelio keitimas.
Scenarijus: užduočių valdymo MCP serveris
Ankstesnėse pamokose nagrinėjome atskiras dalis: HTTP transportą, tarpinę programinę įrangą (middleware) ir prieigos raktų autentifikavimą. Dabar jas surinksi į vieną visiškai veikiantį projektą. Serveris eksponuoja keturis užduočių valdymo įrankius – sukurti, išvardinti, užbaigti, ištrinti – o klientas prisijungia nuotoliniu būdu, prie kiekvieno užklausos pateikdamas prieigos raktą (bearer token). Tas pats serveris tada veiks iš „Vibe“ be jokio papildomo kodo eilutės: tai ir yra visas nuotolinio serverio pranašumas, lyginant su STDIO serveriu.
Serveris: task_server.py
Šiame viename faile sugyvena trys elementai. „FastAPI“ tvarko HTTP transportą ir autentifikavimo tarpinę programinę įrangą, MCPServer tvarko MCP protokolą ir įrankius, o Python žodynas veikia kaip duomenų bazė. Failų tvarka svarbi: pirmiausia deklaruok MCP serverį ir jo įrankius, tada sukurk „FastAPI“ programą su lifespan, kuri paleidžia sesijų valdytoją, ir tik galiausiai prijunk serverį. Atkreipk dėmesį, kad tarpinė programinė įranga saugo kelią /tasks, kuriame tiksliai ir yra prijungtas MCP serveris: šios dvi reikšmės turi sutapti, kitaip gausi arba atviras duris, arba užtvertą kelią.
# 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)
Dvi įgyvendinimo detalės nusipelno tavo dėmesio. Funkcijoje create_task pavadinimas sutrumpinamas iki 200 simbolių, o prioritetas pagal nutylėjimą nustatomas kaip medium, jei gauta reikšmė nėra leistinų sąraše: modelis kartais siūlo tikėtinus, bet sutarties neatitinkančius parametrus, todėl įrankis privalo išlikti stabilus ir neklysti. Funkcijose complete_task ir delete_task nežinomas ID neišmeta išimties, o grąžina JSON klaidos pranešimą – modelis tai gali perskaityti, suprasti savo klaidą ir suformuluoti užklausą iš naujo, tuo tarpu programos gedimas to neleistų.
Paleisk ir eksponuok serverį
# Pirmajame terminale atidaryk ngrok tunelį
ngrok http 8000
# Viešas URL: https://xyz789.ngrok-free.app
# Antrajame terminale paleisk serverį, nurodydamas šį hosto vardą
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
MCP galinis taškas tada yra adresu https://xyz789.ngrok-free.app/tasks/mcp. Atkreipk dėmesį į šio adreso sandarą: ngrok suteiktas viešas URL, po jo einamas prijungimo kelias /tasks, o galiausiai SDK pridėtas sufiksas /mcp. Painiava dėl šio sujungimo yra pagrindinė prisijungimo nesėkmių priežastis.
Klientas: client_tasks.py
Kliento pusėje niekas nesikeičia, lyginant su vietiniu serveriu, išskyrus MCP kliento tipą ir autentifikavimo antraštės pridėjimą. Tačiau agentas gauna instrukcijas, kurios natūralia kalba aprašo jo vaidmenį – tai skatina jį patvirtinti kiekvieną veiksmą, o ne tyliai vykdyti kvietimų grandines.
# 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())
Žinučių seka yra apgalvota: ji sujungia du sukūrimus, nuskaitymą, atnaujinimą ir pakartotinį nuskaitymą. Tai minimalus scenarijus, patikrinantis, ar būsena išlieka nuo vieno kvietimo iki kito ir ar modelis gali atgauti anksčiau pokalbio metu sukurtos užduoties ID. Jei ketvirtoji instrukcija nepavyksta, problema retai kyla serveryje: dažniausiai ji kyla dėl to, kad list_tasks atsakyme ID nėra pakankamai aiškiai matomi.
Testavimas su „Mistral Vibe“
Tas pats galinis taškas gali būti pridėtas tiesiogiai kaip tinkintas jungtis (custom connector), suteikiantis testavimo sąsają nerašant kliento kodo. Tai taip pat geriausias būdas patikrinti savo dokumentacijos eilutes (docstrings): „Vibe“ jas rodo tokias, kokios yra, atradimo metu, todėl iškart matai, ką modelis turės prieš akis spręsdamas, kurį įrankį iškviesti.
- Eik į skirtuką Connectors „Vibe“ sistemoje
- Spustelėk Add Custom Connector
- Įvesk Name kaip
Task Manager, URL kaiphttps://xyz789.ngrok-free.app/tasks/mcp, tada pasirink Auth: Token ir įklijuokmcp-secret-token-2026 - Spustelėk Connect
„Vibe“ tada automatiškai atranda keturis įrankius ir gali bendrauti natūralia kalba su savo pačio serveriu.
Projekto organizavimas ir kiti žingsniai
task-mcp-project/
├── task_server.py # MCP serveris + FastAPI + autentifikavimas
├── client_tasks.py # Python klientas su agentu
├── requirements.txt # fastapi, uvicorn, mcp>=2.2,<3, mistralai[agents]
└── .env # MISTRAL_API_KEY, API_TOKEN
Šis skeletas tinka prototipams kurti, tačiau du dalykai diskvalifikuoja jį naudoti gamyboje. Grynas tekstas su prieigos raktu源代码 turi būti perkeltas į .env, o ngrok URL keičiasi kiekvieno paleidimo metu, sugadinant visas sukonfigūruotas jungtis. ngrok lieka idealus įrankis idėjai patikrinti per kelias minutes; nuolatinis talpinimas su „Docker“, debesijos ir „Hugging Face Spaces“ parinktimis yra 12 pamokos tema.
Svarbiausi punktai
- Nuotolinis serveris sujungia FastAPI (HTTP) +
MCPServer(MCP) + tarpinę programinę įrangą (autentifikavimas), o viešas hosto vardas deklaruojamastransport_security - Prieigos raktų autentifikavimas tvarkomas naudojant antraštę
Authorization: Bearer ... - Klientas
MCPClientStreamableHTTPpriima tinkintas antraštes autentifikavimui - Tas pats serveris naudojamas tiek iš Python SDK, tiek iš „Mistral“ Vibe
- ngrok leidžia greitai kurti prototipus prieš diegiant gamyboje