fix: make MCP outputSchema accept negotiated 3.0 media-buy status

[bokelley]

Summary

After adcp==6.2.0b3, the server-side version resolver/adaptation path is returning the correct legacy 3.0 media-buy shape for omitted/existing 3.0 buyers, but MCP output validation still rejects the response because the advertised/generated tool outputSchema only accepts the 3.1 beta success-envelope status.

This leaves adopters tempted to patch outputSchema locally. We should not do that in sellers; the Python SDK/server layer should generate or advertise an MCP schema that is compatible with the negotiated wire contract.

Environment

• Python SDK: adcp==6.2.0b3
• JS storyboard runner: @adcp/sdk@7.11.0 (AdCP 3.0.12)
• Seller capabilities advertise both 3.0 and 3.1-beta.3
• Repro seller: Prebid Sales Agent local stack

Repro

Run the legacy 3.0 storyboard runner against the MCP endpoint:

npx -y @adcp/sdk@7.11.0 storyboard run \
  http://localhost:50001/mcp \
  media_buy_seller \
  --auth ci-test-token \
  --protocol mcp \
  --allow-http \
  --json

Representative failing scenario:

media_buy_seller/pending_creatives_to_start/create_buy_no_creatives

The seller returns the expected 3.0 shape:

{
  "media_buy_id": "mb_...",
  "packages": [],
  "status": "pending_creatives",
  "context": {
    "correlation_id": "..."
  }
}

But MCP output validation rejects it:

Output validation error: {... "status": "pending_creatives", ...} is not valid under any of the given schemas

In the local repro this accounts for six MCP 3.0 storyboard failures. The same seller code path works for explicit 3.1 beta shape (status: "completed" plus media_buy_status).

Expected

When a buyer requests or implies 3.0 compatibility, the server should be able to return the 3.0 success shape and pass MCP output validation.

Concretely, one of these should happen upstream:

• Generate MCP outputSchema for multi-version handlers wide enough to accept both negotiated 3.0 and 3.1 media-buy success shapes.
• Or select the tool output schema by the resolved request version before validation.
• Or avoid validating a negotiated 3.0 response against a 3.1-only generated success branch.

Notes

This is the residual issue after #851 / #855. Those changes exposed the resolver and improved response adaptation, but the MCP tool schema/validator is still single-shape.

I verified the root cause locally by temporarily widening the generated MCP media-buy create/update success-arm status enum to the legacy MediaBuyStatus values. That made the 3.0 MCP storyboard pass. I removed that local shim because this should be fixed in the SDK rather than in seller applications.

[bokelley]

Triage

Classification: Bug
Bucket(s): handlers, middleware
Status: ready-to-implement

What the experts said:

• ad-tech-protocol-expert: Approach 1 (widen status to union of Literal["completed"] + MediaBuyStatus values, derived from MEDIA_BUY_LEGACY_STATUS_VALUES) is MCP-spec-conformant with cross-protocol precedent; apply to both create_media_buy and update_media_buy. Approach 3 (skip 3.0 validation) is unsound — it removes the structural correctness check for the default unversioned buyer path.
• code-reviewer: Write a failing regression test first — FastMCP's output_model for a → dict[str, Any] fn may be None, meaning rejection could be in validate_response() (version-aware JSON-schema layer) rather than Pydantic; the fix target differs by layer. Approach 2 (contextvars to thread version into _AdcpFuncMetadata.convert_result) is architecturally cleanest if output_model is the actual rejection site.

My take: Both experts converge: Approach 3 is wrong and a failing test on the adcp_version-omitted → status="pending_creatives" path will confirm the rejection layer (FastMCP Pydantic vs. validate_response JSON-schema) and determine whether Approach 1 or 2 applies. Non-breaking either way — only widens accepted values.

• Step 1 — failing test: create_media_buy with omitted adcp_version, handler returns {"media_buy_id": "mb_test", "packages": [], "status": "pending_creatives"}; record exception type + call site to identify the rejection layer.
• If FastMCP output_model layer: widen CreateMediaBuyResponse1.status (and UpdateMediaBuyResponse1) from Literal["completed"] to also accept MediaBuyStatus values — or patch _generate_pydantic_output_schemas() to emit a merged status enum. Derive the union from MEDIA_BUY_LEGACY_STATUS_VALUES in src/adcp/types/media_buy_status_helpers.py.
• If validate_response() layer: update the bundled 3.0 media-buy success schema to include legacy status values; verify post_adapter_validator_version is correctly set for the unnegotiated-default path in mcp_tools.py:2389.
• Checks: pytest tests/test_mcp_middleware_composition.py tests/test_adcp_version_wire.py tests/test_dispatcher_version_routing.py -q, mypy src/adcp/server/, ruff check src/. No dep bumps, no edits to generated_poc/.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01Uysk1rGKvcN8JrqAyKz8fd

---

Generated by Claude Code

[bokelley]

Resolved on main ahead of release. The negotiated 3.0 media-buy status/outputSchema path is covered by \ and related server response adaptation coverage in .

[bokelley]

Correction to the close note above: resolved on main ahead of release. The negotiated 3.0 media-buy status/outputSchema path is covered by tests/test_tools_list_output_schema.py::test_media_buy_output_schema_accepts_negotiated_30_statuses and related server response adaptation coverage in tests/test_schema_validation_server.py.