"Look at the last 100 traces in my project and explain the most common failures."

Read-only deployment mode: Set WANDB_MCP_ACCESS_MODE=read-only to omit every tool classified as a write, including create_wandb_report_tool, log_analysis_to_wandb, and (in the ARIA profile) aria_send_message. query_wandb_tool is read-only in every mode. Choose either structured SDK parameters (entity_name, project_name, resource, and optional selectors) or legacy query/variables inputs. Structured reads use documented W&B APIs and fixed, application-owned projections where needed to avoid per-result fan-out. GraphQL mode preserves the existing tool name for introspection, unmodeled fields, aliases, or read shapes the structured interface cannot express.

GraphQL compatibility: The legacy mode is available in every supported workload and both access modes; it does not require a new profile or additional permissions. Defaults are max_items=100 and items_per_page=20, further bounded by the active workload's item/page limits, deadline, and response budget. Supply exactly one query operation and do not mix query/variables with structured SDK selectors. Mutations, subscriptions, multiple operations, and mixed-mode inputs are rejected before backend work. The separate query_wandb_graphql_tool remains local-only in the models-weave-graphql-compat profile; that extra tool is not required to use GraphQL through query_wandb_tool. See the query capability matrix.

On the supported W&B service transport, raw and fixed GraphQL responses are checked at 16 MiB before MCP JSON decoding and again after decoding with a 500,000-node structural ceiling. Oversized results return response_too_large. These are MCP processing safeguards after the SDK has received the protobuf envelope; they do not cap network bytes or backend work.

Recommended deployment presets:

Compatibility with v0.3.7: Existing query-only query_wandb_tool calls can keep their query and optional variables arguments. Structured SDK parameters are an additional mode, not a mandatory migration. Use one mode per call and refresh the client's tool definitions when upgrading. Authorization and bounded read safeguards apply to both modes; tool names and profile counts are unchanged.

Run history semantics: for explicit multi-key default-history sampled and ranged collection reads, get_run_history_tool outer-joins requested metric series by _step, falling back to the selected x-axis when _step is absent, so keys logged in separate wandb.log() calls do not disappear. Multi-key ranges use one independent bounded series per metric, in requests of at most eight series. The independent-spec path is designed to cover active/newly synced as well as exported history. Multi-request reads use the same freshly observed upper-step boundary for every batch. A fixed snapshot query reads run identity plus one complete, resume-oriented historyTail row; it avoids loading the full config, summary, system metrics, or history-key index before the bounded history read. samples is the total final-row budget across all requested keys, not a per-key allowance. All observed sparse points in the bounded result are retained when the budget permits. Diagnostics report unobserved_keys when no usable finite/non-null value appears in a bounded/sample result; missing_keys is reported only when absence was checked exactly. A custom x-axis must occur on the same row as its metric because the server does not invent interpolation. non_finite_counts reports NaN or Infinity observations seen in the bounded source; those invalid JSON numeric values are omitted from returned rows, and their counts are exhaustive only when key_counts_exact=true. Exact target_x remains a point lookup rather than an outer-union read. This path uses a fixed application-owned query-only projection, accepts no caller-supplied GraphQL, and is part of every supported managed tool profile.

Weave Agents (OTel) tools — these read the OpenTelemetry/GenAI agent-spans data plane (the Agents tab), which is separate from the classic Weave calls above:

These tools are present in the explicit models-weave-agents and models-weave-agents-aria profiles, and are also retained in the hosted models-weave-agents-agent-lens profile. Dedicated v0.4 rejects all three.

Schema-first workflow: Call infer_trace_schema_tool first to discover fields, then query_weave_traces_tool with precise columns and detail_level:

• "schema" -- structural fields only (fast browsing)
• "summary" -- truncated inputs/outputs (default)
• "full" -- everything untruncated (drill into specific traces)

Chart panels: create_wandb_report_tool accepts a panels parameter for LinePlots, BarPlots, run comparisons, custom Vega charts, and ordered report layouts. Use panel_grid when multiple charts should share one runset, and use heading plus markdown blocks to interleave narrative sections with charts.

Docs search: search_wandb_docs_tool proxies docs.wandb.ai so you get data tools + documentation search from a single MCP connection. Disable with WANDB_MCP_PROXY_DOCS=false if you connect the docs MCP separately.

Docs queries accept up to 64 KiB of UTF-8 text. The proxy makes one request, downloads at most 4 MiB (or the lower configured accumulation limit), and fits returned snippets to the response token budget. Oversized snippets include a truncation notice; upstream errors never echo the query.

