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

Model Context Protocol (MCP) est une norme ouverte qui permet aux agents d’IA d’appeler des outils externes. Le serveur MCP de W&B donne à votre IDE, à votre assistant de code ou à votre agent conversationnel un accès direct à vos données et à votre documentation W&B. Grâce à cet accès, votre agent peut répondre aux questions sur vos runs, traces, évaluations et artefacts sans avoir à faire de copier-coller. Pour obtenir la liste complète de ce que vous pouvez faire avec le serveur, consultez la section capacités du serveur MCP de W&B. Il s’intègre directement à la plupart des IDE, assistants de code et agents conversationnels, notamment :

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

Types de déploiement

Le serveur MCP de W&B est disponible en deux options de déploiement. Utilisez le serveur hébergé pour la configuration la plus rapide, ou configurez une version locale si vous avez besoin de davantage d’isolation et de flexibilité. La version locale oblige votre client à utiliser une URL différente pour accéder au serveur.

Serveur hébergé (recommandé)

Un serveur MCP géré par W&B, auquel votre client se connecte via HTTP avec votre clé API W&B. Aucune installation ni aucun processus local à maintenir.Utiliser le serveur hébergé

Installation locale

Exécutez le serveur MCP sur votre propre machine via STDIO ou HTTP. À utiliser si vous avez besoin d’un fonctionnement isolé du réseau, de verrouiller une version précise, d’un comportement de serveur personnalisé, d’un développement actif du serveur ou de la prise en charge d’un client qui ne prend en charge que STDIO.Exécuter le serveur MCP en local

Si vous exécutez W&B sur Cloud dédié ou Autogéré et que le serveur MCP hébergé n’est pas encore activé sur votre instance, contactez l’assistance W&B ou votre équipe de compte W&B pour en faire la demande.

Prérequis

Avant de configurer un client, assurez-vous de disposer des éléments suivants :

Créez une clé API W&B sur wandb.ai/authorize.
Définissez cette clé comme variable d’environnement WANDB_API_KEY, ou transmettez-la à votre client sous forme de jeton Bearer.
Pour Cloud dédié, Autogéré et les installations locales sur une instance autre que l’instance par défaut, définissez la variable d’environnement WANDB_BASE_URL sur l’URL de votre instance.

Utiliser le serveur hébergé

W&B gère un serveur MCP pour chaque type de déploiement. Vous n’avez rien à installer. Configurez votre client pour se connecter via HTTP avec une clé API W&B dans l’en-tête Authorization.

URL de connexion

L’URL dépend de votre type de déploiement W&B :

Déploiement	URL du serveur
Cloud mutualisé	`https://mcp.withwandb.com/mcp`
Cloud dédié	`https://[YOUR-INSTANCE]/mcp`
Autogéré	`https://[YOUR-INSTANCE]/mcp`

Pour Cloud dédié ou Autogéré, remplacez https://mcp.withwandb.com/mcp par https://[YOUR-INSTANCE]/mcp et laissez tout le reste inchangé. Les configurations client suivantes utilisent l’URL du Cloud mutualisé.

Enregistrez le serveur MCP W&B dans Claude Code, en remplaçant le jeton Bearer par votre clé API W&B :

claude mcp add --transport http wandb https://mcp.withwandb.com/mcp \
  --header "Authorization: Bearer [YOUR-WANDB-API-KEY]"

Ajoutez --scope user pour configurer Claude Code globalement. Omettez-le pour configurer uniquement le projet en cours.Vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que les éventuelles Teams. Si la connexion échoue, voir Résolution des problèmes. Pour plus d’informations, voir la documentation MCP de Claude Code.

L’interface intégrée de connecteurs personnalisés de Claude 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 afin de connecter Claude Desktop au serveur MCP distant de W&B. Le proxy s’exécute localement et transmet les requêtes à 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 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 d’échappement des espaces dans certaines versions de Claude Desktop.Redémarrez Claude Desktop pour activer la nouvelle configuration. Vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que vos Teams. Si la connexion échoue, voir Dépannage.

Exportez votre clé API W&B en tant que variable d’environnement, puis enregistrez le serveur dans Codex :

export WANDB_API_KEY=[YOUR-WANDB-API-KEY]
codex mcp add wandb \
  --url https://mcp.withwandb.com/mcp \
  --bearer-token-env-var WANDB_API_KEY

Vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que les éventuelles Teams. Si la connexion échoue, voir Résolution des problèmes.

Installez automatiquement le serveur dans Cursor à l’aide du lien d’installation en un clic, puis remplacez la valeur de l’espace réservé par votre clé API W&B dans le champ Authorization.Pour configurer Cursor manuellement :

Sur macOS, ouvrez Cursor > Settings > Cursor Settings. Sur Windows ou Linux, ouvrez Preferences > Settings > Cursor Settings.
Sélectionnez Tools and MCP.
Dans Installed MCP Servers, sélectionnez Add Custom MCP. Cursor ouvre le fichier de configuration mcp.json.

Ajoutez ce qui suit à l’objet 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.
Vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que les équipes auxquelles vous appartenez.

Si la connexion échoue, voir Troubleshooting. Pour plus d’informations, voir la documentation MCP de Cursor.

Installez l’extension MCP de W&B :

gemini extensions install https://github.com/wandb/wandb-mcp-server

Redémarrez Gemini CLI. Vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que les Teams auxquelles vous appartenez.Si la connexion échoue, voir Dépannage. Pour plus d’informations, voir la documentation MCP de Gemini CLI.

Dans LeChat, ouvrez le menu Intelligence et sélectionnez Add Connector.
Sélectionnez Custom MCP Connector.
Configurez les champs suivants :
- Connector Server : https://mcp.withwandb.com/mcp
- Description : (Facultatif) Une courte description.
- Authentication Method : Sélectionnez API Token Authentication.
- Header name : Laissez Authorization.
- Header type : Sélectionnez Bearer.
- Header value : Votre clé API W&B.
Sélectionnez Create.
Vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que les Teams auxquelles vous appartenez.

Si la connexion échoue, voir Troubleshooting. Pour plus d’informations, voir la documentation MCP de LeChat.

Ajoutez le serveur dans le champ tools de votre appel à l’API OpenAI Responses :

import os
from openai import OpenAI

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("WANDB_API_KEY"),
        "require_approval": "never",
    }],
    input="List my W&B entities.",
)

print(resp.output_text)

Transmettez la clé API W&B telle quelle comme valeur de authorization. OpenAI ajoute le préfixe Bearer lorsqu’il appelle le serveur, donc ne l’incluez pas vous-même. L’intégration MCP d’OpenAI s’exécute côté serveur et ne peut donc pas accéder à un serveur MCP local. Pour le développement local, voir Exécuter le serveur MCP localement.

Ouvrez votre fichier mcp.json global ou d’espace de travail (par exemple, ~/.vscode/mcp.json ou .vscode/mcp.json) et ajoutez ce qui suit :

{
  "servers": {
    "wandb": {
      "type": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer [YOUR-WANDB-API-KEY]"
      }
    }
  }
}

Redémarrez VS Code, confirmez que le serveur apparaît dans le panneau MCP et vérifiez la connexion en demandant List my W&B entities. L’agent doit appeler list_entities_tool et renvoyer votre nom d’utilisateur ainsi que toutes les équipes auxquelles vous appartenez.Si la connexion échoue, consultez Résolution des problèmes.

Exécuter le serveur MCP en local

Une installation locale est une alternative au serveur hébergé, et non l’option par défaut pour aucun type de déploiement. Utilisez-la lorsque le serveur hébergé ne convient pas à votre environnement. Raisons courantes d’exécuter le serveur en local :

Environnements isolés du réseau ou hors ligne où votre client ne peut pas atteindre un point de terminaison W&B hébergé.
Version épinglée. Le serveur hébergé suit la branche principale. Une installation locale permet d’épingler une balise de version spécifique.
Comportement personnalisé du serveur, comme modifier les descriptions des outils, ajouter des outils ou définir un budget de jetons de réponse différent de la valeur par défaut.
Développement actif sur le serveur lui-même.
Clients STDIO uniquement ou clients nécessitant un processus local.

Pour les utilisateurs de Cloud dédié ou Autogéré, privilégiez la solution hébergée. Utilisez une installation locale depuis wandb/wandb-mcp-server uniquement si le serveur hébergé n’est pas encore activé sur votre instance ou si l’une des raisons précédentes s’applique. Définissez la variable d’environnement WANDB_BASE_URL avec l’URL de votre instance.

