Utiliser le serveur MCP de W&B

Connectez votre IDE ou votre agent IA au serveur Model Context Protocol (MCP) de W&B pour accéder aux données et à la documentation de votre Workspace.

Model Context Protocol (MCP) permet à un agent LLM d’interroger et d’analyser efficacement les données afin de réduire le coût en tokens. Cette page explique comment utiliser le serveur MCP de W&B pour interroger et analyser vos données W&B depuis votre IDE ou client MCP, et pour donner à votre client un accès programmatique à la documentation de W&B afin qu’il puisse générer des réponses plus précises aux requêtes liées à W&B.

Il s’intègre nativement à la plupart des IDE, des assistants de code et des agents conversationnels, notamment :

• Cursor
• Visual Studio Code (VS Code)
• Claude Code
• Codex
• Gemini CLI
• Mistral LeChat
• Claude Desktop

Le serveur MCP de W&B est disponible en version hébergée et en version locale. La version hébergée prend uniquement en charge les déploiements W&B Cloud dédié. La version locale prend en charge à la fois les déploiements Cloud dédié et les déploiements Autogéré.

​

Capacités du serveur MCP de W&B

Vous pouvez utiliser le serveur MCP pour analyser des expériences, déboguer des traces, créer des Reports et obtenir de l’aide pour intégrer vos applications aux fonctionnalités de W&B.

Les exemples de prompts suivants illustrent certains types de tâches que votre agent peut effectuer lorsqu’il est connecté au serveur MCP :

• Montre-moi les 5 meilleurs runs par eval/accuracy dans your-team-name/your-project-name ?
• Comment la latence des traces de prédiction de mon agent de recrutement a-t-elle évolué au cours des derniers mois ?
• Génère un rapport wandb comparant les décisions prises par l’agent de recrutement le mois dernier.
• Comment puis-je créer un classement dans Weave - demande à SupportBot ?

​

Outils disponibles

Le serveur MCP de W&B permet à vos agents d’accéder aux outils suivants :

Outil	Description	Exemple de requête
query_wandb_tool	Interroger les runs, les métriques et les expériences W&B	”Affiche les runs avec une perte < 0.1”
query_weave_traces_tool	Analyser les traces et les évaluations de LLM	”Quelle est la latence moyenne ?“
count_weave_traces_tool	Compter les traces et obtenir des métriques de stockage	”Combien de traces ont échoué ?“
create_wandb_report_tool	Créer des Reports W&B de manière programmatique	”Créer un rapport de performances”
query_wandb_entity_projects	Lister les projets d’une entité	”Quels projets existent ?“
query_wandb_support_bot	Obtenir de l’aide via la documentation W&B	”Comment puis-je utiliser Sweeps ?”

​

Utiliser le serveur MCP distant de W&B

W&B met à disposition un serveur MCP hébergé à l’adresse https://mcp.withwandb.com, qui ne nécessite aucune installation. Les instructions suivantes expliquent comment configurer ce serveur hébergé avec différents assistants IA et IDE.

​

Prérequis

• Un déploiement W&B Cloud dédié.
• Une clé API W&B. Vous pouvez en créer une à l’adresse wandb.ai/authorize.
• Définissez votre clé comme variable d’environnement sous le nom WANDB_API_KEY.

​

Configurez votre client MCP

Sélectionnez l’onglet correspondant aux instructions de votre client MCP :

Cursor

Vous pouvez installer automatiquement le serveur W&B dans Cursor à l’aide d’un lien d’installation en un clic (vous devez ajouter Bearer <your-wandb-api-key> dans le champ Authorization), ou l’installer manuellement en suivant les instructions ci-dessous :

