Przykład kompletny: Zdalny serwer z uwierzytelnianiem
Na tej stronie
Aktualizacja z 2 listopada 2026 — Le Chat to teraz Vibe. Od 28 maja 2026 r. Le Chat zmienił nazwę na Vibe (nadal pod adresem chat.mistral.ai): to pojedynczy agent do pracy i kodowania, który zachowuje Twoje konwersacje, ustawienia i subskrypcje. Legacyjne doświadczenie Le Chat pozostaje dostępne w trybie Chat; w trybie Work agenci to teraz umiejętności (wywoływane za pomocą
@»), pamięci służą jako baza wiedzy, a głębokie wyszukiwanie to umiejętność Deep Research. Plany noszą teraz nazwy Mistral Free, Pro, Team i Enterprise. W tej lekcji używamy nazwy Vibe; niektóre opisane tu menu mogły zmienić nazwy lub lokalizację. *Dodatkowa uwaga z 3 listopada: wynikirun_asyncodczytuje się zresult.output_as_text; SDKmistralaiw wersji 3.7.0 nie posiada atrybutuoutput`.*
Aktualizacja z 2 listopada 2026 — MCP Python SDK v2. Ten kurs opiera się teraz na wersji 2 SDK
mcp(2.3.0 według stanu na 2 października 2026 r.):MCPServerzastępujeFastMCP, ustawienia transportu przeniesiono dorun()lubstreamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi deklarować tę nazwę hosta (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatekmistralai[agents]wymagamcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie.
Scenariusz: Serwer MCP do zarządzania zadaniami
Poprzednie lekcje omawiały poszczególne elementy: transport HTTP, middleware i uwierzytelnianie tokenem. Teraz złożysz je w w pełni funkcjonalny projekt. Serwer udostępnia cztery narzędzia do zarządzania zadaniami — tworzenie, listowanie, kończenie i usuwanie — a klient łączy się zdalnie, przedstawiając token bearer z każdym żądaniem. Ten sam serwer uruchomisz następnie z poziomu Vibe bez ani jednej dodatkowej linii kodu: to właśnie jest główna zaleta serwera zdalnego w porównaniu z serwerem STDIO.
Serwer: task_server.py
W tym jednym pliku współistnieją trzy elementy. FastAPI obsługuje transport HTTP i middleware uwierzytelniające, MCPServer zajmuje się protokołem MCP i narzędziami, a słownik Pythona pełni rolę bazy danych. Kolejność w pliku ma znaczenie: najpierw zadeklaruj serwer MCP i jego narzędzia, następnie utwórz aplikację FastAPI z lifespan, która uruchamia menedżera sesji, a na końcu zamontuj serwer. Pamiętaj, że middleware chroni ścieżkę /tasks, czyli dokładnie tam, gdzie zamontowano serwer MCP: te dwie wartości muszą się zgadzać, inaczej uzyskasz albo otwarte drzwi, albo zablokowaną ścieżkę.
# task_server.py
"""Zdalny serwer MCP z uwierzytelnianiem tokenem."""
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
# --- Konfiguracja ---
API_TOKEN = "mcp-secret-token-2026"
# --- Baza danych w pamięci ---
tasks_db: dict[str, dict] = {}
# --- Serwer MCP ---
mcp = MCPServer("Task Manager")
@mcp.tool()
def create_task(title: str, description: str = "", priority: str = "medium") -> str:
"""Tworzy nowe zadanie w menedżerze.
Args:
title: Tytuł zadania (wymagany, maks. 200 znaków)
description: Szczegółowy opis (opcjonalny)
priority: Poziom priorytetu: low, medium, high (domyślnie: medium)
Returns:
JSON z ID i szczegółami utworzonego zadania
"""
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:
"""Wyświetla listę zadań z opcjonalnymi filtrami.
Args:
status: Filtrowanie po statusie: all, open, completed (domyślnie: all)
priority: Filtrowanie po priorytecie: all, low, medium, high (domyślnie: all)
Returns:
JSON z listą zadań i całkowitą liczbą
"""
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:
"""Oznacza zadanie jako ukończone.
Args:
task_id: Unikalny identyfikator zadania
Returns:
Potwierdzenie aktualizacji lub komunikat o błędzie
"""
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:
"""Usuwa zadanie z menedżera.
Args:
task_id: Unikalny identyfikator zadania do usunięcia
Returns:
Potwierdzenie usunięcia lub komunikat o błędzie
"""
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)
# --- Montaż serwera MCP w FastAPI ---
# streamable_http_app() tworzy aplikację ASGI dla serwera MCP.
# Jego menedżer sesji musi zostać uruchomiony przez lifespan FastAPI,
# w przeciwnym razie serwer odpowiada, ale każde wywołanie narzędzia kończy się niepowodzeniem.
@asynccontextmanager
async def lifespan(app: FastAPI):
async with mcp.session_manager.run():
yield
api = FastAPI(title="Task Manager MCP", lifespan=lifespan)
# --- Middleware uwierzytelniający ---
@api.middleware("http")
async def auth_middleware(request: Request, call_next):
"""Weryfikuje token dla wszystkich tras /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)
# Publiczny host (ngrok, domena produkcyjna) zadeklarowany dla serwera 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)
Dwa szczegóły implementacyjne zasługują na Twoją uwagę. W create_task tytuł jest skracany do 200 znaków, a priorytet domyślnie ustawiany na medium, jeśli otrzymana wartość nie znajduje się na liście dozwolonych: model czasami proponuje wartości prawdopodobne, ale niezgodne z kontraktem, a narzędzie musi pozostać odporne i nie ulegać awarii. W complete_task i delete_task nieznany identyfikator nie powoduje zgłoszenia wyjątku, lecz zwraca komunikat błędu w formacie JSON — model może go odczytać, zrozumieć swój błąd i sformułować pytanie na nowo, podczas gdy awaria uniemożliwiłaby to działanie.
Uruchomienie i udostępnienie serwera
# W pierwszym terminalu otwórz tunel ngrok
ngrok http 8000
# Publiczny URL: https://xyz789.ngrok-free.app
# W drugim terminalu uruchom serwer, deklarując tę nazwę hosta
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
Endpoint MCP znajduje się następnie pod adresem https://xyz789.ngrok-free.app/tasks/mcp. Zwróć uwagę na budowę tego adresu: publiczny URL dostarczony przez ngrok, po którym następuje ścieżka montowania /tasks, a na końcu sufiks /mcp dodany przez SDK. Nieporozumienia dotyczące tego łączenia są najczęstszą przyczyną niepowodzeń połączenia.
Klient: client_tasks.py
Po stronie klienta nic się nie zmienia w porównaniu z serwerem lokalnym, z wyjątkiem typu klienta MCP i dodania nagłówka uwierzytelniającego. Agent otrzymuje jednak instrukcje opisujące jego rolę w języku naturalnym — zachęca go to do potwierdzania każdej czynności, zamiast cichego łańcuchowania wywołań.
# client_tasks.py
"""Klient MCP dla zdalnego serwera zadań z uwierzytelnianiem."""
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"])
# Utwórz agenta z dostosowanymi instrukcjami
agent = client.beta.agents.create(
model="mistral-medium-latest",
name="task-manager",
instructions=(
"Jesteś inteligentnym menedżerem zadań. "
"Używaj dostępnych narzędzi do tworzenia, listowania i zarządzania "
"zadaniami użytkownika. Odpowiadaj w języku angielskim. "
"Potwierdzaj każdą wykonaną czynność."
),
)
# Skonfiguruj zdalnego klienta MCP z uwierzytelnianiem
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)
# Konwersacja z menedżerem
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())
Sekwencja wiadomości jest celowa: łączy dwa utworzenia, odczyt, aktualizację i ponowny odczyt. To minimalny scenariusz pozwalający zweryfikować, czy stan przetrwał między wywołaniami i czy model potrafi odzyskać ID zadania utworzonego wcześniej w trakcie konwersacji. Jeśli czwarta instrukcja zawiedzie, problem rzadko leży po stronie serwera: zazwyczaj wynika z faktu, że odpowiedź list_tasks nie czyni identyfikatorów wystarczająco widocznymi.
Testowanie w Mistral Vibe
Ten sam endpoint można dodać bezpośrednio jako niestandardowy konektor, co daje interfejs testowy bez konieczności pisania klienta. To także najlepszy sposób na walidację Twoich docstringów: Vibe wyświetla je tak, jak są, podczas odkrywania, więc od razu widzisz, co model będzie miał przed sobą, decydując, którego narzędzia użyć.
- Przejdź do zakładki Connectors w Vibe
- Kliknij Add Custom Connector
- Wprowadź Name jako
Task Manager, URL jakohttps://xyz789.ngrok-free.app/tasks/mcp, następnie wybierz Auth: Token i wklejmcp-secret-token-2026 - Kliknij Connect
Vibe automatycznie odkrywa cztery narzędzia, dzięki czemu możesz prowadzić konwersację w języku naturalnym z własnym serwerem.
Organizacja projektu i kolejne kroki
task-mcp-project/
├── task_server.py # Serwer MCP + FastAPI + auth
├── client_tasks.py # Klient Python z agentem
├── requirements.txt # fastapi, uvicorn, mcp>=2.2,<3, mistralai[agents]
└── .env # MISTRAL_API_KEY, API_TOKEN
Ten szkielet sprawdza się do prototypowania, ale dwie rzeczy dyskwalifikują go do użycia produkcyjnego. Token w postaci zwykłego tekstu w kodzie źródłowym musi zostać przeniesiony do .env, a URL ngrok zmienia się przy każdym restarcie, co powoduje zerwanie wszystkich skonfigurowanych konektorów. ngrok pozostaje idealnym narzędziem do szybkiej walidacji pomysłu w ciągu kilku minut; trwałe hostowanie, z opcjami Docker, chmury i Hugging Face Spaces, jest tematem lekcji 12.
Kluczowe wnioski
- Serwer zdalny łączy FastAPI (HTTP) +
MCPServer(MCP) + middleware (auth), przy czym publiczny host jest deklarowany wtransport_security - Uwierzytelnianie tokenem odbywa się poprzez nagłówek
Authorization: Bearer ... - Klient
MCPClientStreamableHTTPakceptuje niestandardowe nagłówki do uwierzytelniania - Ten sam serwer jest użyteczny zarówno z Python SDK, jak i Mistral Vibe
- ngrok umożliwia szybkie prototypowanie przed wdrożeniem produkcyjnym