Prérequis locaux

Pour exécuter le serveur en local, assurez-vous de disposer des éléments suivants :

Python 3.11 ou version ultérieure.
uv ou pip.
Une clé API W&B, définie dans WANDB_API_KEY.
WANDB_BASE_URL défini sur l’URL de votre instance si vous utilisez Cloud dédié ou Autogéré.

Installer le serveur

Choisissez une méthode d’installation et exécutez la commande suivante pour installer le serveur MCP :

uvx (sans installation permanente)
uv
pip
Installer depuis GitHub

uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server

uv pip install wandb-mcp-server

pip install wandb-mcp-server

pip install git+https://github.com/wandb/wandb-mcp-server

Configurez votre client

Après avoir installé le serveur, configurez votre client pour le lancer. Sélectionnez votre client MCP, puis exécutez la configuration suivante en remplaçant [YOUR-WANDB-API-KEY] par votre clé API W&B si nécessaire :

Claude Code
Claude Desktop
Codex
Cursor
VS Code

Enregistrez le serveur local dans Claude Code. Ajoutez --scope user pour une configuration globale.

claude mcp add wandb \
  -e WANDB_API_KEY=[YOUR-WANDB-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 Desktop :

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

Ajoutez le JSON suivant. Utilisez le chemin complet vers uvx, car sinon Claude Desktop risque de ne pas le trouver dans votre PATH.

{
  "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 appliquer la configuration.

codex mcp add wandb \
  --env WANDB_API_KEY=[YOUR-WANDB-API-KEY] \
  --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"
      }
    }
  }
}

Omettez WANDB_BASE_URL pour utiliser le point de terminaison API W&B par défaut.

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

Exécutez le serveur avec le transport HTTP

Pour les clients web et 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 un serveur local à des clients externes, tels que l’API OpenAI Responses, utilisez un tunnel :

uvx wandb_mcp_server --transport http --port 8080

# Dans un autre terminal
ngrok http 8080

Mettez à jour la configuration de votre client MCP pour utiliser l’URL du tunnel.

Variables d’environnement

Les variables d’environnement suivantes contrôlent l’authentification, le routage de l’instance et le comportement du serveur pour les installations locales. Définissez-les dans le bloc env de votre client ou exportez-les dans votre shell.

Variable	Description
`WANDB_API_KEY`	Clé API W&B pour l’authentification. Requise.
`WANDB_BASE_URL`	URL personnalisée de l’instance W&B pour Cloud dédié ou Autogéré. Valeur par défaut : `https://api.wandb.ai`.
`WANDB_MCP_PROXY_DOCS`	Active le proxy de recherche dans la documentation `search_wandb_docs_tool`. Valeur par défaut : `true`.
`WANDBOT_BASE_URL`	Point de terminaison personnalisé pour le proxy de recherche dans la documentation.
`MAX_RESPONSE_TOKENS`	Budget de jetons pour la troncature des réponses des outils. Valeur par défaut : `30000`.
`MCP_SERVER_LOG_LEVEL`	Niveau de verbosité de la journalisation. Valeurs possibles : `DEBUG`, `INFO`, `WARNING`, `ERROR`.

Pour la référence complète de la ligne de commande et les options avancées, voir le README de wandb-mcp-server.

Capacités du serveur MCP de W&B

Utilisez le serveur MCP pour analyser des Experiments, déboguer des traces, créer des Reports, gérer le registre et les artefacts, et répondre à des questions sur la documentation W&B. Les prompts d’exemple suivants illustrent certaines des tâches que vous pouvez demander à votre agent d’effectuer lorsqu’il est connecté au serveur MCP de W&B :

“Montrez-moi les 5 meilleurs runs selon eval/accuracy dans your-team/your-project.”
“Comment la latence des traces de prédiction de mon agent de recrutement a-t-elle évolué au cours du dernier mois ?”
“Générez un Report W&B comparant les décisions prises par l’agent de recrutement la semaine dernière.”
“Quelles versions de l’artefact production-model existent, et quelles modifications ont été apportées entre v2 et v3 ?”
“Comment puis-je créer un classement dans Weave ?”

Outils disponibles

