W&B MCP Server

Query and analyze your Weights & Biases data using natural language through the Model Context Protocol.

---

What's new in 0.4

• Structured experiment queries and legacy GraphQL inputs work through the same query_wandb_tool interface.
• Targeted summary/config reads and sparse multi-key history make it easier to work with large experiments without loading every field.
• Explicit tool profiles, read-only mode, and bounded responses let you choose the capabilities appropriate for your installation.
• HTTP session recovery, input validation, and offline token counting are more robust. Tool telemetry excludes raw arguments and API keys; see the privacy guidance before enabling verbose logging.

The current 0.4.3 candidate restores W&B username attribution in analytics, adds the optional DOCS_MCP_URL override for self-hosted docs search, keeps every tool description under 4,000 characters with ARIA's query and counting rules folded in, and requires mcp 1.30.0 or newer. See the v0.4.3 release note for its current qualification state and the release index for earlier 0.4 versions.

Release availability

Public source, W&B-hosted images, customer images, and installation artifacts advance independently. Use only immutable evidence recorded in the release index; a version string or mutable container tag does not prove that another channel is available or qualified.

What Can This Server Do?

Analyze Experiments	Debug Traces	Create Reports	Get Help
Show me the top 5 runs by eval/accuracy in my-team/my-project.	How has my agent's latency changed this month?	Create a W&B report comparing these runs.	Search the W&B docs for how to create a leaderboard in Weave.

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

Tool	Description	Example Query
infer_trace_schema_tool	Discover field names, types, and sample values	"What fields are in my traces?"
query_weave_traces_tool	Analyze LLM traces with detail_level control	"Show failed traces with full data"
count_weave_traces_tool	Count traces and get storage metrics	"How many traces failed?"
resolve_trace_roots_tool	Resolve spans to their root traces	"Find the root traces for these calls"
query_wandb_tool	Use structured W&B reads or a bounded, query-only GraphQL document	"Show me runs with loss < 0.1"
probe_project_tool	Discover useful project fields and bounded samples	"What metrics and config fields are available?"
get_run_history_tool	Bounded time-series data with sparse, multi-key outer-union sampling	"Show loss and validation-loss curves for run abc123"
compare_runs_tool	Compare selected metrics and configuration across runs	"Compare these three training runs"
diagnose_run_tool	Diagnose a run using bounded metadata and history reads	"Why did this run diverge?"
summarize_evaluation_tool	Summarize bounded evaluation results with coverage metadata	"Summarize this evaluation"
create_wandb_report_tool	Create reports with markdown, charts, and panels	"Create a report with loss plots"
log_analysis_to_wandb	Log analysis metrics to W&B as a run	"Log these latency stats to W&B"
search_wandb_docs_tool	Search official W&B documentation	"How do I create a Weave scorer?"
list_entities_tool	List entities accessible to the current API key	"Which W&B teams can I access?"
query_wandb_entity_projects	List projects for an entity	"What projects exist?"
list_registries_tool	List model registries in an organization	"What registries are available?"
list_registry_collections_tool	List collections within a registry	"What models are in the prod registry?"
list_artifact_versions_tool	List versions of an artifact collection	"Show versions of my model artifact"
get_artifact_details_tool	Get full details of an artifact version	"What's in model-v2 artifact?"
compare_artifact_versions_tool	Diff two artifact versions	"Compare model v1 vs v2"
list_wandb_automations_tool	List W&B Automations	"What automations alert on run metrics or status for my team's runs?"
list_wandb_integrations_tool	List registered integrations for W&B automations (e.g. Slack, webhook)	"Which Slack channels can my automations target?"
aria_send_message (opt-in)	Start or continue async work with the hosted W&B agent	"Ask ARIA to diagnose these failed evals"
aria_get_turn (opt-in)	Poll an ARIA turn for progress or its final result	"Check whether that ARIA analysis finished"
aria_get_turns (opt-in)	Poll up to 20 ARIA turns concurrently	"Check all of those ARIA analyses in one bounded wait"

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:

Deployment	Settings
MT SaaS with Agent Lens	models-weave-agents-agent-lens, shared, read-write (39 tools)
Dedicated Models-only	models-only, dedicated, read-write (17 tools)
Dedicated with classic Weave	models-weave, dedicated, read-write (22 tools)
Local extra GraphQL tool	models-weave-graphql-compat, local; choose either access mode

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.

