Przejdź do głównej treści
Polski— Wybierz język
Menu

Przykład kompletny: Zdalny serwer z uwierzytelnianiem

Lekcja 9 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Scenariusz: Serwer MCP do zarządzania zadaniami
  2. Serwer: task_server.py
  3. Uruchomienie i udostępnienie serwera
  4. Klient: client_tasks.py
  5. Testowanie w Mistral Vibe
  6. Organizacja projektu i kolejne kroki
  7. Kluczowe wnioski

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: wyniki run_asyncodczytuje się zresult.output_as_text; SDK mistralaiw 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.): MCPServer zastępuje FastMCP, ustawienia transportu przeniesiono do run() lub streamable_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: dodatek mistralai[agents] wymaga mcp>=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ć.

  1. Przejdź do zakładki Connectors w Vibe
  2. Kliknij Add Custom Connector
  3. Wprowadź Name jako Task Manager, URL jako https://xyz789.ngrok-free.app/tasks/mcp, następnie wybierz Auth: Token i wklej mcp-secret-token-2026
  4. 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 w transport_security
  • Uwierzytelnianie tokenem odbywa się poprzez nagłówek Authorization: Bearer ...
  • Klient MCPClientStreamableHTTP akceptuje 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