> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-sdk-testing-latest.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Utiliser le serveur MCP de W&B
> Connectez votre IDE ou votre agent d’IA au serveur Model Context Protocol (MCP) de W&B pour interroger et analyser vos données et votre documentation W&B en langage naturel.
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](#w\&b-mcp-server-capabilities).
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.
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é](#use-the-hosted-server)
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](#run-the-mcp-server-locally)
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](mailto:support@wandb.com) 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](https://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 :
```bash theme={null}
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](#troubleshooting). Pour plus d'informations, voir [la documentation MCP de Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp).
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`](https://www.npmjs.com/package/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](https://nodejs.org/) 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 :
```json theme={null}
{
"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](#troubleshooting).
Exportez votre clé API W\&B en tant que variable d'environnement, puis enregistrez le serveur dans Codex :
```bash theme={null}
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](#troubleshooting).
Installez automatiquement le serveur dans Cursor à l'aide du [lien d'installation en un clic](https://cursor.com/en/install-mcp?name=wandb\&config=eyJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3Aud2l0aHdhbmRiLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIge3tXQU5EQl9BUElfS0VZfX0iLCJBY2NlcHQiOiJhcHBsaWNhdGlvbi9qc29uLCB0ZXh0L2V2ZW50LXN0cmVhbSJ9fQ%3D%3D), puis remplacez la valeur de l'espace réservé par votre clé API W\&B dans le champ `Authorization`.
Pour configurer Cursor manuellement :
1. Sur macOS, ouvrez **Cursor** > **Settings** > **Cursor Settings**. Sur Windows ou Linux, ouvrez **Preferences** > **Settings** > **Cursor Settings**.
2. Sélectionnez **Tools and MCP**.
3. Dans **Installed MCP Servers**, sélectionnez **Add Custom MCP**. Cursor ouvre le fichier de configuration `mcp.json`.
4. Ajoutez ce qui suit à l'objet `mcpServers` :
```json theme={null}
{
"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.
6. 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](#troubleshooting). Pour plus d'informations, voir [la documentation MCP de Cursor](https://cursor.com/docs/context/mcp).
Installez l’extension MCP de W\&B :
```bash theme={null}
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](#troubleshooting). Pour plus d'informations, voir [la documentation MCP de Gemini CLI](https://geminicli.com/docs/tools/mcp-server/).
1. Dans LeChat, ouvrez le menu **Intelligence** et sélectionnez **Add Connector**.
2. Sélectionnez **Custom MCP Connector**.
3. 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.
4. Sélectionnez **Create**.
5. 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](#troubleshooting). Pour plus d'informations, voir [la documentation MCP de LeChat](https://mistral.ai/news/le-chat-mcp-connectors-memories).
Ajoutez le serveur dans le champ `tools` de votre appel à l’API OpenAI Responses :
```python theme={null}
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](#run-the-mcp-server-locally).
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 :
```json theme={null}
{
"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](#troubleshooting).
## 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](https://github.com/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`](https://docs.astral.sh/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 :
```bash theme={null}
uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server
```
```bash theme={null}
uv pip install wandb-mcp-server
```
```bash theme={null}
pip install wandb-mcp-server
```
```bash theme={null}
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 :
Enregistrez le serveur local dans Claude Code. Ajoutez `--scope user` pour une configuration globale.
```bash theme={null}
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`.
```json theme={null}
{
"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.
```bash theme={null}
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` :
```json theme={null}
{
"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 :
```json theme={null}
{
"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 :
```bash theme={null}
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 :
```bash theme={null}
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](https://github.com/wandb/wandb-mcp-server#readme).
## 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](https://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](/fr/platform/wb-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](#triage-failing-llm-calls).
### 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](#diagnose-a-bad-training-run) et [Résumer les évaluations et comparer les versions de modèle](#summarize-evals-and-compare-model-versions).
### 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é](/fr/platform/hosting/hosting-options/dedicated-cloud/rate-limits) 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 :
1. `list_entities_tool` pour trouver une entité ou une équipe.
2. `query_wandb_entity_projects` pour trouver le projet.
3. `probe_project_tool` pour les projets basés sur des runs, ou `infer_trace_schema_tool` pour les projets de traces Weave.
4. 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 :
1. `query_weave_traces_tool` avec un filtre sur les champs d’erreur ou d’exception, et `detail_level="summary"`.
2. `resolve_trace_roots_tool` sur la liste de `trace_id` obtenue afin d’associer chaque échec à sa session racine.
3. `query_weave_traces_tool` avec `detail_level="full"` sur un petit nombre de racines spécifiques afin d’approfondir l’analyse.
4. `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 :
1. `get_run_history_tool` pour récupérer les courbes de perte et de validation.
2. `diagnose_run_tool` pour effectuer des vérifications automatisées de convergence, de surapprentissage et de NaN.
3. `compare_runs_tool` par rapport à un run de référence connu pour être correct.
4. `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 :
1. `summarize_evaluation_tool` pour les taux de réussite par Scorer et le nombre d’erreurs.
2. `list_artifact_versions_tool` sur la collection de modèles concernée.
3. `compare_artifact_versions_tool` entre la version candidate et la version de production actuelle.
4. `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](https://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](mailto:support@wandb.com) pour demander l'activation, puis vérifiez l'URL dans [URL de connexion](#connection-url). |
| `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é](/fr/platform/hosting/hosting-options/dedicated-cloud/rate-limits) 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`. |