The package includes its token-counting vocabulary, so response budgets work without outbound downloads or a writable tokenizer cache.

ARIA tools are explicit and local-only in managed v0.4: select models-weave-agents-aria and configure WB_AGENT_BASE_URL to an approved absolute HTTPS origin. Endpoint presence alone never enables the tools. WANDB_MCP_ACCESS_MODE=read-only omits aria_send_message while retaining the two polling tools. Shared and Dedicated managed profiles reject ARIA.

ARIA polling: ARIA calls are asynchronous. aria_send_message returns a turn handle, and aria_get_turn polls one turn for up to 30 seconds. Use aria_get_turns for several outstanding turns so they are fetched concurrently within one shared polling window. Poll results are compact by default; pass include_turn=true only when a bounded raw service snapshot is needed.

Agent Lens is explicit and hosted-only in managed v0.4.2: W&B-hosted deployments may select models-weave-agents-agent-lens with the shared workload and an operator-reviewed AGENT_LENS_BASE_URL. The default models-weave profile and both Dedicated profiles omit these tools, and merely setting the endpoint never enables them. See the Agent Lens tool guide. The guide also documents the end-to-end request deadline and scoped logging protections for caller-derived identifiers.

Registry organization resolution: Registry tools use the authenticated request's W&B client when organization is omitted. A single accessible organization is selected automatically; callers with access to multiple organizations receive organization_required with a bounded candidate list. Collection listings intentionally return aliases: null and aliases_loaded: false instead of loading every collection's version aliases. Use list_artifact_versions_tool when aliases are needed.

→ Provide your W&B project and entity name LLMs are not mind readers, ensure you specify the W&B Entity and W&B Project to the LLM.

→ Avoid asking overly broad questions Questions such as "what is my best evaluation?" are probably overly broad and you'll get to an answer faster by refining your question to be more specific such as: "what eval had the highest f1 score?"

→ Check result coverage for broad questions Collection and evaluation tools report fields such as total_count, returned_count, has_more, project_exhaustive, sampled, and truncated. For broad questions, ask the client to explain these fields rather than assuming that a bounded result represents the entire project.

• Click on the button above to automatically add the config to Cursor
• Then add your WANDB_API_KEY in the respective field Bearer YOUR_API_KEY and connect

For manual or local installation, see Option 2 below.

from openai import OpenAI
import os

client = OpenAI()

resp = client.responses.create(
 model="gpt-4o",
 tools=[{
     "type": "mcp",
     "server_url": "https://mcp.withwandb.com/mcp",
     "authorization": os.getenv('WANDB_API_KEY'),
     "server_label": "WandB_MCP",
 }],
 input="How many traces are in my project?"
)
print(resp.output_text)

Note: OpenAI's MCP is server-side, so localhost URLs won't work. Use the hosted W&B endpoint or an authenticated Helm deployment.

# run in terminal
claude mcp add --transport http wandb https://mcp.withwandb.com/mcp --scope user --header "Authorization: Bearer <your-api-key-here>"

For local installation, see Option 2 below.

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

For local installation, see Option 2 below.

# Set your API key
export WANDB_API_KEY="your-api-key-here"

# Install the extension
gemini extensions install https://github.com/wandb/wandb-mcp-server

The extension will use the configuration from gemini-extension.json pointing to the hosted server.

For local installation, see Option 2 below.

# Open settings
code ~/.vscode/mcp.json # or global mcp.json file

{
  "servers": {
    "wandb": {
      "type": "http",
      "url": "https://mcp.withwandb.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WANDB_API_KEY"
      }
    }
  }
}

For local installation, see Option 2 below.

Use the Custom MCP Connector flow:

1. Open Le Chat and go to Connectors.
2. Add a custom MCP connector.
3. Set the server URL to https://mcp.withwandb.com/mcp.
4. Select HTTP Bearer Token or API Key authentication.
5. Paste your W&B API key from wandb.ai/authorize.

If the UI asks for a token value, paste the raw W&B API key. If it asks for the full Authorization header value, use Bearer <your-wandb-api-key>.

For a local STDIO connection, add the server to the Claude Desktop configuration. Use the absolute path to uvx if the desktop application cannot resolve your shell PATH.

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop to activate.

The hosted server provides a managed, zero-installation experience. It uses bounded workload profiles, request deadlines, and retryable overload responses to protect W&B while serving multiple users.

Using the Public Server

The easiest way is using our hosted server at https://mcp.withwandb.com/mcp.

