Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Esimerkki kokonaisuudessaan: etäpalvelin todennuksella

Oppitunti 9 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Skenaario: Tehtävienhallinnan MCP-palvelin
  2. Palvelin: task_server.py
  3. Palvelimen käynnistäminen ja julkaiseminen
  4. Asiakas: client_tasks.py
  5. Testaus Mistral Vibessä
  6. Projektin organisaatio ja seuraavat askeleet
  7. Keskeiset asiat

Päivitys 2. marraskuuta 2026 — Le Chat on nyt Vibe. 28. toukokuuta 2026 lähtien Le Chat on uudelleenbrändätty nimelle Vibe (osoitteessa chat.mistral.ai): yksi agentti työhön ja koodaukseen, joka säilyttää keskustelusi, asetuksesi ja tilauksesi. Vanha Le Chat -kokemus on edelleen käytettävissä Chat-tilassa; Work-tilassa agenteista on tullut taitoja (kutsutaan merkillä @), muistit toimivat tietopankkina ja syvähaku on Deep Research -taito. Suunnitelmat ovat nyt nimeltään Mistral Free, Pro, Team ja Enterprise. Tässä oppitunnissa käytetään nimeä Vibe; jotkin tässä kuvatut valikot ovat voineet vaihtaa nimeä tai sijaintia. Lisäys 3. marraskuuta: run_async-tulokset luetaan kohdasta result.output_as_text; mistralai SDK:n versiossa 3.7.0 ei ole output-attribuuttia.

Päivitys 2. marraskuuta 2026 — MCP Python SDK v2. Tämä kurssi seuraa nyt mcp SDK:n versiota 2 (2.3.0 päivätty 2. lokakuuta 2026): MCPServer korvaa FastMCP:n, kuljetusasetukset siirtyvät metodeihin run() tai streamable_http_app(), ja oikean isäntänimen alla julkaistun sovelluksen on ilmoitettava kyseinen isäntänimi (transport_security). Tämä on myös Mistral SDK:n vaatima versio: mistralai[agents]-lisäosa vaatii mcp>=2.2.0,<3.0. Lähteet: Mitä uutta versiossa v2 · Migraatio-opas · Käyttöönotto ja skaalaus.

Skenaario: Tehtävienhallinnan MCP-palvelin

Aiemmissa oppitunneissa käsiteltiin yksittäisiä osia: HTTP-kuljetus, välitysohjelmisto ja tunnistautuminen tokenilla. Nyt kokoat ne toimivaksi kokonaisuudeksi. Palvelin tarjoaa neljä tehtävienhallintatyökalua – luominen, listaus, valmistuminen ja poistaminen – ja asiakas yhdistää etänä lähettäen bearer-tokenin jokaisen pyynnön mukana. Sama palvelin toimii sitten Vibessä ilman yhtään ylimääräistä koodiriviä: siinä koko etäpalvelimen etu STDIO-palvelimeen verrattuna.

Palvelin: task_server.py

Tässä yhdessä tiedostossa elävät rinnakkain kolme elementtiä. FastAPI hoitaa HTTP-kuljetuksen ja todennusvälitysohjelmiston, MCPServer hoitaa MCP-protokollan ja työkalut, ja Python-sanakirja toimii tietokantana. Tiedoston järjestys on tärkeä: ilmoita ensin MCP-palvelin ja sen työkalut, luo sitten FastAPI-sovellus lifespan-funktiolla, joka käynnistää istunnonhallinnan, ja kiinnitä palvelin viimeiseksi. Huomaa, että välitysohjelmisto suojaa polkua /tasks, johon MCP-palvelin on kiinnitetty: näiden kahden arvon on täsmättävä, muuten päädyt joko avoimeen oveen tai muurattuun polkuun.

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

Kaksi toteutusyksityiskohtaa ansaitsevat huomiosi. Funktiossa create_task otsikko katkaistaan 200 merkkiin ja prioriteetti oletusarvoistetaan arvoksi medium, jos vastaanotettu arvo ei ole sallittujen listalla: malli ehdottaa joskus uskottavia mutta sopimuksen ulkopuolisia arvoja, ja työkalun on pysyttävä vakaana epäonnistumatta. Funktioissa complete_task ja delete_task tuntematon ID ei heitä poikkeusta, vaan palauttaa JSON-virheilmoituksen – malli voi lukea tämän, ymmärtää virheensä ja muotoilla pyynnön uudelleen, kun taas kaatuminen estäisi tämän.