1. Sur macOS, ouvrez le menu Cursor, sélectionnez Settings, puis Cursor Settings. Sur Windows ou Linux, ouvrez le menu Preferences, sélectionnez Settings, puis Cursor Settings.
2. Dans le menu Cursor Settings, sélectionnez Tools and MCP. Le menu Tools s’ouvre.
3. Dans la section Installed MCP Servers, sélectionnez Add Custom MCP. Le fichier de configuration mcp.json s’ouvre.
4. Dans le fichier de configuration, ajoutez l’objet wandb suivant à l’objet JSON mcpServers :

{
  "mcpServers": {
    "wandb": {
      "transport": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-wandb-api-key>",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

5. Redémarrez Cursor pour que les modifications prennent effet.
6. Vérifiez que l’agent de chat a accès au serveur MCP de W&B en saisissant l’invite “Liste les Projects de mon compte W&B.”

Pour obtenir des informations plus détaillées, voir la documentation de Cursor.

Claude Code

Pour ajouter le serveur MCP de W&B à Claude Code, mettez à jour l’en-tête Authorization de la commande suivante avec votre clé API W&B, puis exécutez-la dans votre terminal :

claude mcp add --transport http wandb https://mcp.withwandb.com/mcp \
  --header "Authorization: Bearer <your-wandb-api-key>"

Ajoutez --scope user pour une configuration globale, ou omettez-le afin de configurer uniquement le projet en cours.

Pour plus d’informations, voir la documentation de Claude Code.

Codex

Pour ajouter le serveur MCP W&B à Codex, mettez à jour l’argument --bearer-token-env-var de la commande suivante avec la variable d’environnement contenant votre clé API W&B, puis exécutez-la dans votre terminal :

export WANDB_API_KEY=<your-wandb-api-key>
codex mcp add wandb --url https://mcp.withwandb.com/mcp --bearer-token-env-var <your-wandb-api-key-environment-variable>

OpenAI

Pour ajouter le serveur MCP de W&B à vos appels OpenAI, ajoutez les informations du serveur dans le champ tools de la configuration de vos réponses OpenAI :

from openai import OpenAI
import os

client = OpenAI()

resp = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "wandb",
        "server_description": "Query W&B data",
        "server_url": "https://mcp.withwandb.com/mcp",
        "authorization": os.getenv("<your-wandb-api-key>"),
        "require_approval": "never",
    }],
    input="List the projects in my W&B account.",
)

print(resp.output_text)

Gemini CLI

Pour ajouter le serveur MCP W&B à Gemini CLI :

1. Installez l’extension MCP W&B à l’aide d’une seule commande :

   # Installer l’extension
   gemini extensions install https://github.com/wandb/wandb-mcp-server
   

2. Une fois l’extension installée, redémarrez Gemini CLI.

3. Vérifiez que l’agent de chat a accès au serveur MCP W&B en saisissant le prompt “Liste les Projects de mon compte W&B.”

Pour en savoir plus, voir la documentation de Gemini.

Mistral LeChat

Pour ajouter le serveur MCP W&B à Mistral LeChat :

1. Dans le menu Intelligence, sélectionnez Add Connector pour ouvrir la fenêtre Connector.

2. Sélectionnez l’onglet Custom MCP Connector.

3. Configurez les champs avec les valeurs suivantes :

   • Connector Server: https://mcp.withwandb.com/mcp
   • Description: (facultatif) Une courte description libre de la connexion.
   • Authentication Method: Sélectionnez API Token Authentication. Des champs supplémentaires s’affichent.
   • Header name: Conservez la valeur par défaut, Authorization.
   • Header type: Sélectionnez Bearer.
   • Header value: Saisissez votre jeton d’API W&B.

4. Une fois tous les champs configurés, sélectionnez Create. LeChat ajoute le serveur MCP à votre configuration.

5. Vérifiez que l’agent de chat a accès au serveur MCP W&B en saisissant l’invite “Affiche les Projects de mon compte W&B.”

Pour plus d’informations, voir la documentation de LeChat.

​

Configurer une version locale du serveur MCP de W&B

Si vous devez exécuter le serveur MCP de W&B localement pour des déploiements W&B Autogéré, le développement, les tests ou des environnements air-gapped, vous pouvez l’installer et l’exécuter sur votre machine.

