Why
There are now two MCP servers — hookdeck gateway mcp and hookdeck outpost mcp — and each is scoped to its own project type (#350). That is correct for the servers themselves, but it pushes a choice onto the user that they should not have to make: which one do I install?
Most people have one project type and do not think of themselves as using "the Event Gateway MCP". They use Hookdeck.
Proposal
A top-level hookdeck mcp that accepts any project type and exposes the tools appropriate to whichever project is currently selected. The product-scoped servers stay, for anyone who wants a narrower surface.
This mirrors the CLI itself: hookdeck project use, then commands relevant to that project.
The open question: how tools change with project type
Two designs, and the choice is the substance of this RFC.
A. Dynamic — the tool list changes on project switch
Expose only the selected product's tools; emit notifications/tools/list_changed on switch.
Smallest surface at any moment, but three real risks:
- Clients cache tool lists. tools/list_changed support is uneven. A client that caches at initialize keeps offering tools that no longer exist — silent mismatch, the failure mode we keep working to remove.
- Models handle disappearing capabilities badly. An agent that has seen a tool and then loses it will retry, and the failure will not explain itself.
- Cold start is nearly empty. Before a project is selected there is nothing to expose but login, projects and help.
B. Static superset — every tool always, guarded at call time
Expose both toolsets. A tool for the wrong product returns a directive error:
outpost_tenants needs an Outpost project. This session is on a Gateway project — switch with hookdeck_projects use, or use hookdeck gateway mcp.
No list churn, no cache problem, agent always sees the whole picture, and the error teaches. Cost is roughly 23 tools in context. #228 notes selection accuracy degrades above 30-50 tools, so this is under the line but not free.
Suggested starting point: B. It is strictly simpler, has no protocol-support dependency, and fails loudly rather than silently. Add dynamic filtering only if the tool count is shown to hurt.
Related decisions this depends on
- Tool naming. A single server makes prefixes load-bearing: outpost_tenants vs hookdeck_connections is confusing when both are present, because the second is a Gateway tool wearing a platform prefix. See the rename issue.
- Platform vs product tools. login and projects are platform-level and should keep the hookdeck_ prefix in every server; product tools take the product prefix.
- Project scoping. Gateway MCP: projects use has no project-type guard #350 scopes the per-product servers. The top-level server is the deliberate exception.
Out of scope
Cross-project queries. Related but separable — tracked separately.
Why
There are now two MCP servers — hookdeck gateway mcp and hookdeck outpost mcp — and each is scoped to its own project type (#350). That is correct for the servers themselves, but it pushes a choice onto the user that they should not have to make: which one do I install?
Most people have one project type and do not think of themselves as using "the Event Gateway MCP". They use Hookdeck.
Proposal
A top-level hookdeck mcp that accepts any project type and exposes the tools appropriate to whichever project is currently selected. The product-scoped servers stay, for anyone who wants a narrower surface.
This mirrors the CLI itself: hookdeck project use, then commands relevant to that project.
The open question: how tools change with project type
Two designs, and the choice is the substance of this RFC.
A. Dynamic — the tool list changes on project switch
Expose only the selected product's tools; emit notifications/tools/list_changed on switch.
Smallest surface at any moment, but three real risks:
B. Static superset — every tool always, guarded at call time
Expose both toolsets. A tool for the wrong product returns a directive error:
No list churn, no cache problem, agent always sees the whole picture, and the error teaches. Cost is roughly 23 tools in context. #228 notes selection accuracy degrades above 30-50 tools, so this is under the line but not free.
Suggested starting point: B. It is strictly simpler, has no protocol-support dependency, and fails loudly rather than silently. Add dynamic filtering only if the tool count is shown to hurt.
Related decisions this depends on
Out of scope
Cross-project queries. Related but separable — tracked separately.