Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Exemple complet : serveur distant avec authentification

Lektion 9 av 14 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Scénario : un serveur MCP de gestion de tâches
  2. Le serveur : task_server.py
  3. Lancement et exposition du serveur
  4. Le client : client_tasks.py
  5. Test dans Mistral Vibe
  6. Organisation du projet et prochaines étapes
  7. Viktiga punkter

Mise à jour du 2 novembre 2026 — Le Chat devient Vibe. Depuis le 28 mai 2026, Le Chat a été rebaptisé Vibe (toujours sur chat.mistral.ai) : un agent unique pour le travail et le code, qui conserve vos conversations, paramètres et abonnements. L’expérience historique de Le Chat reste accessible en mode Chat ; en mode Work, les agents sont désormais des compétences (appelées avec @), les mémoires servent de base de connaissances et la recherche approfondie est la compétence Deep Research. Les formules s’appellent désormais Mistral Free, Pro, Team et Enterprise. Cette leçon utilise le nom Vibe ; certains menus décrits ici peuvent avoir changé de nom ou d’emplacement. Addendum du 3 novembre : les résultats de run_async se lisent via result.output_as_text ; le SDK mistralai 3.7.0 ne possède pas d’attribut output.

Mise à jour du 2 novembre 2026 — MCP Python SDK v2. Ce cours suit désormais la version 2 du SDK mcp (2.3.0 au 2 octobre 2026) : MCPServer remplace FastMCP, les paramètres de transport migrent vers run() ou streamable_http_app(), et une application exposée sous un nom d’hôte réel doit déclarer cet hôte (transport_security). C’est aussi la version requise par le SDK Mistral : l’extra mistralai[agents] exige mcp>=2.2.0,<3.0. Sources : Nouveautés de la v2 · Guide de migration · Déploiement et mise à l’échelle.

Scénario : un serveur MCP de gestion de tâches

Les leçons précédentes ont présenté les briques individuelles : transport HTTP, intergiciels et authentification par jeton. Tu vas maintenant les assembler pour former un projet entièrement fonctionnel. Le serveur expose quatre outils de gestion de tâches — création, liste, achèvement, suppression — et le client se connecte à distance en présentant un jeton bearer à chaque requête. Ce même serveur s’exécutera ensuite depuis Vibe sans une seule ligne de code supplémentaire : c’est là tout l’avantage d’un serveur distant par rapport à un serveur STDIO.

Le serveur : task_server.py

Trois éléments coexistent dans ce fichier unique. FastAPI gère le transport HTTP et l’intergiciel d’authentification, MCPServer gère le protocole MCP et les outils, et un dictionnaire Python sert de base de données. L’ordre des déclarations compte : déclare d’abord le serveur MCP et ses outils, puis crée l’application FastAPI avec le cycle de vie (lifespan) qui démarre le gestionnaire de session, et monte enfin le serveur. Note que l’intergiciel protège le chemin /tasks, qui est exactement là où le serveur MCP est monté : ces deux valeurs doivent correspondre, sinon tu te retrouveras soit avec une porte grande ouverte, soit avec un chemin muré.

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

Deux détails d’implémentation méritent ton attention. Dans create_task, le titre est tronqué à 200 caractères et la priorité bascule sur medium si la valeur reçue n’est pas dans la liste autorisée : le modèle propose parfois des valeurs plausibles mais hors contrat, et l’outil doit rester robuste sans planter. Dans complete_task et delete_task, un ID inconnu ne lève pas d’exception mais renvoie un message d’erreur JSON : le modèle peut le lire, comprendre son erreur et reformuler, alors qu’un crash l’en empêcherait.

Lancement et exposition du serveur

# Dans un premier terminal, ouvre le tunnel ngrok
ngrok http 8000
# Public URL: https://xyz789.ngrok-free.app

# Dans un second terminal, lance le serveur en déclarant ce nom d'hôte
MCP_PUBLIC_HOST=xyz789.ngrok-free.app python task_server.py

Le point de terminaison MCP se trouve alors à https://xyz789.ngrok-free.app/tasks/mcp. Note la composition de cette adresse : l’URL publique fournie par ngrok, suivie du chemin de montage /tasks, puis du suffixe /mcp ajouté par le SDK. La confusion autour de cette concaténation est la première cause d’échec de connexion.

Le client : client_tasks.py

Côté client, rien ne change par rapport à un serveur local, si ce n’est le type de client MCP et l’ajout de l’en-tête d’authentification. L’agent reçoit en revanche des instructions qui décrivent son rôle en langage naturel : cela l’incite à confirmer chaque action plutôt qu’à enchaîner silencieusement les appels.

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

La séquence de messages est délibérée : elle enchaîne deux créations, une lecture, une mise à jour et une relecture. C’est le scénario minimal pour vérifier que l’état survit d’un appel à l’autre et que le modèle peut retrouver l’ID d’une tâche créée plus tôt dans la conversation. Si la quatrième instruction échoue, ton problème vient rarement du serveur : il tient généralement au fait que la réponse de list_tasks ne rend pas les IDs assez visibles.

Test dans Mistral Vibe

Le même point de terminaison peut être ajouté directement comme connecteur personnalisé, ce qui te donne une interface de test sans écrire de client. C’est aussi la meilleure façon de valider tes docstrings : Vibe les affiche telles quelles lors de la découverte, tu vois donc immédiatement ce que le modèle aura sous les yeux pour décider quel outil appeler.

  1. Va dans l’onglet Connectors de Vibe
  2. Clique sur Add Custom Connector
  3. Saisis Name : Task Manager, URL : https://xyz789.ngrok-free.app/tasks/mcp, puis choisis Auth : Token et colle mcp-secret-token-2026
  4. Clique sur Connect

Vibe découvre alors automatiquement les quatre outils, et tu peux converser en langage naturel avec ton propre serveur.

Organisation du projet et prochaines étapes

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

Ce squelette fonctionne pour le prototypage, mais deux éléments le disqualifient pour la production. Le jeton en clair dans le code source doit migrer vers .env, et l’URL ngrok change à chaque redémarrage, cassant tous les connecteurs configurés. ngrok reste l’outil idéal pour valider une idée en quelques minutes ; l’hébergement permanent, avec ses options Docker, cloud et Hugging Face Spaces, fait l’objet de la leçon 12.

Viktiga punkter

  • Un serveur distant combine FastAPI (HTTP) + MCPServer (MCP) + intergiciel (auth), avec le nom d’hôte public déclaré dans transport_security
  • L’authentification par jeton passe par l’en-tête Authorization: Bearer ...
  • Le client MCPClientStreamableHTTP accepte des en-têtes personnalisés pour l’authentification
  • Le même serveur est utilisable depuis le SDK Python et depuis Mistral Vibe
  • ngrok permet un prototypage rapide avant le déploiement en production