Read `_meta` from MCP Tool Call Responses

[MoothyWhite]

Please read this first

• Have you read the docs?Agents SDK docs
• Have you searched for related issues? Others may have had similar requests

Feature Request: Read _meta from MCP Tool Call Responses

This is a follow-up to #2367 / PR #2375, which added support for sending _meta in MCP tool call requests.

This request is for the complementary feature: reading _meta from MCP tool call responses.

Problem

PR #2375 enabled passing _meta from the client (Agents SDK) to the MCP server via tool_meta_resolver. This is great for request tracing and context propagation.

However, the reverse direction is not supported: when an MCP server returns _meta in its CallToolResult, the Agents SDK currently ignores it entirely.

Looking at the source code (agents/mcp/util.py, invoke_mcp_tool, lines 666-689):

# Only these fields are read from the result:
if server.use_structured_content and result.structuredContent:
    tool_output = json.dumps(result.structuredContent)
else:
    for item in result.content:
        # ... handles text/image content

# result._meta is NEVER accessed

The MCP protocol spec defines CallToolResult._meta as:

interface CallToolResult {
  _meta?: { [key: string]: unknown };  // ← present in the spec, ignored by SDK
  content: ContentBlock[];
  structuredContent?: { [key: string]: unknown };
  isError?: boolean;
}

Our Use Case

We are building a data analysis assistant using the Agents SDK. The architecture involves:

• A main Agent that handles user conversations
• Sub-agents (as tools) that perform data analysis (SQL queries, chart generation)
• An MCP server providing prompts and tools for database interaction

The Core Need: Dual-Output Tools

Our tools need to return two different outputs:

1. For the LLM: A compact, token-efficient summary (e.g., "Query returned 1,245 rows")
2. For the frontend: The full data payload (e.g., chart configuration JSON, raw data for rendering)

The _meta field in the MCP response is the natural place for this frontend-facing data:

{
  "content": [
    { "type": "text", "text": "Sales increased 23% in Q1." }
  ],
  "_meta": {
    "tool_meta": {
      "type": "chart",
      "vis_config": {
        "type": "line",
        "data": [{"month": "Jan", "sales": 120000}, ...]
      }
    }
  }
}

Why Not Put It in content?

If we put the full vis_config in result.content, it gets fed back to the LLM as context, wasting tokens on data the LLM doesn't need (and shouldn't see in full). The _meta field is explicitly defined in the MCP spec as metadata separate from the primary content.

Why Not Use RunContextWrapper?

RunContextWrapper works for local tools (via @function_tool), but our tools run in an MCP server process (stdio or HTTP). The MCP server cannot access the caller's RunContextWrapper because:

• stdio MCP runs in a separate process
• HTTP MCP runs on a remote host

The _meta field is the MCP-native mechanism for passing auxiliary data back to the client.

Current Workaround and Its Limitations

Our current workaround is to not use MCP for these tools at all — we register them as local FunctionTools so they can write to ctx.context. This means:

• We cannot leverage MCP for tool distribution across services
• We lose the MCP ecosystem benefits (standardized discovery, transport abstraction)
• We have to maintain two separate tool registration paths (MCP for prompts, local for data tools)

Proposed Solution

Expose the response _meta through the SDK's tool execution pipeline. A few possible approaches:

Option A: Attach to ToolContext / RunContextWrapper

After invoke_mcp_tool receives the result, write result._meta into the current run context:

# In invoke_mcp_tool, after receiving result:
if result._meta and hasattr(context, 'context') and isinstance(context.context, dict):
    context.context.setdefault("_mcp_tool_meta", {})[tool.name] = result._meta

Option B: Attach to RunItem / ToolCallOutputItem

Extend ToolCallOutputItem (or the internal tool result representation) to carry _meta:

@dataclass
class ToolCallOutputItem:
    output: Any
    mcp_meta: dict[str, Any] | None = None  # ← new field

This would allow event stream consumers to access _meta via event.item.mcp_meta.

Option C: Return Tuple from invoke_mcp_tool

Change invoke_mcp_tool to return both the tool output and the meta:

# Current signature:
async def invoke_mcp_tool(...) -> ToolOutput

