Utiliser le serveur MCP de W&B - Weights & Biases Documentation

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 :

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

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 :

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.

L’interface intégrée des connecteurs personnalisés de Claude Code Desktop ne prend pas en charge l’authentification par clé API pour les serveurs MCP distants. Pour contourner cette limitation, utilisez le proxy npm mcp-remote pour connecter Claude Code Desktop au serveur MCP distant de W&B. Le proxy s’exécute en local et transfère les requêtes vers https://mcp.withwandb.com/mcp avec votre jeton Bearer.Vous devez avoir Node.js installé sur votre système.Ouvrez votre fichier de configuration Claude Code Desktop dans un éditeur de texte. Vous trouverez le fichier de configuration à l’emplacement suivant selon 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, en remplaçant <your-wandb-api-key> par votre clé API W&B :

{
  "mcpServers": {
    "wandb": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.withwandb.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-wandb-api-key>"
      }
    }
  }
}

La valeur complète de l’en-tête est définie via le champ env, plutôt que directement dans args, afin de contourner un problème lié à l’échappement des espaces dans certaines versions de Claude Desktop.Redémarrez Claude Code Desktop pour activer la nouvelle configuration. Vérifiez la connexion en saisissant le prompt “List the projects in my W&B account.”

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>

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 :

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.
Dans le menu Cursor Settings, sélectionnez Tools and MCP. Le menu Tools s’ouvre.
Dans la section Installed MCP Servers, sélectionnez Add Custom MCP. Le fichier de configuration mcp.json s’ouvre.
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"
      }
    }
  }
}

Redémarrez Cursor pour que les modifications prennent effet.
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.

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

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

Une fois l’extension installée, redémarrez Gemini CLI.
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.

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

Dans le menu Intelligence, sélectionnez Add Connector pour ouvrir la fenêtre Connector.
Sélectionnez l’onglet Custom MCP Connector.
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.
Une fois tous les champs configurés, sélectionnez Create. LeChat ajoute le serveur MCP à votre configuration.
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.

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)

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 :

uv
pip
Installer directement depuis GitHub

uv pip install wandb-mcp-server

pip install wandb-mcp-server

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 :

Claude Code CLI
Claude Code Desktop
Codex
Cursor
VS 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

Ouvrez votre fichier de configuration Claude Code Desktop 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 Code Desktop. Utilisez le chemin complet vers uvx, car sinon Claude Code 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.

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

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"
      }
    }
  }
}

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"
      }
    }
  }
}

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.

Documentation Index

​Capacités du serveur MCP de W&B

​Outils disponibles

​Utiliser le serveur MCP distant de W&B

​Prérequis

​Configurez votre client MCP

​Configurer une version locale du serveur MCP de W&B

​Prérequis

​Installer et configurer le serveur MCP

​Conseils d’utilisation

Capacités du serveur MCP de W&B

Outils disponibles

Utiliser le serveur MCP distant de W&B

Prérequis

Configurez votre client MCP

Configurer une version locale du serveur MCP de W&B

Prérequis

Installer et configurer le serveur MCP

Conseils d’utilisation