Surface upstream HTTP response headers from remote MCP tool calls (e.g. pagination, rate-limit) via CallToolResult._meta #29665

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

When a remote MCP server wraps a paginated REST API, the upstream HTTP response usually carries the totals in headers (x-total-count, x-total-pages, Link: rel="next", plus x-ratelimit-* and x-request-id). The MCP server itself sees those headers, but opencode's MCP client only forwards the response body into CallToolResult.content, so the LLM can never tell how many results exist in total. In practice this forces the model to either keep paging until it hits an empty page (slow, wastes tokens) or just give up on totals.

Concretely: calling a SearchItems-style tool that returns 20 items per page, the model has no way to know there are 1342 matches in total, even though the upstream API already said so in the headers.

I think the right place to put this is CallToolResult._meta, which the MCP spec explicitly reserves for implementation-specific extensions. Something like _meta.opencode.transport = { status, headers } with an opt-in per-server allowlist (so things like set-cookie / authorization don't accidentally leak). Default off keeps existing behaviour identical.

Prior art in this repo:

• LLM response headers are discarded, preventing plugins from accessing proxy routing metadata #26091 / feat(session): expose LLM response headers on assistant messages #26090 do exactly this but for the LLM provider layer (assistant.responseHeaders). The same idea applied to MCP tool results would close the symmetric gap.
• [FEATURE]: Support _meta when calling downstream MCP tools #17084 covers the inbound direction (forwarding caller _meta to downstream tools). This request is the outbound direction (surfacing upstream HTTP metadata back through _meta).
• [FEATURE]: Full MCP client capabilities #28567 lists many MCP client gaps but doesn't specifically cover upstream response headers; happy for this to be folded into that thread if maintainers prefer.