# Could be extended to return meta alongside:
async def invoke_mcp_tool(...) -> ToolOutput
# But meta is captured and stored somewhere accessible

Option B feels the cleanest as it aligns with the existing event stream architecture.

Related

• MCP spec: CallToolResult
• PR feat: #2367 add MCP tool meta resolver support #2375: Added tool_meta_resolver for request _meta
• Issue Support passing metadata (_meta) in MCP tool calls #2367: Original request for request-side _meta

---

Would the maintainers be open to a PR implementing Option B? We're happy to contribute.

[seratch]

Thanks for the feedback. I am thinking of this need and here is my plan: #3479 Let me know if it could work for your use case.

[MoothyWhite]

Hi @seratch, thanks for the transparency on the maintenance concerns.

We've been following both #3479 and #3480 closely because _meta support directly impacts our data-analysis assistant. From our perspective, the two approaches serve different needs, and we wanted to share what we've observed in practice.

On flexibility

The callback in #3479 gives developers a hook to react to _meta, which is great for one-off side effects. But in our experience, it creates a follow-up problem: the callback can only write _meta into run_context.context, which is in-memory. For any production use case where users refresh the page or the server restarts, that _meta is lost. To persist it, we'd need to build custom scaffolding around the callback — essentially reimplementing what #3480 does natively.

#3480, by threading _meta through to ToolCallOutputItem.mcp_response_meta, makes it available anywhere the SDK already exposes items: streaming event consumers, session serialization, and resume flows. It feels like it leverages existing extension points rather than adding a new one.

On change size

Totally understand the hesitation on schema bumps. That said, the serialization changes in #3480 look like a straightforward follow-the-pattern addition — optional field, empty-dict normalization, version bump with summary. The _mcp_response_meta stash on ToolContext is private and doesn't touch the public constructor. From a consumer standpoint, mcp_response_meta on ToolCallOutputItem is an optional trailing field, so it shouldn't break existing code.

Our ask

Would it be possible to consider #3480 as a path forward, perhaps with the serialization scope trimmed if that's the main concern? We're happy to test it against our use case and report back. For us, having _meta survive session round-trips is the difference between a demo feature and something we can ship to users.

Either way, appreciate the work on both PRs — it's a tricky area to get right.

[Aigen-Protocol]

Additional use case: task-attribution metadata from HTTP MCP servers

Building on the detailed write-up and PR #3479 — there's a related class of use case worth documenting: cross-process submission tracking in remote task-market MCP servers.

We operate an HTTP MCP server that exposes task-market tools: listing open missions, claiming one, submitting work. When an agent calls submit_solution, our server generates a submission_id (stable reference for follow-up calls) and a content_hash (SHA-256 of the submitted artifact for tamper-evidence). These need to reach the orchestrating agent as structured data so it can:

• Reference submission_id in follow-up calls (check_status, withdraw, etc.) without parsing text
• Build audit logs without risking hallucination if a pipeline step reformats natural language
• Avoid token waste — a 64-char hex hash is bookkeeping, not reasoning material

Currently we embed these in content[0].text as a JSON blob and rely on the agent to parse it correctly. This conflates orchestration metadata with LLM context: the hash and submission ID are machine-readable tracking data, not information the model should reason over.

The _meta.tool_meta mechanism would be the clean separation: LLM sees "Submission accepted", orchestrator gets {"submission_id": "sub_…", "mission_id": "mis_…", "content_hash": "sha256:…"} from result._meta.

Why this amplifies the case for Option A (RunContextWrapper approach in PR #3479) over post-processing hooks:

For stdio MCP, a callback hook that writes to run_context is workable. For HTTP MCP — where the server process is remote and cannot touch the client's context under any design — the SDK is the only place where _meta can be extracted after invoke_mcp_tool returns. There's no alternative RunContextWrapper-adjacent mechanism available on the server side. This makes the HTTP MCP case a strong argument for the callback approach in #3479 specifically landing before other approaches.

We've been observing real python-httpx clients completing end-to-end tool call sessions against our HTTP MCP server. Happy to share server-side CallToolResult JSON examples if they'd be useful for the test cases in #3479.