Le sampling

Mise à jour du 2 novembre 2026 — sampling. La spécification MCP 2026-07-28 déprécie le Sampling. Il fonctionne encore pendant la période de dépréciation, mais la recommandation officielle pour une nouvelle implémentation est d’appeler directement l’API du fournisseur de modèle depuis le serveur. Ce que vous apprenez ici reste utile pour maintenir des serveurs existants. Dans le SDK Python v2, la forme recommandée est un résolveur : une fonction renvoie Sample(messages, max_tokens=...) et l’outil reçoit le CreateMessageResult par un paramètre annoté Annotated[CreateMessageResult, Resolve(fonction)] ; ctx.session.create_message(...), utilisé dans ce cours, existe encore mais ne fonctionne que sur les connexions de l’ère 2025 et lève un avertissement de dépréciation. Source : Sampling and roots (SDK Python v2).

Le sampling permet à un serveur MCP d’accéder à un modèle de langage comme Claude via le client MCP connecté. Au lieu que le serveur appelle directement Claude, il demande au client de faire l’appel en son nom. Cela transfère la responsabilité et le coût de la génération de texte du serveur vers le client. À la fin de cette leçon, vous saurez quand le sampling se justifie, comment il s’implémente des deux côtés, et ce qu’en fait la version 2026-07-28 du protocole.

Le problème que résout le sampling

Imaginez que vous avez un serveur MCP avec un outil de recherche qui récupère des informations depuis Wikipedia. Après avoir rassemblé toutes ces données, vous devez les résumer en un rapport cohérent. Vous avez deux options :

Option 1 : Donner au serveur MCP un accès direct à Claude. Le serveur aurait besoin de sa propre clé API, de gérer l’authentification, les coûts, et d’implémenter tout le code d’intégration Claude. Ça fonctionne mais ajoute une complexité significative.

Option 2 : Utiliser le sampling. Le serveur génère un prompt et demande au client : “Peux-tu appeler Claude pour moi ?” Le client, qui a déjà une connexion à Claude, fait l’appel et retourne les résultats.

Comment fonctionne le sampling

Le flux est simple :

1. Le serveur complète son travail (ex: récupère des articles Wikipedia)
2. Le serveur crée un prompt demandant la génération de texte
3. Le serveur envoie une requête de sampling au client
4. Le client appelle Claude avec le prompt fourni
5. Le client retourne le texte généré au serveur
6. Le serveur utilise le texte généré dans sa réponse

Implémentation

Côté serveur

Dans votre fonction d’outil, utilisez create_message pour demander la génération de texte :

@mcp.tool()
async def summarize(text_to_summarize: str, ctx: Context):
    prompt = f"""
    Veuillez résumer le texte suivant :
    {text_to_summarize}
    """
    
    result = await ctx.session.create_message(
        messages=[
            SamplingMessage(
                role="user",
                content=TextContent(
                    type="text",
                    text=prompt
                )
            )
        ],
        max_tokens=4000,
        system_prompt="You are a helpful research assistant",
    )
    
    if result.content.type == "text":
        return result.content.text
    else:
        raise ValueError("Sampling failed")

Côté client

Créez un callback de sampling qui gère les requêtes du serveur :

async def sampling_callback(
    context: RequestContext, params: CreateMessageRequestParams
):
    # Appeler Claude via le SDK Anthropic
    text = await chat(params.messages)
    
    return CreateMessageResult(
        role="assistant",
        model=model,
        content=TextContent(type="text", text=text),
    )

Passez ensuite ce callback lors de l’initialisation de votre session client :

async with ClientSession(
    read,
    write,
    sampling_callback=sampling_callback
) as session:
    await session.initialize()

Avantages du sampling

Quand utiliser le sampling

Le sampling est plus précieux quand vous construisez des serveurs MCP accessibles publiquement. Vous ne voulez pas que des utilisateurs aléatoires génèrent du texte illimité à vos frais. En utilisant le sampling, chaque client paie pour sa propre utilisation de l’IA tout en bénéficiant des fonctionnalités de votre serveur.

La technique déplace essentiellement la complexité de l’intégration IA de votre serveur vers le client, qui a souvent déjà les connexions et credentials nécessaires en place. Depuis la version 2026-07-28, le registre officiel des dépréciations indique le chemin de migration : intégrer directement l’API du fournisseur de modèle depuis le serveur. Autrement dit, le sampling reste la bonne lecture d’un serveur public existant, et l’appel direct à l’API (ou le résolveur du SDK v2) la bonne réponse pour un nouveau.

À vous de jouer

1. Listez les outils de votre serveur qui produisent du texte « rédigé » (résumé, reformulation, classification) : ce sont les candidats au sampling.
2. Pour chacun, répondez : qui doit payer les tokens, et le serveur doit-il connaître une clé d’API ? Si la réponse est « le client » et « non », le sampling (ou son équivalent v2) s’impose.
3. Sur un projet neuf, écrivez la version « appel direct de l’API Anthropic » du même outil, et comparez la surface de configuration (clé, coûts, dépendances).

Sources officielles : Sampling (Claude Academy) · Sampling (spécification 2026-07-28, déprécié) · Registre des dépréciations · Sampling and roots (SDK Python v2)

Points clés à retenir

• Le sampling : le serveur demande au client d’appeler le modèle à sa place ; le client paie et détient la clé, le serveur reste sans secret.
• Côté serveur, ctx.session.create_message(messages, max_tokens, system_prompt) ; côté client, un sampling_callback passé à ClientSession.
• Idéal pour les serveurs publics existants ; déprécié en 2026-07-28, où le chemin recommandé est l’intégration directe de l’API du modèle.
• En SDK v2, la forme équivalente est un résolveur Resolve(fonction) renvoyant Sample(...).