​

Prérequis

• Une clé API W&B. Vous pouvez en créer une nouvelle sur wandb.ai/authorize.
• Définissez votre clé en tant que variable d’environnement nommée WANDB_API_KEY.
• Définissez la variable d’environnement WANDB_BASE_URL si vous utilisez W&B Autogéré.
• Python 3.10 ou version ultérieure
• uv (recommandé) ou pip

Voir la documentation de uv pour les instructions d’installation.

​

Installer et configurer le serveur MCP

Pour installer le serveur MCP localement :

Pour installer le serveur MCP de W&B sur votre machine locale, utilisez l’une des commandes d’installation suivantes :

uvbash uv pip install wandb-mcp-server

pipbash pip install wandb-mcp-server

Installer directement depuis GitHubbash pip install git+https://github.com/wandb/wandb-mcp-server

Une fois le serveur MCP installé localement, configurez votre client MCP pour l’utiliser. Sélectionnez un client MCP pour continuer :

Cursor

Ajoutez ce qui suit à votre configuration mcp.json :

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/wandb/wandb-mcp-server", "wandb_mcp_server"],
      "env": {
        "WANDB_API_KEY": "<your-wandb-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

VS Code

Ajoutez ce qui suit à votre .vscode/mcp.json ou à la configuration MCP globale :

{
  "servers": {
    "wandb": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/wandb/wandb-mcp-server", "wandb_mcp_server"],
      "env": {
        "WANDB_API_KEY": "<your-wandb-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

Claude Code

Exécutez la commande suivante dans votre terminal. Ajoutez --scope user pour une configuration globale, ou omettez-le pour ne configurer que le projet actuel.

claude mcp add wandb \
  -e WANDB_API_KEY=your-api-key \
  -e WANDB_BASE_URL=https://your-wandb-instance.example.com \
  -- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

Codex

Exécutez la commande suivante dans votre terminal :

codex mcp add wandb \
  --env WANDB_API_KEY=your_api_key_here \
  --env WANDB_BASE_URL=https://your-wandb-instance.example.com \
  -- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

Claude Desktop

Ouvrez votre fichier de configuration Claude dans un éditeur de texte. Vous trouverez le fichier de configuration aux emplacements correspondant à votre système d’exploitation :

• macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Ajoutez ce qui suit à l’objet JSON de votre fichier de configuration Claude. Utilisez le chemin complet vers uvx, car sinon Claude Desktop risque de ne pas trouver votre installation de uvx.

{
  "mcpServers": {
    "wandb": {
      "command": "/full/path/to/uvx",
      "args": ["--from", "git+https://github.com/wandb/wandb-mcp-server", "wandb_mcp_server"],
      "env": {
        "WANDB_API_KEY": "<your-wandb-api-key>",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

Redémarrez Claude Desktop pour activer la nouvelle configuration.

Pour les clients web ou pour effectuer des tests, exécutez le serveur avec le transport HTTP :

uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 8080

Pour exposer le serveur local à des clients externes tels qu’OpenAI, utilisez ngrok :

uvx wandb_mcp_server --transport http --port 8080

# Dans un autre terminal, exposez avec ngrok
ngrok http 8080
    ```

If you expose the server using `ngrok`, update your MCP client configuration to use the `ngrok` URL.

​

Conseils d’utilisation

• Indiquez le nom de votre projet W&B et de votre entité : Précisez l’entité et le projet W&B dans vos requêtes pour obtenir des résultats précis.
• Évitez les questions trop générales : Au lieu de « quelle est ma meilleure évaluation ? », demandez « quelle évaluation a obtenu le score F1 le plus élevé ? »
• Vérifiez la récupération des données : Lorsque vous posez des questions générales comme « quels sont mes runs les plus performants ? », demandez à l’assistant de confirmer qu’il a récupéré tous les runs disponibles.