Le serveur propose plusieurs outils regroupés par usage. Le tableau suivant répertorie le nom de chaque outil, à quel moment l’agent doit l’utiliser, ainsi qu’un prompt concret que vous pouvez utiliser pour invoquer cet outil.

Des outils qui vous aident à identifier les noms de projet et d’entité, et à inspecter les schémas.

Tool	Use when	Example prompt
`list_entities_tool`	Aucune entité n’est spécifiée, ou pour énumérer les équipes et comptes auxquels la clé API peut accéder.	”À quelles équipes W&B ai-je accès ?”
`query_wandb_entity_projects`	L’entité est connue, mais pas le nom du projet, ou une requête précédente a échoué avec “project not found”.	”Liste tous les projets de `your-team`.”
`probe_project_tool`	Pour découvrir les métriques disponibles, les clés de configuration et les tags dans un projet basé sur des runs que vous ne connaissez pas.	”Analyse `your-team/your-project` et dites-moi quelles métriques sont enregistrées.”
`infer_trace_schema_tool`	Pour découvrir les noms de champs, les types et des exemples de valeurs dans un projet de traces Weave que vous ne connaissez pas avant d’exécuter une requête.	”Quels champs figurent dans les traces Weave de `your-team/your-project` ?”

Outils qui interrogent, comparent et diagnostiquent les runs de W&B Models.

Tool	Use when	Example prompt
`query_wandb_tool`	La question porte sur des runs, des sweeps, des configurations, des résumés ou des artefacts dans W&B Models. Exécute une requête GraphQL.	”Montrez-moi les 5 meilleurs runs selon `eval/accuracy` dans `your-team/your-project`.”
`get_run_history_tool`	La question porte sur les courbes d’entraînement, les tendances des métriques au fil du temps, ou toute série temporelle enregistrée pour un run.	”Tracez la courbe de perte du run `abc123` dans `your-team/your-project`.”
`compare_runs_tool`	La question porte sur les modifications entre deux runs, ou sur lequel des deux est le meilleur. Renvoie la différence de configuration, l’écart des métriques et, facultativement, l’historique aligné.	”Comparez les runs `abc123` et `def456` dans `your-team/your-project`.”
`diagnose_run_tool`	La question porte sur le fait de savoir si un run a convergé, est en surapprentissage ou a produit des valeurs NaN. Renvoie des recommandations spécifiques.	”Le run `abc123` dans `your-team/your-project` est-il en surapprentissage ?”

Outils permettant d’interroger et d’agréger les traces et les évaluations de LLM.

Tool	Use when	Example prompt
`query_weave_traces_tool`	Les Données de trace sont requises (appels LLM, évaluations, exécutions d’agent). Commencez par `detail_level="summary"` et ne passez à `"full"` que pour des traces spécifiques.	”Montrez-moi les traces ayant échoué dans `your-team/your-project` au cours des dernières 24 heures.”
`count_weave_traces_tool`	La question porte sur le nombre de traces ou d’erreurs, et les Données de trace elles-mêmes ne sont pas nécessaires.	”Combien de traces ont échoué dans `your-team/your-project` cette semaine ?”
`resolve_trace_roots_tool`	Après que `query_weave_traces_tool` a trouvé des traces enfants, pour rattacher chacune à sa session ou à son flux de travail racine en un seul appel groupé.	”Trouvez les appels LLM qui contiennent `rate limit` et indiquez-moi à quelles sessions ils appartiennent.”
`summarize_evaluation_tool`	La question porte sur la manière dont une évaluation s’est déroulée, sur le taux de réussite ou sur les tâches qui échouent le plus souvent. Agrège les hiérarchies `Evaluation.evaluate`.	”Résumez l’évaluation la plus récente dans `your-team/your-project`.”

Outils qui enregistrent les analyses dans W&B.

Tool	Use when	Example prompt
`create_wandb_report_tool`	Une requête explicite permettant de créer un report ou d’enregistrer des résultats. Accepte du Markdown ainsi qu’un tableau `panels` pour les graphiques en courbes, les graphiques à barres et les comparaisons de runs.	”Créer un report W&B comparant les runs `abc123` et `def456`.”
`log_analysis_to_wandb`	Les valeurs calculées dans la session MCP (distributions de latence, ventilation des erreurs) doivent être enregistrées comme un run avant d’être utilisées dans un report.	”Enregistrez ces percentiles de latence dans W&B comme un run d’analyse.”

