Passer au contenu principal
Ouvrir dans Colab Le Model Context Protocol (MCP) est un protocole de communication standardisé qui permet aux applications d’IA d’échanger des informations avec de grands modèles de langage (LLM). MCP fournit une interface permettant aux LLM d’accéder à des sources de données et d’interagir avec des outils externes, sans nécessiter d’intégrations personnalisées pour chaque nouveau service. L’intégration Weave vous permet de tracer l’activité entre votre client MCP et votre serveur MCP. Elle vous offre une visibilité détaillée sur les appels d’outils, l’accès aux ressources et la génération de prompts dans les systèmes reposant sur MCP, afin que vous puissiez déboguer, auditer et optimiser vos applications MCP. Ce guide explique le fonctionnement de l’intégration, comment activer le tracing côté serveur et côté client, et présente un exemple complet que vous pouvez exécuter vous-même.

Fonctionnement

L’intégration capture séparément les opérations côté client et côté serveur, mais ne fournit pas de visibilité de bout en bout sur leur interaction. Une proposition en cours vise à ajouter la prise en charge des traces OpenTelemetry à MCP afin de permettre une observabilité de bout en bout. Pour plus d’informations, voir GitHub discussion #269.
L’intégration Weave trace automatiquement les composants clés du Model Context Protocol (MCP) en patchant les méthodes de base avec le décorateur weave.op(). Plus précisément, elle patche des méthodes dans les classes mcp.server.fastmcp.FastMCP et mcp.ClientSession. Grâce à cette intégration, Weave trace les composants MCP suivants : mcp_trace_timeline.png

Utiliser l’intégration

L’intégration Weave fonctionne à la fois avec le serveur MCP et le client. Une fois installée, vous pouvez activer Tracing avec deux lignes de code supplémentaires : l’une pour importer weave, et l’autre pour l’initialiser.

Prérequis

Avant de commencer, installez les paquets requis :
pip install -qq "mcp[cli]" weave

Configuration

Configurez l’intégration MCP à l’aide de la variable d’environnement MCP_TRACE_LIST_OPERATIONS. Définissez cette variable sur true pour activer le Tracing des opérations de liste (list_tools, list_resources et list_prompts) côté serveur et côté client.

Intégration côté serveur

Utilisez cette section si vous développez ou instrumentez un serveur MCP. Pour tracer un serveur MCP, ajoutez deux lignes à votre configuration FastMCP existante : l’une pour importer Weave et l’autre pour initialiser le client. Une fois ces lignes ajoutées, Weave trace automatiquement les opérations d’outil, de ressource et de prompt.
# Importer Weave (requis pour le tracing)
import weave
from mcp.server.fastmcp import FastMCP

# Initialiser Weave avec le nom de votre projet
weave_client = weave.init("my-project")

# Configurer le MCP server
mcp = FastMCP("Demo")

# Définir un outil (cet appel sera tracé)
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

