Пълен пример: Отдалечен сървър с удостоверяване
На тази страница
Актуализация от 2 ноември 2026 г. — Le Chat вече е Vibe. От 28 май 2026 г. Le Chat беше ребрандиран като Vibe (все още на chat.mistral.ai): единен агент за работа и кодиране, който запазва Вашите разговори, настройки и абонаменти. Старият интерфейс на Le Chat остава достъпен в режим Chat; в режим Work агентите вече са умения (извикват се с
@, спомените служат като база знания, а задълбоченото търсене е умението Deep Research. Плановете вече се наричат Mistral Free, Pro, Team и Enterprise. Този урок използва името Vibe; някои менюта, описани тук, може да са променили имената или местоположенията си. Добавка от 3 ноември: резултатите отrun_asyncсе четат отresult.output_as_text; SDKmistralaiверсия 3.7.0 няма атрибутoutput.
Актуализация от 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на SDK
mcp(2.3.0 към 2 октомври 2026 г.):MCPServerзаместваFastMCP, настройките за транспорт се преместват вrun()илиstreamable_http_app(), а приложение, изложено под реално име на хост, трябва да декларира това име на хост (transport_security). Това е също версията, изисквана от Mistral SDK: допълнениетоmistralai[agents]изискваmcp>=2.2.0,<3.0. Източници: Какво е ново във v2 · Ръководство за миграция · Разполагане и мащабиране.
Сценарий: MCP сървър за управление на задачи
Предишните уроци разгледаха отделните компоненти: HTTP транспорт, междинен софтуер (middleware) и удостоверяване чрез токени. Сега ще ги сглобите в напълно функционален проект. Сървърът предоставя четири инструмента за управление на задачи — създаване, изброяване, завършване и изтриване, — а клиентът се свързва отдалечено, представяйки bearer токен с всяка заявка. Същият този сървър след това ще работи от Vibe без нито един допълнителен ред код: това е цялото предимство на отдалечения сървър спрямо STDIO сървър.
Сървърът: task_server.py
Три елемента съществуват заедно в този единствен файл. FastAPI се грижи за HTTP транспорта и междинния софтуер за удостоверяване, MCPServer управлява MCP протокола и инструментите, а речник на Python служи като база данни. Редът на файловете има значение: първо декларирайте MCP сървъра и неговите инструменти, след това създайте FastAPI приложението с lifespan, което стартира мениджъра на сесиите, и най-накрая монтирайте сървъра. Имайте предвид, че междинният софтуер защитава пътя /tasks, който е точно там, където е монтиран MCP сървърът: тези две стойности трябва да съвпадат, в противен случай ще се окажете или с отворена врата, или с блокиран път.
# 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)
Два детайла от реализацията заслужават вниманието Ви. В create_task заглавието се съкращава до 200 знака, а приоритетът по подразбиране е medium, ако получената стойност не е в разрешения списък: моделът понякога предлага правдоподобни, но извън договорените стойности, и инструментът трябва да остане устойчив, без да се срива. В complete_task и delete_task неизвестен ID не предизвиква изключение, а връща JSON съобщение за грешка — моделът може да прочете това, да разбере грешката си и да преформулира, докато сривът би предотвратил това.
Стартиране и излагане на сървъра
# В първи терминал отворете тунела на ngrok
ngrok http 8000
# Публичен URL: https://xyz789.ngrok-free.app
# Във втори терминал стартирайте сървъра, декларирайки това име на хост
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
MCP крайната точка се намира тогава на https://xyz789.ngrok-free.app/tasks/mcp. Обърнете внимание на състава на този адрес: публичният URL, предоставен от ngrok, последван от пътя за монтиране /tasks, и след това наставката /mcp, добавена от SDK. Объркването относно тази конкатенация е водещата причина за неуспешни връзки.
Клиентът: client_tasks.py
От страна на клиента нищо не се променя в сравнение с локален сървър, освен типа на MCP клиента и добавянето на хедър за удостоверяване. Агентът обаче получава инструкции, които описват ролята му на естествен език — това го насърчава да потвърждава всяко действие, вместо тихо да верижно извиква функции.
# 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())
Последователността от съобщения е умишлена: тя верижно свързва две създавания, едно четене, едно обновяване и едно повторно четене. Това е минималният сценарий за проверка дали състоянието оцелява от едно извикване до следващото и дали моделът може да извлече ID на задача, създадена по-рано в разговора. Ако четвъртата инструкция се провали, проблемът Ви рядко е в сървъра: обикновено произтича от това, че отговорът на list_tasks не прави ID-тата достатъчно видими.
Тестване в Mistral Vibe
Същата крайна точка може да бъде добавена директно като персонализиран конектор, което Ви дава тестов интерфейс без писане на клиент. Това е също най-добрият начин за валидиране на Вашите docstrings: Vibe ги показва както са по време на откриването, така че веднага виждате какво ще има моделът пред себе си, за да реши кой инструмент да извика.
- Отидете в раздела Connectors във Vibe
- Кликнете върху Add Custom Connector
- Въведете Name като
Task Manager, URL катоhttps://xyz789.ngrok-free.app/tasks/mcp, след това изберете Auth: Token и поставетеmcp-secret-token-2026 - Кликнете върху Connect
Vibe след това автоматично открива четирите инструмента и можете да разговаряте на естествен език със собствения си сървър.
Организация на проекта и следващи стъпки
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
Тази скелетна структура работи за прототипиране, но две неща я дисквалифицират за продукция. Токенът в чист текст в изходния код трябва да се премести в .env, а URL адресът на ngrok се променя при всяко рестартиране, което нарушава всички конфигурирани конектори. ngrok остава идеалният инструмент за валидиране на идея за минути; постоянното хостване, с неговите опции за Docker, облак и Hugging Face Spaces, е предмет на урок 12.
Ключови изводи
- Отдалеченият сървър комбинира FastAPI (HTTP) +
MCPServer(MCP) + middleware (auth), като публичното име на хоста се декларира вtransport_security - Удостоверяването чрез токен се обработва чрез хедъра
Authorization: Bearer ... - Клиентът
MCPClientStreamableHTTPприема персонализирани хедъри за удостоверяване - Един и същ сървър е използваем както от Python SDK, така и от Mistral Vibe
- ngrok позволява бързо прототипиране преди разполагане в продукция