Tool-call middleware seam

[gbrlcustodio]

Part of the hosted on-behalf-of MCP server proposal (#297).

Scope

Add a documented middleware (interceptor) chain around tool invocation, so cross-cutting concerns can be layered without swapping the server's internal request handlers.

Today the only way to observe or govern a tool call is to replace the low-level CallToolRequest handler on the server. That is a single private slot: it is undocumented, and the next feature that needs the same seam overwrites the previous one. Several accepted and proposed items all need this exact interception point:

• per-tool logging and metrics (Structured request and tool logging #373, Per-user observability and quotas #309)
• per-user quotas and rate limiting (Per-user observability and quotas #309, Rate limiting and abuse protection #307)
• cost weighting for expensive tools (Rate limiting and abuse protection #307)
• downstream protection: circuit breaking and honoring the API's 429s (Rate limiting and abuse protection #307)

Each of these is "run something around a tool invocation with the caller's validated identity in hand." A single ordered middleware chain turns all of them into registered middleware rather than internal extension.

Proposed shape (illustrative, not prescriptive):

async def middleware(ctx: ToolCallContext, call_next):
    # ctx exposes: tool name, arguments, the validated auth context
    # (subject, client id, scopes) from request-scoped identity, and a request id
    result = await call_next(ctx)   # runs inner middleware, then the tool
    # after: result error flag, duration
    return result

Middleware runs in registration order (outer to inner) around the handler, may short-circuit (for example, a quota middleware returning an error result without calling call_next), and has read access to the validated auth context so it never re-decodes the bearer.

Acceptance criteria

• A public, documented way to register tool-call middleware; the internal request-handler dict is no longer the extension surface.
• Middleware receives the tool name, arguments, validated caller identity (subject, client id, scopes), and a request id correlating to the HTTP request.
• Middleware runs in a defined order and can short-circuit a call (return an error result without invoking the tool).
• The structured tool logging in Structured request and tool logging #373 is reimplemented as a middleware on this chain, demonstrating the seam end to end.
• Registering middleware does not require importing or mutating server internals.

Dependencies

Builds on request-scoped identity (#302, closed) for the auth context passed to middleware. Unblocks the tool-call half of per-user observability and quotas (#309), rate limiting and abuse protection (#307), and is the seam #373 should be built on.

[Danielmoraisg]

Hey @gbrlcustodio I was looking at this issue and it occurred to me that we never proposed how we should handle metrics in the hosted mcp server. I'd lean toward a prometheus approach as a plug and play on this middleware so we can record tool metrics like latency, status code etc. Does it sound good? if so I'd be happy to create a sibling issue for this

[adriannoes]

Hey @gbrlcustodio, heads-up from the #373 stack side. We split hosted structured logging into three PRs (#375, #376, #377) and wanted to flag overlap with this issue before we go further.

Where we align (positive)

• feat(mcp): add JSON structured logging emitter and JWT sub claim (#373 stack 1/3) #375 (feat/373-json-log-emitter, ready for review) is mostly independent: JSON emitter (observability/json_logging.py), PIPEFY_MCP_LOG_LEVEL, and PipefyAccessToken.sub. That infrastructure should plug into a future ToolCallContext middleware chain rather than being thrown away.
• feat(mcp): add HTTP request log middleware and hosted wiring (#373 stack 2/3) #376 (HTTP request middleware, draft) is orthogonal to Tool-call middleware seam #374: pure-ASGI request lines, request_id in scope["state"], manual uvicorn — no tool-call seam involved.
• A public middleware chain is the right long-term home for quotas (Per-user observability and quotas #309), rate limiting (Rate limiting and abuse protection #307), and tool observability; we'd rather not have multiple features competing for request_handlers[CallToolRequest].
• Our E2E correlation tests (test_observability_end_to_end.py, stateful session) assert observable behavior; they should survive a move from handler-wrap to middleware.

Where we overlap (risks)

• feat(mcp): add tool-call structured logger (#373 stack 3/3) #377 (tool-call logger, draft) implements logging exactly via the private CallToolRequest handler wrap — the pattern this issue calls out and asks to replace with middleware on the chain.
• Merging feat(mcp): add tool-call structured logger (#373 stack 3/3) #377 before Tool-call middleware seam #374 lands likely means rework in tool_call_logger.py, observability/wiring.py, and related tests when the public seam arrives.
• Shared touchpoints if both land in parallel: observability/wiring.py, server.py, AGENTS.md.

Our plan for now

• Proceed with feat(mcp): add JSON structured logging emitter and JWT sub claim (#373 stack 1/3) #375 only (emitter + settings + sub) and wait for review/merge.
• feat(mcp): add HTTP request log middleware and hosted wiring (#373 stack 2/3) #376 and feat(mcp): add tool-call structured logger (#373 stack 3/3) #377 stay in draft until we coordinate on Tool-call middleware seam #374 timeline and whether tool logging should ship as a temporary handler wrap or wait for the middleware chain.
• We're not blocking Tool-call middleware seam #374 on Structured request and tool logging #373; we're pausing the top of our stack so we don't add more debt on the private handler slot.

Happy to sync on your expected timeline/branch for #374 so we can decide when to adapt #377 (or reimplement tool logging as the first middleware on your chain).

[gbrlcustodio]

Closed by #378