Benefits:

• ✅ Zero installation
• ✅ Managed, reviewed release updates
• ✅ Managed workload limits
• ✅ No server maintenance

Simply use the configurations shown in Quick Start.

Run the MCP server locally for development, testing, or when you need direct control over its configuration. The local server runs on your machine with STDIO transport for desktop clients or HTTP transport for web-based clients. It still requires network access to the configured W&B instance and any enabled documentation or telemetry endpoints. See below for client-specific installation.

Running the Server Locally

Quick Start:

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Replace vX.Y.Z with a signed, available release from the release index.
export WANDB_API_KEY="your-api-key"
uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z wandb_mcp_server

📖 For complete command line options and environment variables, see the Command Line Reference in the More Information section.

Manual Configuration

Add to your MCP client config (for detailed client-specific configs see below):

{
  "mcpServers": {
    "wandb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z",
        "wandb_mcp_server"
      ],
      "env": {
        "WANDB_API_KEY": "YOUR_API_KEY",
        "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
      }
    }
  }
}

Cursor

1. Open Cursor Settings (⌘, or Ctrl,)
2. Navigate to Features → Model Context Protocol
3. Click "Install from Registry" or "Add MCP Server"
4. Search for "wandb" or enter:
   • Name: wandb
   • URL: https://mcp.withwandb.com/mcp
   • API Key: Your W&B API key

Manual hosted config in mcp.json:

"wandb": {
  "transport": "http",
  "url": "https://mcp.withwandb.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR-API_KEY",
    "Accept": "application/json, text/event-stream"
  }
}

Manual local (dedicated or on-prem) config in mcp.json:

"wandb": {
  "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z",
      "wandb_mcp_server"
    ],
    "env": {
      "WANDB_API_KEY": "YOUR-API_KEY",
      "WANDB_BASE_URL": "https://your-wandb-instance.example.com"
    }
}

Codex

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@vX.Y.Z wandb_mcp_server

Claude Code

Add --scope user for global config.

claude mcp add wandb -e WANDB_API_KEY=your-api-key -e WANDB_BASE_URL=your-base-url -- uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z wandb_mcp_server

Claude Desktop

Same as above.

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop to activate.

The standalone HTTP entrypoint is intentionally loopback-only and must not be published through ngrok or another tunnel. Use the authenticated hosted wrapper or the operator-wandb Helm deployment for a remotely accessible endpoint.

The package exposes an unauthenticated Streamable HTTP transport only for local development. It requires an explicit acknowledgement and accepts loopback binds only. Use the authenticated hosted wrapper or Helm image for production HTTP.

Running HTTP Server Locally

For lightweight experimentation and testing, you can run the FastMCP HTTP transport directly:

# Basic loopback HTTP server
export MCP_AUTH_DISABLED=true
uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z wandb_mcp_server \
  --transport http \
  --host 127.0.0.1 \
  --port 8080

# With Weave tracing enabled
uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z wandb_mcp_server \
  --transport http \
  --host 127.0.0.1 \
  --port 8080 \
  --weave_entity your-entity \
  --weave_project mcp-server-logs

📖 For all available command line options, see the Command Line Reference in the More Information section.

Note: This entrypoint has no bearer-authentication middleware. It uses the single server-side WANDB_API_KEY and refuses non-loopback binds.

MCP is an optional component in the operator-wandb Helm chart. Before upgrading, confirm that the selected image and chart support the same runtime configuration; changing only one can prevent startup. Use the compatibility and immutable artifact evidence in the applicable versioned release note.

With a compatible chart and image, enable the component in your WeightsAndBiases values:

mcp-server:
  install: true

When enabled, the server becomes accessible at https://<your-instance>/mcp. The chart keeps this public URL for clients and user-facing links while routing server-side W&B API calls to the namespace-local API service.

Requirements:

• A chart version explicitly compatible with MCP 0.4 and a verified image digest.
• A supported tool profile and access mode for the installation.
• Weave installed and configured when using the models-weave profile. The models-only profile does not require Weave.

Client configuration for dedicated instances:

{
  "mcpServers": {
    "wandb": {
      "url": "https://your-instance.wandb.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WANDB_API_KEY"
      }
    }
  }
}

Contact your W&B account team to enable MCP on your dedicated deployment.

from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()

client = OpenAI()

resp = client.responses.create(
    model="gpt-4o",  # Use gpt-4o for larger context window
    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'),
        },
    ],
    input="How many traces are in my-team/my-project?",
)

print(resp.output_text)