Palvelimen käynnistäminen ja julkaiseminen

# Avaa ngrok-tunneli ensimmäisessä päätteenässä
ngrok http 8000
# Julkinen URL: https://xyz789.ngrok-free.app

# Käynnistä palvelin toisessa päätteenässä ilmoittaen tämä isäntänimi
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py

MCP-päätepiste sijaitsee osoitteessa https://xyz789.ngrok-free.app/tasks/mcp. Huomaa tämän osoitteen muodostuminen: ngrokin tarjoama julkinen URL, jota seuraa kiinnityspolku /tasks ja lopuksi SDK:n lisäämä suffiksi /mcp. Sekaannus tässä ketjutuksessa on yleisin syy yhteysvirheisiin.

Asiakas: client_tasks.py

Asiakaspuolella mikään ei muutu paikalliseen palvelimeen verrattuna, paitsi MCP-asiakkaan tyyppi ja todennusotsakkeen lisääminen. Agentti saa kuitenkin ohjeet, jotka kuvaavat sen roolin luonnollisella kielellä – tämä kannustaa sitä vahvistamaan jokaisen toiminnan sen sijaan, että se ketjuttaisi kutsuja hiljaa.

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

Viestijono on harkittu: se ketjuttaa kaksi luontia, lukemisen, päivityksen ja uudelleenlukemisen. Tämä on minimaalinen skenaario sen varmistamiseksi, että tila säilyy kutsusta toiseen ja että malli pystyy hakemaan aiemmin keskustelussa luodun tehtävän ID:n. Jos neljäs ohje epäonnistuu, ongelma on harvoin palvelimessa: se johtuu yleensä siitä, että list_tasks-vastaus ei tee ID-tunnisteista tarpeeksi näkyviä.

Testaus Mistral Vibessä

Sama päätepiste voidaan lisätä suoraan mukautettuna liittimenä, mikä antaa sinulle testikäyttöliittymän ilman asiakaskoodin kirjoittamista. Tämä on myös paras tapa validoida docstringisi: Vibe näyttää ne sellaisinaan etsinnän aikana, joten näet heti, mitä mallilla on edessään päättäessään, mitä työkalua kutsua.

  1. Siirry Vibessä välilehdelle Connectors
  2. Napsauta Add Custom Connector
  3. Syötä Name arvoksi Task Manager, URL arvoksi https://xyz789.ngrok-free.app/tasks/mcp ja valitse Auth: Token sekä liitä arvo mcp-secret-token-2026
  4. Napsauta Connect

Vibe löytää automaattisesti neljä työkalua, ja voit keskustella luonnollisella kielellä oman palvelimesi kanssa.

Projektin organisaatio ja seuraavat askeleet

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

Tämä runko toimii prototyyppaukseen, mutta kaksi asiaa estää sen käytön tuotannossa. Lähdekoodissa oleva selväkielinen token on siirrettävä tiedostoon .env, ja ngrok-URL muuttuu jokaisella uudelleenkäynnistyksellä, mikä rikkoo kaikki määritetyt liittimet. ngrok on edelleen ihanteellinen työkalu idean validointiin minuuteissa; pysyvä hosting Dockerilla, pilvipalveluilla ja Hugging Face Spaces -vaihtoehdoilla on oppitunnin 12 aihe.

Keskeiset asiat

  • Etäpalvelin yhdistää FastAPI:n (HTTP) + MCPServer:n (MCP) + välitysohjelmiston (auth), ja julkinen isäntänimi ilmoitetaan kohdassa transport_security
  • Token-todennus hoidetaan otsakkeen Authorization: Bearer ... kautta
  • MCPClientStreamableHTTP-asiakas hyväksyy mukautetut otsakkeet todennusta varten
  • Sama palvelin on käytettävissä sekä Python SDK:sta että Mistral Vibestä
  • ngrok mahdollistaa nopean prototyyppauksen ennen tuotantoon siirtämistä