Outils qui vous permettent d’inspecter et de comparer des modèles, des Datasets et d’autres artefacts versionnés.

Tool	Use when	Example prompt
`list_registries_tool`	La question porte sur les registres de modèles, les Registered Models ou les Datasets enregistrés dans une organisation.	”Quels registres existent dans `your-org` ?”
`list_registry_collections_tool`	Pour voir quels modèles ou Datasets se trouvent dans un registre donné.	”Quelles collections se trouvent dans le registre `model` de `your-org` ?”
`list_artifact_versions_tool`	Pour lister les versions disponibles d’un modèle, d’un dataset ou d’une autre collection d’artefacts.	”Listez les versions de `production-model` dans `your-team/your-project`.”
`get_artifact_details_tool`	Pour examiner une version précise d’un artefact, y compris sa traçabilité et ses fichiers.	”Que contient `production-model:v3` ?”
`compare_artifact_versions_tool`	La question porte sur les modifications entre deux versions d’un artefact.	”Comparez `production-model:v2` et `production-model:v3`.”

Outils qui répondent à des questions sur les produits à partir de la documentation officielle de W&B.

Outil	À utiliser lorsque	Exemple de prompt
`search_wandb_docs_tool`	La question porte sur l’utilisation d’une fonctionnalité ou d’une API de W&B ou Weave. Agit comme proxy pour docs.wandb.ai.	”Comment puis-je créer un tableau de classement dans Weave ?”

Requêtes de traces axées sur le schéma

Pour les requêtes de traces Weave, appelez d’abord infer_trace_schema_tool pour identifier les champs disponibles, puis appelez query_weave_traces_tool avec une liste précise de colonnes et detail_level :

`detail_level`	Renvoie	À utiliser lorsque
`schema`	Champs structurels uniquement. Le plus rapide.	Pour parcourir ou compter.
`summary`	Entrées et sorties tronquées. Par défaut.	Pour la plupart des tâches d’analyse.
`full`	Tout, sans troncature.	Pour examiner en détail un petit nombre de traces spécifiques.

Cette approche limite l’utilisation des jetons pour les questions générales et permet à l’agent de passer à full uniquement pour les traces pertinentes.

Conseils d’utilisation

Les sections suivantes décrivent des pratiques et des flux de travail qui vous aideront à obtenir de meilleurs résultats avec le serveur MCP de W&B. Commencez par les pratiques générales, puis lisez la section qui correspond à votre charge de travail pour obtenir des conseils plus précis et des enchaînements d’outils en plusieurs étapes.

Bonnes pratiques générales

Suivez ces pratiques, quel que soit votre cas d’utilisation :

Spécifiez l’entité et le projet. Les outils MCP nécessitent une entité explicite (votre équipe ou votre compte personnel) et un nom de projet. Indiquez les deux dans каждой question, par exemple « dans your-team/your-project ».
Posez des questions ciblées. Préférez « Quelle évaluation a obtenu le score F1 le plus élevé ? » à « Quelle est ma meilleure évaluation ? ». Des métriques et des plages de temps précises produisent de meilleurs appels d’outils.
Vérifiez la récupération complète. Pour les questions larges telles que « Quels sont mes runs les plus performants ? », demandez à l’agent de confirmer qu’il a récupéré tous les runs disponibles, et pas seulement les plus récents.
Combinez avec W&B Skills. W&B Skills montrent aux agents de code comment structurer les flux de travail W&B. Skills fournit des modèles et MCP fournit l’accès aux données ; les deux fonctionnent bien ensemble.

Pour les flux de travail avec de nombreuses traces

Suivez ces bonnes pratiques lorsque vous travaillez avec les traces Weave :

Commencez par le schéma. Appelez infer_trace_schema_tool avant query_weave_traces_tool pour fournir à l’agent les champs et les valeurs de filtre valides.
Choisissez le bon detail_level. Utilisez schema pour explorer, summary (par défaut) pour l’analyse, et full uniquement lorsque vous examinez en détail un petit nombre de traces spécifiques.
Enchaînez avec resolve_trace_roots_tool. Après une requête sur des traces enfants, transmettez la liste de trace_id obtenue à resolve_trace_roots_tool pour associer chaque trace à sa session racine en un seul appel groupé.
Privilégiez summarize_evaluation_tool pour les évaluations. Il agrège automatiquement la hiérarchie Evaluation.evaluate et predict_and_score. Ne revenez à query_weave_traces_tool que pour les données de trace brutes.

