Filter 8: mcp_tool

[leseb]

Purpose

Execute a single MCP tool call against an MCP server. Handle session reuse, approval policy, and event emission.

Behavior

• Look up server config from responses.mcp_tool_map
• Check approval policy: always (require approval), never (auto-approve), filter list
  • Default: approval required
  • If approval required: emit mcp_call.approval_request event
• Reuse MCP session from responses.mcp_sessions (keyed on endpoint + headers hash)
  • Create new session if not cached (protocol auto-detection: STREAMABLE_HTTP → SSE fallback)
• Call tools/call on MCP server
• Emit mcp_call.in_progress, mcp_call.completed / mcp_call.failed events
• Parse result: text content, image content
• Return tool result message for next inference turn

Request parameters

• type: "mcp"
• server_label, server_url, connector_id, headers, authorization
• require_approval: "always" | "never" | ApprovalFilter
• allowed_tools: list[str] | AllowedToolsFilter

Praxis trait methods

• on_response — execute MCP tool call, return result

Routing

Routed to via branch chains based on tool_parse classification. When tool_parse identifies an mcp / mcp_call tool type, the branch chain routes to this filter for execution. Results feed back into the next inference round via agentic_loop.

Same architectural pattern as web_search and file_search execution filters — a leaf execution filter that takes a tool call and produces a tool result.

Dependencies

• MCP servers (HTTP/SSE)
• MCP Foundation (Filter 5: responses_proxy #24 PRs 3-5)
• tool_parse for classification and routing
• agentic_loop (Filter 7: agentic_loop #26) for loop control

Reference

• Proposal: Responses API Filters — Filter 8
• Part of Epic: Responses API and Agentic Loop Orchestration #93

[rpelevin]

For this filter, I would make mcp_call.approval_request a blocking decision contract, not just an emitted notification.

If approval is required, the important guarantee is that tools/call cannot begin until the filter receives a decision for the exact proposed MCP call.

Fields I would include in the approval event:

• response id;
• MCP call id;
• server_label;
• connector_id or session key reference;
• tool name;
• target/resource if known;
• canonical arguments digest;
• approval policy source: default, explicit flag, or filter match;
• approval request id;
• created_at;
• expires_at.

Decision states:

• allow_once;
• deny;
• timeout;
• stale.

Acceptance tests:

1. approval-required call emits mcp_call.approval_request before tools/call.
2. no decision means no MCP execution.
3. approval for one args digest cannot authorize changed args.
4. reused MCP sessions do not reuse approval decisions.
5. timeout/stale decisions are returned as typed failed tool results, not generic transport errors.

That keeps the filter useful as an action boundary instead of only an observability hook.