spec: clarify MCP serialization of core/protocol-envelope (payload nesting, context_id vs context echo)

[bokelley]

The ambiguity. `core/protocol-envelope.json` defines a canonical envelope shape with `status` + `payload` required and `context_id` / `task_id` / `timestamp` / `replayed` / `governance_context` as optional siblings. The schema's own `notes` acknowledge that transports serialize this differently:

MCP may represent this via tool response content fields and metadata
A2A may represent this via assistant messages with structured data
REST may use HTTP headers for status/task metadata and JSON body for payload

But the spec doesn't normatively define what MCP-specifically looks like on the wire. Two load-bearing questions aren't answered:

Q1 — Payload nesting in MCP

Given a response like the schema's own example:

```json
{
"status": "completed",
"context_id": "ctx_abc",
"timestamp": "2025-10-14T14:25:30Z",
"payload": { "products": [...] }
}
```

When an MCP tool returns this, do implementations serialize the JSON verbatim (nested `payload` object as a sibling of `status`), or are `payload` fields hoisted to the root?

Current shipping behavior across at least one SDK (`@adcp/client`'s `wrapEnvelope`) is flat: `{ products: [...], replayed: false, context: {...}, operation_id: "op_123" }`. No `status` field, no nested `payload`. Task response schemas like `media-buy/get-products-response.json` declare body fields at the root, not under `payload`.

Which is spec-conforming? The schema's `required: [status, payload]` suggests nested; shipping SDKs ship flat. Conformance testing can't grade this without a normative answer.

Q2 — `context_id` vs a `context` echo object

`protocol-envelope` defines `context_id: string` ("session/conversation identifier"). SDKs in the wild attach a `context: object` — the request's `context` block echoed back unchanged for caller-side correlation (internal tracing, UI session IDs, custom metadata). These are semantically distinct (session scope vs per-request echo) but similarly named.

Is `context` (echo object) a second envelope field that should join `protocol-envelope.json`, or is it the SDK's misinterpretation of `context_id`?

Why this matters

• Multi-SDK interop. Only one production SDK (`@adcp/client`) ships today. Python / Go / Rust SDKs will hit this ambiguity on day one and either choose nested (spec-literal) or flat (SDK-precedent). Divergence here propagates every transport integration.
• Strict validation. Runners that want to validate the envelope (see `adcp-client#832`) can't AJV-check `/schemas/3.0.0/core/protocol-envelope.json` against a flat-wire response without knowing whether that's spec-compliant.
• AdCP 3.0 GA is pinned. Resolving this before 3.1 keeps the path clean; deferring risks every SDK freezing divergent behavior.

Proposed outcome

One of:

1. Normative MCP serialization section in the spec — a short paragraph under each transport (MCP / A2A / REST) stating how `protocol-envelope` serializes, including whether `payload` is nested or flattened. This is the ideal.
2. An errata / clarification note — if the decision is "flat at root" for MCP, add that verbatim to the envelope schema's `notes` and add `context` (echo object) to `protocol-envelope.json` as an optional sibling distinct from `context_id`.
3. Declare current SDK behavior non-conformant and publish migration guidance — if the decision is "nested `payload` is required for MCP too", that's a 3.1 breaking change and needs an explicit ADR.

Happy to contribute the schema / docs change once the working group picks a direction.

Related

• `core/protocol-envelope.json` (definition)
• `adcp-client#832` (downstream tracker for per-field envelope validation — blocked on this question)
• `adcp-client#788` (security-review thread that formalized the SDK's current envelope governance)

[bokelley]

Triage

Classification: Spec question
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Q1 nested is spec-correct — required: [status, payload] + MCP's structuredContent cleanly carries the full envelope, _meta stays transport. Flattening re-introduces the status collision the envelope was designed to prevent. Q2 context (per-request echo) and context_id (session) are semantically orthogonal — get-products-response.json:147 already $refs core/context.json, it just never made it into the envelope doc. Add it. Sizing: needs @bokelley, not Execute-PR — flipping to nested breaks every current @adcp/client integrator's parser post-3.0 GA.
• adtech-product-expert: Flat wins on adopter friction. MCP tutorials + LLM scaffolds produce flat-shaped handlers; payload:{...} nesting is ceremonial boilerplate on both ends. Q2: don't codify @adcp/client's accident — a client_request_id convention covers it. Cost of deferral: two SDKs ship divergent next quarter = silent interop break.

My take: Experts split sharply on Q1 — protocol-expert says spec-correct nested, product-expert says flat-for-adoption. That's the exact trade to rule on. Q2 they agree the need is real; they split on whether to codify as envelope field vs. convention. Both flag this as a GA-defining call that can't wait for 3.1.

@bokelley, your call: (a) nested + patch @adcp/client + migration note in 3.0.x, (b) flat + rewrite the schema's required + normative MCP paragraph, (c) dual-accept at parse with deprecation window. Same decision unblocks the context vs context_id shape.

---

Triaged by Claude Code. Session: https://claude.ai/code/1c1fb33b-fecb-4d12-b1db-01a2d5f4f49b

---

Generated by Claude Code

[bokelley]

Triage

Classification: Spec question
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Real normative gap — envelope's required: [status, payload] contradicts shipping task response schemas (e.g. get-products-response.json) which define body fields at root with their own context sibling. Flat is consistent with MCP conventions + deployed reality; context (echo) is semantically distinct from context_id (session).
• adtech-product-expert: Outcomes (1)+(2) bundled create least friction — ratify flat-on-the-wire behavior the one shipping SDK already uses, add context as first-class envelope field, reject (3). Declaring the sole SDK non-conformant before any peer ships inverts precedent (OpenRTB/prebid/GAM codify shipping behavior first).

My take: Experts converge on outcomes (1)+(2) merged into a single 3.1 clarifying PR — flat MCP serialization canonical, context joins envelope as distinct from context_id, payload in protocol-envelope.json becomes a grouping construct (drop required). The sub-question is whether dropping payload.required needs an ADR or a simple errata. Decision sits with the working group before any edit lands on the CODEOWNERS-protected core schema.

---

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

---

Generated by Claude Code