Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Kompletný príklad: Vzdialený server s autentifikáciou

Lekcia 9 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Scenár: MCP Server na správu úloh
  2. Server: task_server.py
  3. Spustenie a vystavenie servera
  4. Klient: client_tasks.py
  5. Testovanie v Mistral Vibe
  6. Organizácia projektu a ďalšie kroky
  7. Kľúčové poznatky

Aktualizácia 2. novembra 2026 — Le Chat je teraz Vibe. Od 28. mája 2026 prešiel Le Chat rebrandingom na Vibe (stále na chat.mistral.ai): jediný agent pre prácu a kód, ktorý si zachováva vaše konverzácie, nastavenia a predplatné. Pôvodné prostredie Le Chat zostáva dostupné v režime Chat; v režime Work sú agenti teraz zručnosti (vyvolávané pomocou @), spomienky slúžia ako znalostná báza a hĺbkové vyhľadávanie je zručnosť Deep Research. Plány sa teraz nazývajú Mistral Free, Pro, Team a Enterprise. Táto lekcia používa názov Vibe; niektoré tu opísané ponuky mohli zmeniť názvy alebo umiestnenie. Dodatok 3. novembra: výsledky run_async sa čítajú z result.output_as_text; SDK mistralai verzie 3.7.0 nemá atribút output.

Aktualizácia 2. novembra 2026 — MCP Python SDK v2. Tento kurz teraz nasleduje verziu 2 SDK mcp (2.3.0 k 2. októbru 2026): MCPServer nahrádza FastMCP, nastavenia transportu sa presúvajú do run() alebo streamable_http_app() a aplikácia vystavená pod skutočným hostname musí tento hostname deklarovať (transport_security). Toto je tiež verzia požadovaná Mistral SDK: extra balík mistralai[agents] vyžaduje mcp>=2.2.0,<3.0. Zdroje: Čo je nové vo v2 · Sprievodca migráciou · Nasadenie a škálovanie.

Scenár: MCP Server na správu úloh

Predchádzajúce lekcie pokryli jednotlivé časti: HTTP transport, middleware a tokenovú autentifikáciu. Teraz ich poskladáš do plne funkčného projektu. Server vystavuje štyri nástroje na správu úloh – vytvorenie, zoznam, dokončenie, vymazanie – a klient sa pripája vzdialene, pričom ku každej požiadavke predkladá bearer token. Tento istý server potom beží vo Vibe bez jediného riadku kódu navyše: to je celá výhoda vzdialeného servera oproti serveru STDIO.

Server: task_server.py

V tomto jednom súbore koexistujú tri prvky. FastAPI rieši HTTP transport a autentizačný middleware, MCPServer sa stará o protokol MCP a nástroje a Python slovník slúži ako databáza. Poradie súborov je dôležité: najprv deklaruj MCP server a jeho nástroje, potom vytvor FastAPI aplikáciu s lifespan, ktorá spustí správcu relácie, a server namontuj až nakoniec. Všimni si, že middleware chráni cestu /tasks, čo je presne miesto, kde je namontovaný MCP server: tieto dve hodnoty sa musia zhodovať, inak skončíš buď s otvorenými dverami, alebo s uzavretou cestou.

# task_server.py
"""Vzdialený MCP server s tokenovou autentifikáciou."""

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

# --- Konfigurácia ---
API_TOKEN = "mcp-secret-token-2026"

# --- Databáza v pamäti ---
tasks_db: dict[str, dict] = {}

# --- MCP Server ---
mcp = MCPServer("Task Manager")

@mcp.tool()
def create_task(title: str, description: str = "", priority: str = "medium") -> str:
    """Vytvorí novú úlohu v správcovi.

    Args:
        title: Názov úlohy (povinný, max 200 znakov)
        description: Podrobný popis (voliteľné)
        priority: Úroveň priority: low, medium, high (predvolené: medium)

    Returns:
        JSON s ID a detailmi vytvorenej úlohy
    """
    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:
    """Vypíše úlohy s voliteľnými filtrami.

    Args:
        status: Filter podľa stavu: all, open, completed (predvolené: all)
        priority: Filter podľa priority: all, low, medium, high (predvolené: all)

    Returns:
        JSON so zoznamom úloh a celkovým počtom
    """
    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:
    """Označí úlohu ako dokončenú.

    Args:
        task_id: Unikátny identifikátor úlohy

    Returns:
        Potvrdenie aktualizácie alebo chybová správa
    """
    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:
    """Vymaže úlohu zo správcu.

    Args:
        task_id: Unikátny identifikátor úlohy na vymazanie

    Returns:
        Potvrdenie vymazania alebo chybová správa
    """
    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)

# --- Namontovanie MCP servera do FastAPI ---
# streamable_http_app() vytvára ASGI aplikáciu pre MCP server.
# Jeho session manager musí byť spustený cez FastAPI lifespan,
# inak server odpovedá, ale každý volanie nástroja zlyhá.
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with mcp.session_manager.run():
        yield

