Voorbeeld: Externe server met authenticatie
Op deze pagina
Update 2 november 2026 — Le Chat heet nu Vibe. Sinds 28 mei 2026 is Le Chat omgedoopt tot Vibe (nog steeds op chat.mistral.ai): één agent voor werk en code, die uw gesprekken, instellingen en abonnementen overneemt. De oorspronkelijke Le Chat-ervaring blijft beschikbaar in de modus Chat; in de modus Work zijn agents nu vaardigheden (aan te roepen met
@), dienen herinneringen als kennisbank en is diep zoeken de vaardigheid Deep Research. Abonnementen heten nu Mistral Free, Pro, Team en Enterprise. Deze les gebruikt de naam Vibe; sommige hier beschreven menu’s kunnen van naam of locatie zijn veranderd. Addendum 3 november: resultaten vanrun_asyncworden gelezen viaresult.output_as_text; demistralaiSDK 3.7.0 heeft geen attribuutoutput.
Update 2 november 2026 — MCP Python SDK v2. Deze cursus volgt nu versie 2 van de
mcpSDK (2.3.0 per 2 oktober 2026):MCPServervervangtFastMCP, transportinstellingen verhuizen naarrun()ofstreamable_http_app(), en een app die onder een echte hostnaam wordt aangeboden, moet die hostnaam declareren (transport_security). Dit is ook de versie die vereist is door de Mistral SDK: de extramistralai[agents]vereistmcp>=2.2.0,<3.0. Bronnen: Wat is nieuw in v2 · Migratiegids · Implementeren en schalen.
Scenario: Een MCP-server voor taakbeheer
Eerdere lessen behandelden de afzonderlijke onderdelen: HTTP-transport, middleware en token-authenticatie. Nu voegt u ze samen tot een volledig functioneel project. De server biedt vier tools voor taakbeheer aan: maken, lijst weergeven, voltooien en verwijderen. De client maakt op afstand verbinding en stuurt bij elk verzoek een bearer-token mee. Dezelfde server draait vervolgens vanuit Vibe zonder ook maar één regel extra code: dat is het volledige voordeel van een externe server ten opzichte van een STDIO-server.
De server: task_server.py
Drie elementen coëxisteren in dit ene bestand. FastAPI verzorgt het HTTP-transport en de authenticatiemiddleware, MCPServer regelt het MCP-protocol en de tools, en een Python-dictionary fungeert als database. De volgorde in het bestand is belangrijk: declareer eerst de MCP-server en zijn tools, creëer daarna de FastAPI-app met de lifespan die de sessiebeheerder start, en mount de server als laatste. Merk op dat de middleware het pad /tasks beschermt, precies waar de MCP-server wordt gemount: deze twee waarden moeten overeenkomen, anders krijgt u entweder een open deur of een afgesloten pad.
# 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)
Twee implementatiedetails verdienen uw aandacht. In create_task wordt de titel ingekort tot 200 tekens en wordt de prioriteit standaard op medium gezet als de ontvangen waarde niet in de toegestane lijst staat: het model stelt soms plausibele maar niet-conforme waarden voor, en de tool moet robuust blijven zonder te crashen. In complete_task en delete_task leidt een onbekende ID niet tot een uitzondering, maar retourneert een JSON-foutbericht: het model kan dit lezen, zijn fout begrijpen en de vraag herformuleren, terwijl een crash dat zou voorkomen.
De server starten en beschikbaar stellen
# Open in een eerste terminal de ngrok-tunnel
ngrok http 8000
# Publieke URL: https://xyz789.ngrok-free.app
# Start in een tweede terminal de server met declaratie van deze hostnaam
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py
Het MCP-eindpunt bevindt zich vervolgens op https://xyz789.ngrok-free.app/tasks/mcp. Let op de samenstelling van dit adres: de door ngrok verstrekte publieke URL, gevolgd door het mount-pad /tasks, en daarna het door de SDK toegevoegde achtervoegsel /mcp. Verwarring over deze concatenatie is de belangrijkste oorzaak van verbindingsfouten.
De client: client_tasks.py
Aan de kant van de client verandert er niets ten opzichte van een lokale server, behalve het type MCP-client en de toevoeging van de authenticatieheader. De agent ontvangt echter instructies die zijn rol in natuurlijke taal beschrijven; dit moedigt hem aan elke actie te bevestigen in plaats van stilletjes opeenvolgende aanroepen te ketenen.
# 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())
De volgorde van de berichten is bewust: het koppelt twee creaties, een leesactie, een update en een hernieuwde leesactie. Dit is het minimale scenario om te verifiëren dat de state behouden blijft van de ene aanroep naar de andere en dat het model de ID kan ophalen van een taak die eerder in het gesprek is gemaakt. Als de vierde instructie mislukt, ligt uw probleem zelden bij de server: het komt meestal doordat het antwoord van list_tasks de ID’s niet duidelijk genoeg zichtbaar maakt.
Testen in Mistral Vibe
Hetzelfde eindpunt kan direct als aangepaste connector worden toegevoegd, wat u een testinterface biedt zonder dat u een client hoeft te schrijven. Dit is ook de beste manier om uw docstrings te valideren: Vibe toont ze letterlijk tijdens de discoverystap, zodat u direct ziet wat het model voor zich krijgt om te beslissen welke tool het moet aanroepen.
- Ga in Vibe naar het tabblad Connectors
- Klik op Add Custom Connector
- Vul bij Name
Task Managerin, bij URLhttps://xyz789.ngrok-free.app/tasks/mcp, kies vervolgens bij Auth: Token en plakmcp-secret-token-2026 - Klik op Connect
Vibe ontdekt vervolgens automatisch de vier tools en u kunt in natuurlijke taal converseren met uw eigen server.
Projectorganisatie en vervolgstappen
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
Dit skelet werkt voor prototyping, maar twee dingen diskwalificeren het voor productie. Het platte teksttoken in de broncode moet verhuizen naar .env, en de ngrok-URL verandert bij elke herstart, waardoor alle geconfigureerde connectors breken. ngrok blijft het ideale hulpmiddel om een idee binnen enkele minuten te valideren; permanente hosting, met zijn opties voor Docker, cloud en Hugging Face Spaces, is het onderwerp van les 12.
Belangrijkste punten
- Een externe server combineert FastAPI (HTTP) +
MCPServer(MCP) + middleware (auth), waarbij de publieke hostnaam wordt gedeclareerd intransport_security - Token-authenticatie verloopt via de header
Authorization: Bearer ... - De client
MCPClientStreamableHTTPaccepteert aangepaste headers voor authenticatie - Dezelfde server is bruikbaar vanuit zowel de Python SDK als Mistral Vibe
- ngrok maakt snelle prototyping mogelijk vóór implementatie in productie