MCP: cross-project fan-out for read tools #353

Why

Every MCP tool is scoped to one project, because the API is. So the question people actually want to ask — "where are my failures right now?" — cannot be asked directly if they have more than one project.

An agent can already do it: hookdeck_projects use A, query, use B, query, merge. That works, but it is a poor mechanism:

• It mutates session state to perform a read. A failure part-way leaves the session pointing at a project the user did not choose.
• It is serial, so cost and latency scale with project count.
• The agent has to remember to switch back, and nothing enforces it.

Proposal

Let the read tools fan out server-side across several projects and merge the results, rather than making the agent drive it by switching.

Roughly:

hookdeck_metrics { action: "events", project_ids: ["tm_a","tm_b"], ... }
gateway_events   { action: "list", project_ids: ["*"], status: "FAILED" }

Results carry the project each row came from, so an agent can attribute them.

Things to work out

• Which tools. Reads only, and probably only the ones where the cross-project question is natural: events, attempts, issues, metrics. Not writes — fanning out a mutation is a different risk class.
• Partial failure. One project 403s or rate-limits. Return what succeeded plus a per-project error list, rather than failing the whole call. Silent omission would be the worst outcome.
• Rate limits. Fan-out is N requests against a per-key limit. Needs a concurrency cap and probably a project-count ceiling.
• Pagination. Cursors are per project. Merging paginated results across projects needs a defined answer — likely "per-project cursors returned alongside the merged page".
• "*" semantics. All projects the credential can see is convenient and potentially very large. Should it require an explicit list beyond some size?
• Session state. Fan-out must not change the active project. That is the whole point.

Related

• #351 — top-level MCP. Related but separable: this is useful in the product-scoped servers too.
• #350 — project-type scoping. Fan-out must respect it, so a Gateway server fans out across Gateway projects only.

Note this needs a user-associated credential. Keys from hookdeck ci are project-scoped and cannot enumerate projects, so fan-out is unavailable to them by construction.