Pour un flux de travail de bout en bout, voir analyser les appels LLM en échec.

Pour les flux de travail comportant beaucoup de runs

Suivez ces pratiques lorsque vous travaillez avec des runs W&B Models :

Sondez avant d’interroger. Appelez probe_project_tool sur un projet centré sur les runs que vous ne connaissez pas encore afin d’identifier les clés de métriques, les clés de configuration et les tags avant de construire votre requête GraphQL.
Utilisez get_run_history_tool pour les séries chronologiques. GraphQL n’échantillonne pas. Pour les courbes de perte et les autres données de séries chronologiques, get_run_history_tool est donc à la fois plus rapide et moins coûteux.
Laissez compare_runs_tool calculer les écarts. Il renvoie les écarts de configuration et de métriques avec un historique aligné en un appel unique, ce qui évite une comparaison manuelle.
Commencez par un contrôle de santé. Lorsqu’un run d’entraînement semble anormal, appelez diagnose_run_tool avant d’examiner manuellement l’historique.

Pour les flux de travail de bout en bout, Voir Diagnostiquer un run d’entraînement défaillant et Résumer les évaluations et comparer les versions de modèle.

Pour Cloud dédié et Autogéré

Suivez ces pratiques pour les déploiements non multilocataires :

Préférez le serveur hébergé sur votre instance, à l’adresse https://[YOUR-INSTANCE]/mcp. Il expose les mêmes outils que le serveur multilocataire, sans nécessiter de WANDB_BASE_URL côté client. Ne recourez à une installation locale que si le serveur hébergé n’est pas encore activé.
Si vous l’exécutez localement sur votre instance, définissez WANDB_BASE_URL avec l’URL de votre instance dans le bloc env du client. Sans cela, le serveur cible api.wandb.ai et ne renvoie aucune donnée.
Les limites de débit sur Cloud dédié sont distinctes de celles du mode multilocataire. Voir les limites de débit du Cloud dédié pour connaître les valeurs par défaut et savoir comment demander des modifications.

Pour les installations en local

Suivez ces bonnes pratiques lorsque vous exécutez le serveur sur votre propre machine :

Privilégiez le transport STDIO pour les clients de bureau (Cursor, VS Code, Claude Code, Claude Desktop). Ne passez au transport HTTP que si un client l’exige explicitement (par exemple, l’API OpenAI Responses).
Lorsque les appels d’outil échouent silencieusement, définissez MCP_SERVER_LOG_LEVEL=DEBUG dans le bloc env du client, puis vérifiez à nouveau les journaux MCP du client.
Si vous installez depuis GitHub (uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server), uvx utilise la branche par défaut. Pour utiliser une version stable, spécifiez un tag explicite en ajoutant @v0.3.2 à l’URL Git.

Flux de travail recommandés

La plupart des questions concrètes nécessitent plus d’un outil. Les flux de travail suivants présentent des enchaînements d’outils courants en plusieurs étapes que vous pouvez demander à votre agent d’exécuter.

Explorer un projet inconnu

Pour explorer ce qui a été enregistré dans un projet, enchaînez ces outils :

list_entities_tool pour trouver une entité ou une équipe.
query_wandb_entity_projects pour trouver le projet.
probe_project_tool pour les projets basés sur des runs, ou infer_trace_schema_tool pour les projets de traces Weave.
Un appel ciblé à query_wandb_tool ou query_weave_traces_tool à l’aide des clés identifiées.

Analyser les appels LLM en échec

Pour trouver les traces problématiques et les sessions qui les ont produites, utilisez ces outils dans l’ordre suivant :

query_weave_traces_tool avec un filtre sur les champs d’erreur ou d’exception, et detail_level="summary".
resolve_trace_roots_tool sur la liste de trace_id obtenue afin d’associer chaque échec à sa session racine.
query_weave_traces_tool avec detail_level="full" sur un petit nombre de racines spécifiques afin d’approfondir l’analyse.
create_wandb_report_tool pour documenter les résultats.

