feat(gateway mcp): write mode behind --allow-write, and gateway_ tool rename (v3.0.0)

[leggetter]

Implements #357: write mode for the Event Gateway MCP server behind --allow-write, and the hookdeck_* → gateway_* tool rename. Both halves ship together as v3.0.0.

Base branch: this targets feat/outpost-api-client, not main. pkg/mcpcore and pkg/outpost/mcp do not exist on main — they land via #348, which is still an open draft — and every part of this change builds on them. #349 used the same pattern and merged cleanly. Once #348 merges, this retargets to main.

Breaking change

The nine product tools and the help tool are renamed. Per-tool permission grants and allowedTools config do not survive a rename — every user must re-grant them.

Before	After
hookdeck_connections	gateway_connections
hookdeck_sources	gateway_sources
hookdeck_destinations	gateway_destinations
hookdeck_transformations	gateway_transformations
hookdeck_requests	gateway_requests
hookdeck_events	gateway_events
hookdeck_attempts	gateway_attempts
hookdeck_issues	gateway_issues
hookdeck_metrics	gateway_metrics
hookdeck_help	gateway_help
hookdeck_login	unchanged (platform)
hookdeck_projects	unchanged (platform)

Logging in and switching project are Hookdeck operations whichever product's server you are in, so they keep the platform prefix and stay identical across both servers.

What changed

1. The write-gating machinery moved into pkg/mcpcore. action / actionSet / toolSpec / dispatch were package-private inside pkg/outpost/mcp/tools.go, so a second server could not use them. They are now exported as mcpcore.Action, ActionSet, ToolSpec and Dispatch in pkg/mcpcore/toolspec.go, and both servers are built on them. Not duplicated.

The read-only description suffix previously hardcoded see outpost_help; it now comes from Server.HelpToolName(). The shared input helpers (RequireString, Object, StringMap, StringList) moved to mcpcore too, and resolveAllowWrite is now shared rather than copied.

Outpost behaviour is unchanged — pkg/outpost/mcp/tools_test.go passes with only identifier renames (9 lines).

2. Gateway tools ported onto ToolSpec and given write actions. Every client method already existed; this is tool-layer work only.

Tool	Added
connections	create, upsert, update, delete, enable, disable
sources	create, upsert, update, delete, enable, disable
destinations	create, upsert, update, delete, enable, disable
transformations	create, upsert, update, delete, run
events	retry, cancel, mute
requests	retry
issues	update, dismiss
attempts, metrics	— read-only in both modes

events/retry and requests/retry were built first: Gateway MCP usage is overwhelmingly failure investigation, and retry is the action that follows one.

3. Read-only by default. --allow-write, also read from HOOKDECK_MCP_ALLOW_WRITE; --read-only is accepted and wins if both are passed. The gate is in the schema — in read-only mode write actions are absent from the action enum and the description, so an agent is never offered something it cannot do. mcpcore.RequireWrite sits behind that as defence in depth. delete, cancel, mute and dismiss carry DestructiveHint; per the MCP spec annotations are client UX hints and not the enforcement boundary — the flag is.

Decisions worth reviewing

pause/unpause stay available in read-only mode. They are mutations, and they are deliberately not gated. Read-only is the mode incidents get investigated in, and stopping a misbehaving connection is the natural end of an investigation; requiring a server restart at that moment would be the wrong trade. Both are reversible and pausing buffers delivery rather than dropping events. The rationale is recorded at the action definition, and two tests exist purely to fail if someone later gates them.

transformations/run is gated as a write even though it stores nothing. It executes caller-supplied JavaScript, and a read-only session should not be able to cause that. The issue floated "leaning read"; this goes the other way, on the basis that the gate is about what a session can cause to happen, not only about what it persists.

gateway_help is now generated from the tool specs rather than a static map of ~40 hardcoded names. It reports the current mode and cannot advertise an action the session is unable to perform. Hand-written guidance that is not derivable from the schema (filter mappings, worked examples) is preserved via a new ToolSpec.Notes field.

One real bug fixed along the way: mcpcore.HelpTopic only qualified a bare topic with the product prefix, so topic: "projects" stopped resolving once the Gateway prefix was no longer hookdeck. It now tries the product prefix then the platform prefix. Outpost had the same latent bug and is fixed by the same change.

Testing

• pkg/gateway/mcp/write_mode_test.go — action enum and description per mode, annotations, the handler guard refusing all 19 write actions without the flag, and successful writes asserted on the request the handler sends (method + path), not on "did not error".
• pkg/gateway/mcp/server_test.go passes with only tool-name changes. TestConnectionsPause_Success, _ByName and TestConnectionsUnpause_* still pass without a write-enabled server — the assertion that the pause decision held.
• Acceptance under the existing mcp tag: tools/list omits write actions without the flag and includes them with it; renamed tools present, old names absent; help reports the mode.
• Run locally, both green: go test -tags=mcp ./test/acceptance/... (171s) and go test -tags=outpost ./test/acceptance/... (208s). Outpost is the blast radius of the refactor and had to stay green.
• go build, go fmt, go vet, go test ./... clean. go run ./tools/generate-reference --check passes.

Not run: the Claude Desktop end-to-end check from the plan's manual verification.

Follow-ups

• #352 (the rename) is absorbed here and can be closed on merge.
• Part of the #354 v3.0.0 epic.
• Release notes must lead with the breaking change and carry the mapping table above.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wajsob136PyRh6nc92w5L3

[leggetter]

Absorbed into #348, which is now the single v3.0.0 PR targeting main.

Every commit from this branch is in feat/outpost-api-client — the write mode, the gateway_ rename, the transformations run flip to a read, and the 55/55 action coverage. Closing here so there is one place to review and one branch to release from.

Practical reason for the consolidation: a PR based on a feature branch gets no CI, because the workflows trigger only on PRs to main/next. This branch never had a single check run against it. #348 does.