Epic: v3.0.0 — Outpost support, Gateway MCP write mode, and the gateway_ rename

[leggetter]

Status: implementation complete, awaiting beta

Everything below is on feat/outpost-api-client in #348, with CI green across all four acceptance slices.

This epic was originally scoped as three parked breaking changes (#340, #347, #352). That is no longer what 3.0.0 is. It grew to carry Outpost support and Gateway MCP write mode, and two of the original three did not make it. Scope as it actually stands is below; the deferred items are at the end.

What is in 3.0.0

Breaking

• Rename Gateway MCP product tools to a gateway_ prefix (major) #352 — Gateway MCP product tools renamed hookdeck_ → gateway_. hookdeck_login and hookdeck_projects keep their prefix; they are platform tools shared with Outpost. Per-tool permission grants and allowedTools config do not survive a rename — every MCP user must re-grant.
• Split gateway_events and gateway_requests: 25- and 19-parameter schemas where only id is shared #360 — gateway_events and gateway_requests split into plural (list) and singular (by-id) tools. gateway_event and gateway_request are new; the by-id actions moved off the wide-schema tools.

Features

• Epic: Outpost support in the CLI — commands and MCP #346 — Outpost support. Full hookdeck outpost … command tree and hookdeck outpost mcp.
• Gateway MCP: add write mode behind --allow-write, and align tool naming #357 — Gateway MCP write mode behind --allow-write (default off, HOOKDECK_MCP_ALLOW_WRITE). 28 write actions. pause/unpause deliberately stay available in read-only mode.
• Seven documented API filters added to events and requests on both the MCP tools and the CLI: search_term, next_attempt_at, delivery_group, events_count, ignored_count, cli_events_count.

Fixes found by review

Seven release blockers, all fixed in #348:

• Path traversal in resource IDs — an id like src_1/../../destinations/des_2 retargeted the request, so "delete this source" deleted an unrelated destination while reporting the id it was given. Fixed at two layers with a 57-method table test.
• HOOKDECK_API_KEY printed by --help and, via the reference generator, committable to this public repo.
• Quoted booleans and numbers silently dropped filters — {"verified": "false"} returned every request and reported them as unverified.
• Tool and env-var names that do not exist in user-facing text, including a README instruction to use HOOKDECK_API_KEY for MCP publishing, which the code deliberately refuses.
• outpost destination update rejected every partial update, making credential rotation impossible.
• outpost_destinations create omitted required topics, producing a 422 the CLI never hits.
• ReadOnlyHint: true on a tool offering pause — a client auto-approving read-only tools would have halted production delivery without asking.

Plus, from review of the PR itself:

• reauth no longer clears stored credentials before the sign-in completes — an abandoned browser flow used to sign the user out everywhere for nothing.
• ToolSpec.DefaultAction removed as dead API.
• go vet ./... clean repo-wide (unbuffered signal channel in pkg/login).

Testing

• Coverage gates in both MCP packages that fail when an action ships without a successful-call test. Gateway went from 7 of 55 actions covered to 55 of 55.
• Tests assert the wire request (method, path, query, body), not "did not error".
• The outpostlive suite runs nightly instead of never.
• HOOKDECK_CLI_TESTING_CLI_KEY wired into the acceptance job — project list/use had been skipping in CI since March.

Path to GA

• Manual review of pkg/mcpcore/toolspec.go and pkg/gateway/mcp/tools.go. ~500 lines that construct every tool in both servers. Copilot declined the PR for exceeding its 20,000-line limit, so no automated reviewer has seen it either.
• Cut v3.0.0-beta.1 from feat/outpost-api-client. Not from main — betas ship from the branch.
• Beta validation. Point a real MCP client at both servers, read-only then --allow-write. Note that the beta channel is 1–9 organisations, so do not wait on external beta feedback — it does not arrive. This is dogfooding and rename-derisking.
• Merge v3.0.0: Outpost support, Gateway MCP write mode, and the gateway_ tool rename #348 to main.
• Release notes leading with the rename, including the before/after mapping and an explicit "you must re-grant tool permissions".
• Tag v3.0.0.
• Post-release watch, two weeks, named owner. Error rate per command against the Gateway baseline (10.36% CLI / 3.36% MCP non-2xx over 30 days), drop-off after project use, first external Outpost MCP tool call, --allow-write uptake, first non-webhook destination created. GA-then-fix is only honest if the fix half is real.

Known gaps at GA

Accepted, not blocking:

• Non-webhook destination types (AWS, GCP, Azure, RabbitMQ, Kafka) are validated against the live schema but have never been created against real infrastructure. Only a real user closes this — worth recruiting a design partner already running one.
• Outpost MCP write mode has never been exercised end-to-end against a real project. The actions call the same client methods the CLI commands do, and those are covered; the MCP-specific argument-to-request layer is covered by wire-shape unit tests.
• outpost config set does not validate values. MAX_RETRY_LIMIT=notanumber is accepted with a success message. Per AGENTS.md we do not duplicate API validation client-side, but this is a footgun worth raising server-side.

Follow-ups (explicitly not blocking)

• Follow-ups from the #348 security and code review (non-blocking) #364 — non-blocking findings from the security and code reviews
• Read-only MCP mode filters actions but still advertises write-only properties #363 — read-only mode advertises write-only properties
• Acceptance tests leak sources and destinations: ~36k of each in the CI Gateway project #362 — acceptance tests leak sources and destinations (~36k of each)
• Standardize config input: --config means two different things across gateway and outpost #347 — standardize --config across gateway and outpost
• Gateway MCP: projects use has no project-type guard #350 — projects use has no project-type guard
• RFC: top-level hookdeck mcp exposing tools by selected project type #351 — RFC: top-level hookdeck mcp
• MCP: cross-project fan-out for read tools #353 — cross-project fan-out for read tools

Deferred out of 3.0.0

These were in the original scope of this epic and are not in the release:

• Epic: make the CLI safe and predictable for agents and automation #340 — errors move from stdout to stderr. Still parked on a major. It did not make 3.0.0, so it now needs 4.0.0 or a deprecation path.
• Standardize config input: --config means two different things across gateway and outpost #347 — remove the JSON form of gateway --config. Same.

Both are genuinely breaking, so parking them again has a real cost: the next major is now the third time they have been deferred. Worth deciding whether the additive half of #347 (accept both formats) ships as a minor soon, rather than waiting.

[leggetter]

Hands-on testing results

Two agents drove the CLI and both MCP servers against the real API. Full findings are being worked through as tasks; two results change this epic directly.

The biggest known gap is closed

"Non-webhook destination types have never been created against real infrastructure" — they have now, and all seven work: aws_sqs, aws_kinesis, aws_s3, gcp_pubsub, azure_servicebus, rabbitmq, kafka. Destinations were created and real delivery attempts reached the real services, failing with genuine provider errors (InvalidAccessKeyId from S3, UnrecognizedClient from Kinesis, context deadline exceeded from Azure, DNS failures from Kafka and RabbitMQ). Creation and delivery are not the gap.

A new release blocker in its place

tls silently defaults to off for rabbitmq and kafka, contradicting our own documentation. destination-type get rabbitmq prints "tls (optional; default: on)"; following the CLI's own printed example stores "tls": "false", so SASL credentials and payloads go out unencrypted.

Cause: field.Default is display-only — it is the only read of that field in the repo — while the config map is built purely from supplied flags and config is omitempty, so the key is omitted and the server default (off) wins. We print a default we never send.

This must be fixed or explicitly documented before the beta.

Also worth recording here

• outpost publish reports success for a nonexistent tenant (green checkmark, exit 0) and blames the topic rather than the tenant. The guard exists in pkg/hookdeck and is wired into the MCP tool but not the CLI.
• gateway_event cancel/mute report success that never happened — the handler returns a hardcoded status without checking the outcome, and the API 200s on a no-op.
• Bulk resource management is not possible through the CLI: source/destination/connection list have no --next/--prev despite returning a cursor, deletes cost two requests each, and there is no rate-limit handling. This is why Acceptance tests leak sources and destinations: ~36k of each in the CI Gateway project #362 could not simply be cleaned up.

Cleanup progress on #362

Two of the three Gateway test projects are now fully clean; the first is partially done (36,376 → 27,043 sources). ~18,500 resources deleted.