Diagnostiquer un run d’entraînement défaillant

Pour exécuter un contrôle de santé sur un run d’entraînement suspect, enchaînez les outils suivants :

get_run_history_tool pour récupérer les courbes de perte et de validation.
diagnose_run_tool pour effectuer des vérifications automatisées de convergence, de surapprentissage et de NaN.
compare_runs_tool par rapport à un run de référence connu pour être correct.
create_wandb_report_tool avec des panneaux de graphiques linéaires pour partager le diagnostic.

Résumer les évaluations et comparer les versions du modèle

Pour trouver quelle version du modèle a donné les meilleurs résultats lors d’une évaluation, enchaînez ces outils :

summarize_evaluation_tool pour les taux de réussite par Scorer et le nombre d’erreurs.
list_artifact_versions_tool sur la collection de modèles concernée.
compare_artifact_versions_tool entre la version candidate et la version de production actuelle.
log_analysis_to_wandb et create_wandb_report_tool pour publier la comparaison.

Dépannage

Utilisez le tableau suivant pour vous aider à diagnostiquer et à résoudre les problèmes liés au serveur MCP de W&B :

Symptôme	Cause et correctif
`401 Unauthorized` ou `Invalid API key`	Votre clé API W&B est absente, mal formée ou n’est pas autorisée pour l’entité ou l’équipe cible. Générez une nouvelle clé sur wandb.ai/authorize et vérifiez qu’elle est transmise sous forme de jeton Bearer ou définie dans `WANDB_API_KEY`.
Résultats vides pour des requêtes qui devraient aboutir	Le nom de l’équipe, de l’entité ou du projet est incorrect, ou la clé API ne dispose pas de l’accès nécessaire. Vérifiez les deux avec l’agent, puis réessayez.
`404 Not Found` ou `connection refused` sur `https://[YOUR-INSTANCE]/mcp`	Le serveur MCP hébergé n’est pas encore activé sur votre instance Cloud dédié ou Autogéré, ou le client pointe vers une URL incorrecte. Contactez l’assistance W&B pour demander l’activation, puis vérifiez l’URL dans URL de connexion.
`429 Too Many Requests` sur Cloud dédié	Vous avez atteint les limites de débit de votre instance. Voir limites de débit du Cloud dédié pour savoir comment demander des limites plus élevées.
Le serveur local ne parvient pas à trouver `uvx` dans Claude Desktop	Utilisez le chemin complet vers `uvx` dans le champ `command` de `claude_desktop_config.json`.

Documentation Index

​Types de déploiement

Serveur hébergé (recommandé)

Installation locale

​Prérequis

​Utiliser le serveur hébergé

​URL de connexion

​Exécuter le serveur MCP en local

​Prérequis locaux

​Installer le serveur

​Configurez votre client

​Exécutez le serveur avec le transport HTTP

​Variables d’environnement

​Capacités du serveur MCP de W&B

​Outils disponibles

​Requêtes de traces axées sur le schéma

​Conseils d’utilisation

​Bonnes pratiques générales

​Pour les flux de travail avec de nombreuses traces

​Pour les flux de travail comportant beaucoup de runs

​Pour Cloud dédié et Autogéré

​Pour les installations en local

​Flux de travail recommandés

​Explorer un projet inconnu

​Analyser les appels LLM en échec

​Diagnostiquer un run d’entraînement défaillant

​Résumer les évaluations et comparer les versions du modèle

​Dépannage

Types de déploiement

Prérequis

Utiliser le serveur hébergé

URL de connexion

Exécuter le serveur MCP en local

Prérequis locaux

Installer le serveur

Configurez votre client

Exécutez le serveur avec le transport HTTP

Variables d’environnement

Capacités du serveur MCP de W&B

Outils disponibles

Requêtes de traces axées sur le schéma

Conseils d’utilisation

Bonnes pratiques générales

Pour les flux de travail avec de nombreuses traces

Pour les flux de travail comportant beaucoup de runs

Pour Cloud dédié et Autogéré

Pour les installations en local

Flux de travail recommandés

Explorer un projet inconnu

Analyser les appels LLM en échec

Diagnostiquer un run d’entraînement défaillant

Résumer les évaluations et comparer les versions du modèle

Dépannage