fix: make server dispatch automatically adapt responses by requested AdCP version

[bokelley]

Summary

After #855, the Python SDK exposes resolve_requested_adcp_version(), which is useful, but seller applications still have to wire the versioning contract manually inside tool handlers.

That leaves generic protocol behavior in every adopter:

• Resolve the buyer's requested AdCP release from request payload fields.
• Default omitted/legacy buyers to the correct 3.0 compatibility behavior.
• Convert unsupported versions into a protocol error.
• Project media-buy responses into the requested release shape.
• Keep MCP and A2A behavior consistent.

This should be automatic in the SDK/server dispatch layer. Seller handlers should be able to return the canonical current response model, and the server should serialize the correct wire shape for the buyer.

Current adopter-side code

Prebid Sales Agent currently has to carry local code equivalent to:

SUPPORTED_ADCP_VERSIONS = ("3.0", "3.1-beta.3")

requested_adcp_version = resolve_requested_adcp_version(
    request_payload,
    supported=SUPPORTED_ADCP_VERSIONS,
)

if requested_adcp_version == "3.0" and response.status == "completed":
    response.status = response.media_buy_status
    del response.media_buy_status

The real code is more defensive, but the important point is that it is protocol negotiation and response projection, not seller business logic.

Expected

The SDK/server layer should own version negotiation and response serialization:

• Resolve the requested version once during dispatch.
• Reject unsupported versions before invoking the platform handler, or expose a standard exception mapping.
• Expose the resolved version on RequestContext for legitimate business-logic cases.
• Normalize versioned response shapes after the handler returns, for both MCP and A2A.
• Keep this behavior aligned with advertised supported_versions.

Then a seller can implement create_media_buy/update_media_buy once and return the current canonical model:

{
  "status": "completed",
  "media_buy_status": "pending_creatives"
}

The SDK would emit legacy 3.0 wire shape for 3.0 buyers:

{
  "status": "pending_creatives"
}

and 3.1 shape for explicit 3.1 buyers:

{
  "status": "completed",
  "media_buy_status": "pending_creatives"
}

Why this matters

If this stays in seller code, every adopter has to rediscover the same edge cases and keep MCP/A2A behavior aligned by hand. That is exactly the kind of SDK workaround that will fragment implementations.

Related follow-ups from the same integration pass:

• fix: make MCP outputSchema accept negotiated 3.0 media-buy status #866: MCP outputSchema still rejects negotiated 3.0 media-buy success statuses.
• fix: disambiguate A2A artifact domain status from task lifecycle status adcp-client#2009: JS A2A parser confuses artifact domain status: "canceled" with task cancellation.

[bokelley]

Triage

Classification: Feature request
Bucket(s): handlers, middleware (neither label exists in repo — flagged in run summary)
Status: ready-to-implement

What the experts said:

• dx-expert: real boilerplate reduction; resolved_adcp_version: str | None = None on ToolContext is the right attachment point; non-breaking additive field; cautions that sellers doing manual version projection today must remove their projection code after migration or it will be applied twice
• ad-tech-protocol-expert: MCP dispatch already centralizes normalization correctly; A2A gap is confirmed — a2a_server.py never calls _normalize_response_envelope at all; spec places projection on the transport layer, not the handler; critical: None must mean "assume latest" in A2A, not collapse to the DEFAULT_UNNEGOTIATED_ADCP_VERSION = "3.0" pin that unnegotiated MCP traffic uses

My take: The dispatch already resolves wire version and normalizes MCP responses internally — the two missing pieces are (1) threading the resolved version onto ToolContext so handlers can observe it, and (2) extending the same normalization to the A2A path, which currently has none. Both are additive and the normalization is idempotent with what the MCP path already does.

Implementation scope:

• src/adcp/server/base.py — add resolved_adcp_version: str | None = None to ToolContext
• src/adcp/server/mcp_tools.py — set ctx.resolved_adcp_version = wire_version in call_tool after the version is resolved (~line 2307)
• src/adcp/server/a2a_server.py — add detect_wire_version call and post-handler _normalize_response_envelope (currently absent); preserve None = assume latest, not None = 3.0
• Tests: ToolContext.resolved_adcp_version is populated in both MCP and A2A dispatch; A2A path normalizes 3.0 shapes correctly
• Required checks: pytest tests/, mypy src/adcp/server/, ruff check src/
• Non-breaking: new None-default field on ToolContext; MCP normalization already runs today; A2A addition is strictly additive

Related: #866 (MCP outputSchema validation, parallel work, not a blocker).

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[bokelley]

Resolved on main by the server dispatch/version negotiation work. Dispatch now resolves the requested ADCP version, threads , and applies response adaptation; A2A uses the same tool-caller path with explicit major-version projection coverage in .

[bokelley]

Correction to the close note above: resolved on main by the server dispatch/version negotiation work. Dispatch now resolves the requested ADCP version, threads ToolContext.resolved_adcp_version, and applies response adaptation; A2A uses the same tool-caller path with explicit major-version projection coverage in tests/test_a2a_server.py.