Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Primjer u cijelosti: Udaljeni poslužitelj s autentifikacijom

Lekcija 9 od 14 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Scenarij: MCP poslužitelj za upravljanje zadacima
  2. Poslužitelj: task_server.py
  3. Pokretanje i izlaganje poslužitelja
  4. Klijent: client_tasks.py
  5. Testiranje u Mistral Vibeu
  6. Organizacija projekta i sljedeći koraci
  7. Ključne točke

Ažuriranje 2. studenoga 2026. — Le Chat sada je Vibe. Od 28. svibnja 2026., Le Chat je rebrendiran kao Vibe (i dalje na chat.mistral.ai): jedan agent za posao i kod koji prenosi tvoje razgovore, postavke i pretplate. Legacy iskustvo Le Chata ostaje dostupno u načinu Chat; u načinu Work, agenti su sada vještine (pozivaju se s @), memorije služe kao baza znanja, a dubinsko pretraživanje je vještina Deep Research. Planovi se sada zovu Mistral Free, Pro, Team i Enterprise. Ova lekcija koristi ime Vibe; neki izbornici opisani ovdje možda su promijenili imena ili lokacije. Dodatak 3. studenoga: rezultati run_async čitaju se iz result.output_as_text; SDK mistralai verzije 3.7.0 nema atribut output.

Ažuriranje 2. studenoga 2026. — MCP Python SDK v2. Ovaj tečaj sada prati verziju 2 SDK-a mcp (2.3.0 od 2. listopada 2026.): MCPServer zamjenjuje FastMCP, postavke transporta prelaze u run() ili streamable_http_app(), a aplikacija izložena pod stvarnim imenom hosta mora deklarirati to ime hosta (transport_security). Ovo je također verzija koju zahtijeva Mistral SDK: dodatak mistralai[agents] zahtijeva mcp>=2.2.0,<3.0. Izvori: Što je novo u v2 · Vodič za migraciju · Implementacija i skaliranje.

Scenarij: MCP poslužitelj za upravljanje zadacima

Prethodne lekcije pokrivale su pojedinačne dijelove: HTTP transport, srednji sloj (middleware) i autentifikaciju tokenom. Sada ćeš ih sastaviti u potpuno funkcionalan projekt. Poslužitelj izlaže četiri alata za upravljanje zadacima—stvaranje, popis, dovršavanje, brisanje—klijent se povezuje udaljeno i uz svaki zahtjev prilaže bearer token. Taj isti poslužitelj zatim će se pokrenuti iz Vibea bez ijednog dodatnog retka koda: to je cijela prednost udaljenog poslužitelja u odnosu na STDIO poslužitelj.

Poslužitelj: task_server.py

Tri elementa suživota u ovoj jednoj datoteci. FastAPI rukuje HTTP transportom i srednjim slojem za autentifikaciju, MCPServer rukuje MCP protokolom i alatima, a Python rječnik služi kao baza podataka. Redoslijed datoteke je bitan: prvo deklariraj MCP poslužitelj i njegove alate, zatim stvori FastAPI aplikaciju s lifespan ciklusom koji pokreće upravitelja sesije, i na kraju montiraj poslužitelj. Imaj na umu da srednji sloj štiti putanju /tasks, što je točno mjesto gdje je MCP poslužitelj montiran: ove dvije vrijednosti moraju se podudarati, inače ćeš završiti ili s otvorenim vratima ili s ograđenom putanjom.

# 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)

Dva detalja implementacije zaslužuju tvoju pažnju. U create_task, naslov se skraćuje na 200 znakova, a prioritet se zadaje kao medium ako primljena vrijednost nije na popisu dopuštenih: model ponekad predloži uvjerljive, ali izvanugovorne vrijednosti, a alat mora ostati robustan bez rušenja. U complete_task i delete_task, nepoznat ID ne podiže iznimku, već vraća JSON poruku o grešci—model to može pročitati, shvatiti svoju pogrešku i preformulirati zahtjev, dok bi rušenje to onemogućilo.

Pokretanje i izlaganje poslužitelja

# U prvom terminalu, otvori ngrok tunel
ngrok http 8000
# Javni URL: https://xyz789.ngrok-free.app

# U drugom terminalu, pokreni poslužitelj deklarirajući ovo ime hosta
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py

MCP krajnja točka tada se nalazi na https://xyz789.ngrok-free.app/tasks/mcp. Obrati pažnju na sastav ove adrese: javni URL koji osigurava ngrok, nakon čega slijedi putanja montiranja /tasks, a zatim sufiks /mcp koji dodaje SDK. Zbrka oko ove konkatenacije vodeći je uzrok neuspjeha povezivanja.

Klijent: client_tasks.py

Na strani klijenta, ništa se ne mijenja u odnosu na lokalni poslužitelj, osim vrste MCP klijenta i dodavanja zaglavlja za autentifikaciju. Agent, međutim, prima upute koje opisuju njegovu ulogu prirodnim jezikom—to ga potiče da potvrdi svaku radnju umjesto da tiho lančano poziva funkcije.

# 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())

Niz poruka je namjeran: lančano povezuje dva stvaranja, čitanje, ažuriranje i ponovno čitanje. Ovo je minimalni scenarij za provjeru preživljava li stanje od jednog poziva do drugog i može li model dohvatiti ID zadatka stvorenog ranije u razgovoru. Ako četvrta uputa ne uspije, tvoj problem rijetko leži u poslužitelju: obično proizlazi iz toga što odgovor list_tasks ne čini ID-ove dovoljno vidljivima.

Testiranje u Mistral Vibeu

Ista se krajnja točka može dodati izravno kao prilagođeni konektor, što ti daje sučelje za testiranje bez pisanja klijenta. Ovo je također najbolji način za validaciju tvojih docstringova: Vibe ih prikazuje kakvi jesu tijekom otkrivanja, pa odmah vidiš što će model imati ispred sebe kako bi odlučio koji alat pozvati.

  1. Idi na karticu Connectors u Vibeu
  2. Klikni Add Custom Connector
  3. Unesi Name kao Task Manager, URL kao https://xyz789.ngrok-free.app/tasks/mcp, zatim odaberi Auth: Token i zalijepi mcp-secret-token-2026
  4. Klikni Connect

Vibe zatim automatski otkriva četiri alata i možeš razgovarati prirodnim jezikom sa svojim vlastitim poslužiteljem.

Organizacija projekta i sljedeći koraci

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

Ovaj kostur radi za izradu prototipa, ali dvije stvari ga diskvalificiraju za proizvodnju. Token u običnom tekstu u izvornom kodu mora se premjestiti u .env, a ngrok URL se mijenja pri svakom ponovnom pokretanju, čime se lome svi konfigurirani konektori. ngrok ostaje idealan alat za validaciju ideje u nekoliko minuta; trajno hostanje, s opcijama Docker, cloud i Hugging Face Spaces, tema je lekcije 12.

Ključne točke

  • Udaljeni poslužitelj kombinira FastAPI (HTTP) + MCPServer (MCP) + middleware (auth), s javnim imenom hosta deklariranim u transport_security
  • Autentifikacija tokenom obrađuje se putem zaglavlja Authorization: Bearer ...
  • Klijent MCPClientStreamableHTTP prihvaća prilagođena zaglavlja za autentifikaciju
  • Isti se poslužitelj može koristiti i iz Python SDK-a i iz Mistral Vibea
  • ngrok omogućuje brzu izradu prototipa prije proizvodne implementacije