# Définir une ressource (cet appel sera tracé)
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Return a personalized greeting."""
    return f"Hello, {name}!"

# Définir un prompt (cet appel sera tracé)
@mcp.prompt()
def review_code(code: str) -> str:
    """Return a prompt for reviewing code."""
    return f"Please review this code:\n\n{code}"

# Démarrer le serveur
mcp.run(transport="stdio")

Intégration côté client

Utilisez cette section si vous développez ou instrumentez un client MCP. Côté client, le tracing exige également deux changements : importer Weave et l’initialiser. Weave trace automatiquement tous les appels d’outil, les accès aux ressources et les requêtes de prompt.
# Importer Weave (requis pour le tracing)
import weave
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Initialiser Weave avec le nom de votre projet
weave_client = weave.init("my-project")

# Configurer et exécuter le client MCP
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialiser la session
        await session.initialize()
        
        # Appeler un outil (cette opération sera tracée)
        result = await session.call_tool("add", arguments={"a": 1, "b": 2})
        
        # Lire une ressource (cette opération sera tracée)
        resource = await session.read_resource("greeting://user")
        
        # Obtenir un prompt (cette opération sera tracée)
        prompt = await session.get_prompt("review_code", arguments={"code": "print('Hello')"})

Tutoriel : exemple mcp_demo

L’exemple mcp_demo présente une intégration entre le Model Context Protocol (MCP) et Weave pour le Tracing. Il montre comment instrumenter à la fois les composants client et serveur afin de capturer des traces détaillées de leurs interactions. En parcourant ce code, vous pouvez voir les traces des deux côtés d’une application MCP dans l’interface Weave et disposer d’une référence concrète à adapter à vos propres projets.

Exécuter l’exemple

  1. Clonez le dépôt de documentation, puis accédez à l’exemple mcp_demo :
    git clone https://github.com/wandb/docs
    cd docs/weave/examples/mcp_demo
    
    L’exemple comprend deux fichiers principaux :
    • example_server.py : un serveur MCP de démonstration créé avec FastMCP. Il définit des outils, des ressources et des prompts.
    • example_client.py : un client qui se connecte au serveur et interagit avec ses composants.
  2. Installez manuellement les dépendances requises :
    pip install mcp[cli] weave
    
  3. Exécutez la démonstration :
    python example_client.py example_server.py
    
    Cette commande lance à la fois le client et le serveur. Le client démarre un CLI interactif dans lequel vous pouvez tester différentes fonctionnalités.

Commandes CLI du client

L’interface client prend en charge les commandes suivantes :
CommandeDescription
toolsLister les outils disponibles
resourcesLister les ressources disponibles
promptsLister les prompts disponibles
add <a> <b>Additionner deux nombres
bmi <weight> <height>Calculer l’indice de masse corporelle
weather <city>Obtenir les données météo d’une ville
greeting <name>Obtenir une salutation personnalisée
user <id>Récupérer le profil d’un utilisateur
configRécupérer la configuration de l’application
code-review <code>Générer un prompt de revue de code
debug <error>Générer un prompt de débogage
demoExécuter une démo complète de toutes les fonctionnalités disponibles. Exécute chaque fonctionnalité dans l’ordre et produit une chronologie complète des interactions dans la Weave UI.
qQuitter la session

Aperçu de l’exemple

Le serveur example_server.py définit les éléments suivants :
  • Outils : des fonctions comme add(), calculate_bmi(), fetch_weather()
  • Ressources : des endpoints comme greeting://{name}, config://app, users://{id}/profile
  • Prompts : des modèles comme review_code() et debug_error()
Weave trace automatiquement toutes les opérations côté serveur lorsque vous initialisez le client avec weave.init(). Le client example_client.py montre comment :
  • Se connecter à un serveur MCP.
  • Découvrir les outils, les ressources et les prompts disponibles.
  • Appeler des outils avec des paramètres.
  • Lire des données à partir d’URI de ressources.
  • Générer des prompts avec des arguments.
  • Illustrer l’utilisation de weave.op() avec des méthodes et des fonctions personnalisées.
Weave trace tous les appels côté client afin de fournir une vue complète des interactions entre le client et le serveur.

FAQ

La section suivante répond aux questions fréquentes sur l’intérêt du tracing MCP de Weave et sur son utilisation.

Pourquoi le tracing MCP est-il nécessaire ?

En tant que développeur d’applications LLM, vous appartenez à l’une des trois catégories suivantes :
  • Développeur côté serveur MCP : vous souhaitez exposer plusieurs outils, ressources et prompts au client MCP. Vous exposez les outils et les ressources de votre application existante, ou vous avez créé des agents ou disposez de plusieurs agents orchestrés par un agent orchestrateur.
  • Développeur côté client MCP : vous souhaitez connecter votre application côté client à plusieurs serveurs MCP. Une partie essentielle de votre logique côté client consiste à effectuer des appels LLM pour décider quel outil appeler ou quelle ressource récupérer.
  • Développeur serveur et client MCP : vous développez à la fois le serveur et le client.
Si vous appartenez à l’une des deux premières catégories, vous souhaitez savoir quand chaque outil est appelé, à quoi ressemble le flux d’exécution, ainsi que le nombre de tokens et la latence des différents composants de votre logique côté serveur ou côté client. Si vous développez à la fois le serveur et le client, une chronologie unifiée des traces vous aide à itérer sur la logique côté serveur et côté client. Dans tous les cas, une couche d’observabilité vous permet de :
  • Itérer sur votre application.
  • Auditer le flux de travail ou la logique d’exécution.
  • Identifier les goulots d’étranglement.