api = FastAPI(title="Task Manager MCP", lifespan=lifespan)

# --- Autentizačný Middleware ---
@api.middleware("http")
async def auth_middleware(request: Request, call_next):
    """Overí token pre všetky trasy /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)

# Verejný hostname (ngrok, produkčná doména) deklarovaný MCP serveru
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)

Dva implementačné detaily si zaslúžia tvoju pozornosť. V create_task je názov orezaný na 200 znakov a priorita sa predvolí na medium, ak prijatá hodnota nie je v povolenom zozname: model niekedy navrhuje plausible, ale mimo zmluvy stojace hodnoty a nástroj musí zostať robustný bez zlyhania. V complete_task a delete_task neznáme ID nezdvihne výnimku, ale vráti JSON chybovú správu – model si to môže prečítať, pochopiť svoju chybu a formulovať to znova, zatiaľ čo pád by tomu zabránil.

Spustenie a vystavenie servera

# V prvom termináli otvor ngrok tunel
ngrok http 8000
# Verejná URL: https://xyz789.ngrok-free.app

# V druhom termináli spusti server s deklaráciou tohto hostname
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py

MCP endpoint sa potom nachádza na https://xyz789.ngrok-free.app/tasks/mcp. Všimni si zloženie tejto adresy: verejná URL poskytnutá ngrokom, nasledovaná cestou mountu /tasks a potom príponou /mcp pridanou SDK. Zmätok okolo tejto konkatencie je hlavnou príčinou zlyhaní pripojenia.

Klient: client_tasks.py

Na strane klienta sa nič nemení oproti lokálnemu serveru okrem typu MCP klienta a pridania autentizačnej hlavičky. Agent však dostáva inštrukcie, ktoré opisujú jeho rolu prirodzeným jazykom – to ho povzbudzuje, aby potvrdil každú akciu namiesto tichého reťazenia volaní.

# client_tasks.py
"""MCP klient pre vzdialený server úloh s autentifikáciou."""

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"])

    # Vytvorenie agenta s upravenými inštrukciami
    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."
        ),
    )

    # Konfigurácia vzdialeného MCP klienta s autentifikáciou
    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)

        # Konverzácia so správcom
        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())

Sekvencia správ je zámerná: reťazí dve vytvorenia, čítanie, aktualizáciu a opätovné čítanie. Toto je minimálny scenár na overenie, že stav pretrváva z jedného volania do druhého a že model dokáže získať ID úlohy vytvorenej skôr v konverzácii. Ak štvrtá inštrukcia zlyhá, tvoj problém zriedka leží na strane servera: zvyčajne pramení z toho, že odpoveď list_tasks neurobí ID dostatočne viditeľnými.

Testovanie v Mistral Vibe

Ten istý endpoint môžeš pridať priamo ako vlastný konektor, čo ti dáva testovacie rozhranie bez písania klienta. Toto je tiež najlepší spôsob, ako validovať svoje docstringy: Vibe ich zobrazuje tak, ako sú, počas objavovania, takže okamžite vidíš, čo bude mať model pred sebou pri rozhodovaní, ktorý nástroj zavolať.

  1. Prejdi na kartu Connectors vo Vibe
  2. Klikni na Add Custom Connector
  3. Zadaj Name ako Task Manager, URL ako https://xyz789.ngrok-free.app/tasks/mcp, potom vyber Auth: Token a vlož mcp-secret-token-2026
  4. Klikni na Connect

Vibe potom automaticky objaví štyri nástroje a môžeš konverzovať prirodzeným jazykom so svojím vlastným serverom.

Organizácia projektu a ďalšie kroky

task-mcp-project/
├── task_server.py       # MCP server + FastAPI + auth
├── client_tasks.py      # Python klient s agentom
├── requirements.txt     # fastapi, uvicorn, mcp>=2.2,<3, mistralai[agents]
└── .env                 # MISTRAL_API_KEY, API_TOKEN

Táto kostra funguje pre prototypovanie, ale dve veci ju diskvalifikujú pre produkciu. Plaintext token v zdrojovom kóde sa musí presunúť do .env a ngrok URL sa mení pri každom reštarte, čo rozbije všetky nakonfigurované konektory. ngrok zostáva ideálnym nástrojom na validáciu nápadu v priebehu minút; trvalé hostovanie s jeho možnosťami Docker, cloud a Hugging Face Spaces je témou lekcie 12.

Kľúčové poznatky

  • Vzdialený server kombinuje FastAPI (HTTP) + MCPServer (MCP) + middleware (auth), pričom verejný hostname je deklarovaný v transport_security
  • Tokenová autentifikácia sa rieši cez hlavičku Authorization: Bearer ...
  • Klient MCPClientStreamableHTTP akceptuje vlastné hlavičky pre autentifikáciu
  • Ten istý server je použiteľný z Python SDK aj z Mistral Vibe
  • ngrok umožňuje rýchle prototypovanie pred produkčným nasadením