# W&B MCP Server v0.4.3

**Release date:** Pending

## Availability

| Channel | State | Immutable artifact |
|---|---|---|
| Public source | Candidate | Pending signed tag and GitHub Release |
| W&B-hosted | Deployed via the candidate-production exception (not an official source release) | Image `sha256:e5bb3030821521dfcf789dcd548cb9597d3dd4ed18ad4d923b3687ed6b92714d`, staging run 38835652780, promotion run 38925309173 |
| Customer container | Pending | Public repository and verified immutable digest |
| Dedicated/Self-Managed | Pending | Compatible chart/configuration and installation evidence |

Report each artifact's actual status. Do not infer a signed source release or
installation qualification from a published container.

## Summary

This candidate restores W&B username attribution in server analytics. Since
0.4.0 most events identified the actor only by an API-key pseudonym, which
analytics could not join to a user. At the `off` and `standard` privacy levels
the server now resolves the authenticated username once per actor and uses it
for session, request, and tool events.

It also lets operators point docs search at a self-hosted docs MCP endpoint,
for example one serving docs that match their W&B Server version, and keeps
every MCP tool description under 4,000 characters for clients that enforce a
per-tool description limit.

## Highlights

- HTTP authentication resolves the W&B username with one viewer lookup per
  actor and endpoint, cached in process for six hours; STDIO reuses the viewer
  fetched by startup key validation.
- Lookups are bounded: at most four run concurrently on a dedicated executor, a
  request waits at most three seconds, failed lookups are cached separately for
  five minutes, and lookup clients never enter the functional client cache.
- `strict` privacy and `MCP_ANALYTICS_DISABLED=true` never perform the lookup.
- New optional `DOCS_MCP_URL` points `search_wandb_docs_tool` at a
  self-hosted docs MCP endpoint instead of `https://docs.wandb.ai/mcp`.
- The `query_wandb_tool`, `query_weave_traces_tool`, `get_run_history_tool`,
  and `create_wandb_report_tool` descriptions are shortened to stay under
  4,000 characters; extended examples moved to
  [`docs/tool-guidance.md`](../tool-guidance.md). Tool names, schemas, and
  behavior are unchanged.
- The four shortened descriptions now carry the counting, sorting, filter-cost,
  evaluation-anatomy, and report-title rules that ARIA's W&B skill cards use,
  still under 4,000 characters each.
- `query_wandb_tool` rejects an `order` field the W&B backend cannot sort by
  (for example `-summary.loss` instead of `-summary_metrics.loss`) with an
  immediate `invalid_request` instead of waiting for the tool deadline.
- `mcp` is raised to 1.30.0 or newer (GHSA-84m7-p3x7-pcfv: stateful Streamable
  HTTP servers never reclaimed session state).
- No tool schema or runtime-contract change.

## Runtime contract

<!-- BEGIN GENERATED: RELEASE RUNTIME CONTRACT -->
<!-- Generated by scripts/public_release.py docs. Do not edit this block. -->

This release replaces arbitrary per-feature booleans with one packaged runtime contract and four orthogonal selectors:

- `WANDB_MCP_TOOL_PROFILE` selects the exact product-capability profile.
- `WANDB_MCP_ACCESS_MODE` selects `read-write` or `read-only`.
- `MCP_WORKLOAD_PROFILE` selects query/history limits, admission mode and wait, deadlines, sessions, and HTTP rate policy.
- `MCP_CAPACITY_CLASS` selects bounded actor/process capacities and worker counts.

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

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

| Capacity class | Actor | Process | Sync workers | Count workers |
|---|---:|---:|---:|---:|
| `small` | 4 | 4 | 4 | 4 |
| `medium` | 4 | 8 | 8 | 8 |
| `large` | 8 | 16 | 16 | 8 |

Runtime contract: `sha256:230cce534205b7ad60afcf34909b6f9d1cd76e5ceda703cd9bca6a866cb6ef91`.
<!-- END GENERATED: RELEASE RUNTIME CONTRACT -->

## Breaking changes and migration

None.

## Compatibility

- Supported Python versions: unchanged from 0.4.2.
- Supported MCP protocol/SDK range: unchanged from 0.4.2.
- Supported W&B SDK/server range: unchanged from 0.4.2.

## Operator changes

`DOCS_MCP_URL` (optional, default `https://docs.wandb.ai/mcp`) selects
the docs MCP endpoint. It must be an absolute HTTP(S) URL without credentials,
query, or fragment; an invalid value fails startup. Deployments at `off` or `standard` privacy emit plaintext W&B
usernames to analytics sinks again, as before 0.4.0. See
[`docs/OBSERVABILITY.md`](../OBSERVABILITY.md) for the attribution model.

## Security and privacy

Username lookups are telemetry-only and never used for authorization. Because
HTTP authentication validates key format only, well-formed invalid keys reach
the lookup; their failures are cached in a separately bounded table so they
cannot evict resolved users or their cached clients, and concurrency is capped.
Only exception class names are logged. `strict` remains pseudonymous.

## Known limitations

- A username stays cached for up to six hours after its key is revoked.
- When all lookup slots are busy, a cold actor's request is attributed by
  pseudonym until a later request.
- Hosted serves the candidate image under the candidate-production exception; customer and Dedicated channels are pending.

## Validation

Candidate preflight, unit tests, Ruff, Bandit, and the generated documentation
check pass locally. Public CI, security, installed-wheel, and attestation
evidence are pending until recorded for this tree.

## Immutable artifacts

- Signed source tag: Pending
- Source commit/tree: Pending
- GitHub Release: Pending (draft until channel evidence is complete)
- Wheel and source-distribution checksums: Pending
- Public qualification/provenance attestations: Pending
- Hosted image digest: `sha256:e5bb3030821521dfcf789dcd548cb9597d3dd4ed18ad4d923b3687ed6b92714d` (candidate-production exception; official source-released qualification pending)
- Customer image repository and digest: Pending
- Helm chart version: Pending

## Rollback

- Public source: fix forward from the signed tag.
- W&B-hosted: restore and verify the previous configuration, revision, and traffic.
- Dedicated/Self-Managed: restore the previous chart and image digest.