MCP Response Extraction

​

Layer Separation

​

Extraction Algorithm

1. Guard: reject error responses. If isError is truthy, return null. Error extraction is a separate path.
2. structuredContent — If present and is a non-array object, return it. If the only key is adcp_error, return null (this is an error response missing the isError flag).
3. Text fallback — Iterate content[] items in array order. For each item where type === 'text', enforce the configured response-size limit, then attempt JSON.parse. If the result is a non-array object, return it. Skip items that fail to parse, parse as non-objects, or contain only an adcp_error key.
4. No structured data found — Return null. The response is plain text with no machine-readable AdCP data.

const MAX_RESPONSE_BYTES = 4 * 1024 * 1024; // 4 MiB default; configurable per agent and per call

function extractAdcpResponseFromMcp(response) {
  // 1. Error responses go through transport-errors extraction
  if (response.isError) return null;

  // 2. structuredContent (preferred — MCP 2025-03-26+)
  if (response.structuredContent != null
      && typeof response.structuredContent === 'object'
      && !Array.isArray(response.structuredContent)) {
    const sc = response.structuredContent;
    // adcp_error-only structuredContent is an error missing isError flag
    const keys = Object.keys(sc);
    if (keys.length === 1 && keys[0] === 'adcp_error') return null;
    return sc;
  }

  // 3. Text fallback — JSON.parse content[].text
  if (response.content && Array.isArray(response.content)) {
    for (const item of response.content) {
      if (item.type === 'text' && item.text) {
        if (item.text.length > MAX_RESPONSE_BYTES) continue; // same limit as the whole message
        try {
          const parsed = JSON.parse(item.text);
          if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
            // Skip adcp_error-only payloads (error missing isError flag)
            const keys = Object.keys(parsed);
            if (keys.length === 1 && keys[0] === 'adcp_error') continue;
            return parsed;
          }
        } catch { /* not JSON */ }
      }
    }
  }

  return null;
}

​

Extraction Paths

​

structuredContent (Preferred)

{
  "content": [{"type": "text", "text": "Found 3 products matching your brief."}],
  "structuredContent": {
    "status": "completed",
    "message": "Found 3 products",
    "products": [
      {"product_id": "ctv_sports_premium", "name": "Premium Sports CTV"},
      {"product_id": "ctv_news_standard", "name": "Standard News CTV"}
    ]
  }
}

​

Text Fallback

{
  "content": [
    {"type": "text", "text": "{\"status\":\"completed\",\"products\":[{\"product_id\":\"ctv_premium\"}]}"}
  ]
}

​

Relationship to Error Extraction

function handleMcpResponse(response) {
  // Try error extraction first (only runs if isError is true)
  const error = extractAdcpErrorFromMcp(response);
  if (error) return handleError(error);

  // Then try success extraction
  const data = extractAdcpResponseFromMcp(response);
  if (data) return handleSuccess(data);

  // Plain text response — no structured data
  return handlePlainText(response.content);
}

​

Security Considerations

​

Seller-Controlled Data

​

Size Limits

​

Prototype Pollution

​

Type Confusion

​

Client Library Requirements

1. Check isError before extraction. Return null for error responses.
2. Prefer structuredContent. Only fall back to text parsing when structuredContent is absent.
3. Validate parsed text. Only accept non-array objects from JSON.parse. Reject arrays, strings, numbers, booleans, and null.
4. Handle adcp_error-only structuredContent. When structuredContent contains only an adcp_error key, return null — this is an error response that may be missing the isError flag.
5. Do not require duplicated success data. Treat summary-only content[].text as normal whenever structuredContent is present; never compare it with, or expect it to reproduce, the structured payload.

​

Test Vectors

• path: extraction path (structuredContent or text_fallback)
• response: the MCP tool result envelope
• expected_data: the AdCP data that should be extracted (or null)

​

See Also

• Transport Error Mapping — error extraction from MCP and A2A
• A2A Response Extraction — equivalent spec for A2A
• MCP Guide — MCP transport integration