Tool	Description	Example Query
list_weave_agents_tool	List agents with aggregated stats (invocations, tokens, duration, errors)	"Which agents ran this week and how many errors did each have?"
list_weave_agent_versions_tool	Per-version stats for one agent	"Did v2 of my agent regress on latency?"
query_weave_agent_spans_tool	Query individual agent/LLM/tool spans (filter by agent, model, time)	"Show failed tool spans for my-agent yesterday"
get_weave_agent_span_stats_tool	Time-bucketed metric series (tokens, cost, latency, error rate)	"Plot daily token usage by agent"
list_weave_agent_custom_attributes_tool	Discover custom attribute keys on agent spans	"What custom attributes do my agent spans have?"
search_weave_agents_tool	Full-text / structured message search, grouped by conversation	"Find conversations mentioning refunds"
get_weave_agent_trace_tool	Structured chat/trajectory view for one trace (a turn)	"What did the agent do in trace abc123?"
get_weave_agent_conversation_tool	Multi-turn chat view for a conversation	"Show the whole conversation conv-42"

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.

To search a self-hosted copy of the docs (for example, docs matched to your W&B Server version), set DOCS_MCP_URL to its MCP endpoint, such as http://localhost:3000/mcp. The endpoint must accept a JSON-RPC tools/call for search_weights_biases_documentation over Streamable HTTP, as docs.wandb.ai/mcp does. No W&B credential is sent to it. With the operator-wandb Helm chart, set mcp-server.env.DOCS_MCP_URL.

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 deployments (since 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.

---

Quick Start

We recommend using our hosted server at https://mcp.withwandb.com/mcp - no installation required!

🔑 Get your API key from wandb.ai/authorize

🌐 For W&B Dedicated / Self-Managed, use the instance MCP endpoint when enabled by your operator chart (https://<your-instance>/mcp). Local STDIO remains available by setting WANDB_BASE_URL=https://<your-instance>.

Cursor

• 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.

OpenAI Response API

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.

Claude Code

# 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.

OpenAI Codex

# 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.

Gemini CLI

# 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.

VSCode

# 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.

Mistral Chat

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>.

Claude Desktop

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.

---

General Installation Guide

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.

---

More Information

Command Line Reference

When running the server locally, you can customize its behavior with command line arguments:

Available Arguments

Note: Arguments use underscores (e.g., --wandb_api_key), not dashes.

Argument	Type	Default	Description
--transport	string	stdio	Transport type: stdio for local MCP client communication or http for HTTP server
--host	string	localhost	Host to bind HTTP server to (only used with --transport http)
--port	integer	8080	Port to run the HTTP server on (only used with --transport http)
--wandb_api_key	string	None	Compatibility-only API key input; prefer WANDB_API_KEY so the key is not exposed in process arguments
--weave_entity	string	None	The W&B entity to log traced MCP server calls to
--weave_project	string	weave-mcp-server	The W&B project to log traced MCP server calls to

Environment Variables

Variable	Description	Required
WANDB_API_KEY	Your W&B API key (alternative to --wandb_api_key flag)	Yes
WANDB_BASE_URL	Public W&B instance URL used for credentials and user-facing links	No
WANDB_INTERNAL_BASE_URL	Optional server-side W&B Models/API URL; Dedicated charts set this to the in-cluster API service. Weave trace routing remains controlled by WF_TRACE_SERVER_URL.	No
WB_AGENT_BASE_URL	Explicit approved HTTPS origin required only by the ARIA tool profile	No
MCP_SERVER_LOG_LEVEL	Logging verbosity: DEBUG, INFO, WARNING, ERROR	No
WANDB_SILENT	Set to "True" to suppress W&B SDK output (default: true)	No
WEAVE_SILENT	Set to "True" to suppress Weave SDK output (default: true)	No
WANDB_DEBUG	Set to "true" to enable detailed W&B logging	No
MCP_AUTH_DISABLED	Must be true to acknowledge unauthenticated loopback HTTP development	No
WANDB_MCP_PROXY_DOCS	Enable/disable docs search proxy (default: true)	No
DOCS_MCP_URL	Docs MCP endpoint used by search_wandb_docs_tool (default: https://docs.wandb.ai/mcp); HTTP(S), no credentials, query, or fragment	No
MCP_ANALYTICS_DISABLED	Disable structured MCP analytics events	No
MCP_ANALYTICS_QUEUE_CAPACITY	Maximum outstanding events per optional Segment or Datadog forwarder (default: 256)	No
MCP_REQUEST_SUCCESS_SAMPLE_RATE	Deterministic sample rate for successful HTTP request telemetry (default: 0.10; failures and requests over two seconds are always retained).	No
MCP_LOG_PRIVACY_LEVEL	Telemetry privacy: off/standard use an already-authenticated W&B username when functional work has materialized it; strict uses a SHA-256 pseudonym. Datadog keeps one user field, usr.id. Segment uses that trusted username at off/standard for analytics continuity, with a key pseudonym fallback, and always uses a pseudonym at strict. Telemetry never creates a W&B client or viewer request. Unset defaults to off; empty/invalid values fail startup. Raw tool arguments are never logged.	No

Release-controlled orthogonal selectors:

Variable	Default	Effect
WANDB_MCP_TOOL_PROFILE	models-weave	Selects one exact reviewed product-capability profile.
WANDB_MCP_ACCESS_MODE	read-write	read-only subtracts every write tool.
MCP_WORKLOAD_PROFILE	local	Selects query/history limits, admission mode and wait, deadlines, sessions, and HTTP rate policy.
MCP_CAPACITY_CLASS	small	Selects bounded actor/process capacities and worker counts.

Exact tool profiles:

Tool profile	Groups	Managed workloads	Read-write	Read-only
models-only	models	shared, dedicated	17	15
models-weave	models, weave	shared, dedicated	22	20
models-weave-agents	models, weave, agents	shared	30	28
models-weave-agents-aria	models, weave, agents, aria	local only	33	30
models-weave-graphql-compat	models, weave, raw-graphql	local only	23	21
models-weave-agents-agent-lens	models, weave, agents, agent-lens	shared	39	37

Exact workload defaults:

Workload	Collection rows	History samples	Metric keys	Range span	Full-detail rows	Admission / HTTP rate
shared	100	500	20	5,000	3	application admission and HTTP rate limiting off
dedicated	250	1,500	50	20,000	10	admission on; 60/key/minute, 1000/process/minute
local	1,000	5,000	100	100,000	25	application admission and HTTP rate limiting off

Exact capacity classes:

Capacity class	Actor	Process	Sync workers	Count workers
small	4	4	4	4
medium	4	8	8	8
large	8	16	16	8

Use python scripts/public_release.py profiles --all for every exact profile/access-mode manifest and tool name. Runtime contract: sha256:230cce534205b7ad60afcf34909b6f9d1cd76e5ceda703cd9bca6a866cb6ef91.

For the standalone console entrypoint, credential resolution is command-line compatibility input, then the .netrc entry for WANDB_BASE_URL, then WANDB_API_KEY (including a repository-root .env loaded by the CLI). Prefer the environment and remove stale .netrc entries for the same host; never pass a key in release automation or a process argument.

Workload profiles are authoritative in managed deployments. They select query and history limits, admission mode and wait, deadlines, session bounds, and HTTP request-rate policy. Low-level numeric overrides are rejected for shared and dedicated; only local accepts bounded advanced overrides. The generated tables above contain the exact workload and capacity defaults. MCP_CAPACITY_CLASS independently selects actor/process capacity and worker counts; it does not change product capabilities, query semantics, or caller authorization.

Usage Examples

STDIO Transport (default for desktop clients):

# Basic usage with environment variable
export WANDB_API_KEY="your-api-key"
uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z wandb_mcp_server

For stdio clients such as Claude Desktop, stdout is reserved for MCP JSON-RPC messages. The server routes logs and analytics to stderr so clients do not parse diagnostics as protocol messages.

HTTP Transport (for testing and development):

# Basic HTTP server on localhost:8080
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 (log MCP calls to W&B):

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 \
  --weave_entity my-team \
  --weave_project mcp-monitoring

View all options:

uvx --from git+https://github.com/wandb/wandb-mcp-server@vX.Y.Z wandb_mcp_server --help

Contributing & Releasing

• CONTRIBUTING.md -- Development setup, testing, PR process, architecture overview
• RELEASING.md -- Public source releases and artifact verification
• Release index -- Availability and immutable artifacts by channel
• Query capability matrix -- Typed reads and the opt-in compatibility path
• Detailed tool guidance -- Extended query, trace, history, and report examples outside the compact MCP descriptions
• Observability -- Logging, telemetry privacy, and supported collection modes
• Tool-development skill -- Safe implementation and validation workflow
• Release skill -- Exact-candidate release validation and handoff

Key Resources

• W&B Docs: docs.wandb.ai
• Weave Docs: weave-docs.wandb.ai
• MCP Spec: modelcontextprotocol.io

Example Code

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)

Development

Running Tests

Unit tests run without API keys or network access:

uv sync --frozen --extra test --extra http
uv run pytest tests/ -m "not integration" -v

CI runs automatically on every push and PR via GitHub Actions.

Release artifact model

Source releases, container images, and Helm charts are independently versioned. Use the source revision and immutable image digest recorded in the release notes, and check chart compatibility before upgrading. Local source examples use @vX.Y.Z; replace it only with a signed tag listed as available in the release index. A container tag does not imply that a matching Git tag exists. See RELEASING.md for contributor-facing source and artifact checks.

Support

• GitHub Issues
• Email support@wandb.com