MCP `backups_destination`: set or forget where snapshots go, with the same validation as the Backups page; a credential is written, never read back #5449

I added an admin-only MCP tool, backups_destination, that sets or forgets where snapshots go. The new test, test/mcp.test.ts, test/mcp-docs.test.ts and test/mcp-size.test.ts pass. So does every other test/mcp* file (173 tests). tsc --noEmit couldn't run here because the bun types aren't installed in the sandbox.

• Tool: backups_destination takes { action: "set"|"forget", endpoint?, bucket?, region?, accessKey?, secretKey? }. set runs invalidField, so a bad field gets the Backups page's own refusal, then calls saveDestination. forget calls forgetDestination. It needs an admin token. The sandbox-blocked type check and everything else are as above.
• Answer: { kind, place, says }. kind is the destination now in effect (sealed, dir, env or none) and place is where it points. No key or secret appears in the answer. The tool logs nothing from its arguments.
• Non-admins: the tool is hidden from them, as the other admin tools are. They get a JSON-RPC "no tool named …" error, not a "forbidden" tool result.
• Docs and listing: one row in docs/MCP.md. The tool is marked as a write the way the other writes are, and test/mcp.test.ts lists it.
• Tests: test/mcp-backups-destination.test.ts covers the four cases: set and shown on /settings/backups, a bad field refused, forget clears it, and a non-admin refused. It also checks the answer never contains the secret or the access key. Without the tool, none of the cases can pass.
• "Local" destination: the form has no local-directory field, since FORGE_SNAPSHOT_DIR is an environment setting. The test uses a sealed S3 destination pointing at 127.0.0.1.
• Size cap: tools/list was almost at the 37,000-byte headroom, and a tool with a normal schema pushed it over. I did not raise the ceiling, which test/mcp-size.test.ts says is the owner's. The tool has a bare {type:"object"} schema, with the fields named in its one-sentence description and in docs/MCP.md. I also shortened six unrelated tool descriptions in src/http/mcp.ts: asks_act, access, flow, quotas, issue and propose_to_parent_forge. asks, cloud_account and limb lost a few words each, and asks_act lost "(never undone)" after "ship". Please look at those.
• Left out: a test action that lists the bucket, which would be a separate door.

Closes #5441

I added an admin-only MCP tool, backups_destination, that sets or forgets where snapshots go. The new test, test/mcp.test.ts, test/mcp-docs.test.ts and test/mcp-size.test.ts pass. So does every other test/mcp* file (173 tests). tsc --noEmit couldn't run here because the bun types aren't installed in the sandbox.

• Tool: backups_destination takes { action: "set"|"forget", endpoint?, bucket?, region?, accessKey?, secretKey? }. set runs invalidField, so a bad field gets the Backups page's own refusal, then calls saveDestination. forget calls forgetDestination. It needs an admin token. The sandbox-blocked type check and everything else are as above.
• Answer: { kind, place, says }. kind is the destination now in effect (sealed, dir, env or none) and place is where it points. No key or secret appears in the answer. The tool logs nothing from its arguments.
• Non-admins: the tool is hidden from them, as the other admin tools are. They get a JSON-RPC "no tool named …" error, not a "forbidden" tool result.
• Docs and listing: one row in docs/MCP.md. The tool is marked as a write the way the other writes are, and test/mcp.test.ts lists it.
• Tests: test/mcp-backups-destination.test.ts covers the four cases: set and shown on /settings/backups, a bad field refused, forget clears it, and a non-admin refused. It also checks the answer never contains the secret or the access key. Without the tool, none of the cases can pass.
• "Local" destination: the form has no local-directory field, since FORGE_SNAPSHOT_DIR is an environment setting. The test uses a sealed S3 destination pointing at 127.0.0.1.
• Size cap: tools/list was almost at the 37,000-byte headroom, and a tool with a normal schema pushed it over. I did not raise the ceiling, which test/mcp-size.test.ts says is the owner's. The tool has a bare {type:"object"} schema, with the fields named in its one-sentence description and in docs/MCP.md. I also shortened six unrelated tool descriptions in src/http/mcp.ts: asks_act, access, flow, quotas, issue and propose_to_parent_forge. asks, cloud_account and limb lost a few words each, and asks_act lost "(never undone)" after "ship". Please look at those.
• Left out: a test action that lists the bucket, which would be a separate door.

The two failures aren't caused by this pull, so I changed nothing and pushed nothing. There is no new commit to trigger a re-run, so the forge will need to re-run the check.

The failing tests are wall-clock budget checks on /apps/open and /settings/keys, neither of which my change touches. The pull only adds the backups_destination tool, its docs row and its test, and trims a few tool descriptions.

I re-ran the /apps/open and /settings/keys timing tests (test/cloud-org-apps-timing.test.ts and test/settings-timing.test.ts) three times here. They failed once (/apps/open, 49 ms) and passed twice. Four runs of test/cloud-org-apps-timing.test.ts alone gave one failure, on a different route, /organizations/new: 1.8 ms against a 1.5 ms budget. That is the same kind of failure on whichever route is slowest at the time, so I read it as timing noise on a loaded machine.

Shards 13–15 show exited 143, which is the check killing them after the fail-fast. They contain test/mcp.test.ts and test/mcp-size.test.ts, but they were skipped, not failed. Both pass locally, along with the rest of test/mcp* (173 tests).

If the re-run is red on the same timing tests, the budgets in those tests are the thing to look at, not this pull.

I merged main into the branch and pushed it. The MCP tests pass (404). The full bun test run here had 13 failures, none in MCP code, and the forge's check will run them in full.

• Conflicts: main had split src/http/mcp.ts into src/http/mcp/tools/*.ts, so I took its version of that file and docs/MCP.md. I moved backups_destination into its own file, src/http/mcp/tools/backups_destination.ts, with its doc row. Its logic is unchanged: validated as the Backups page does, and a key is written but never read back. I regenerated docs/MCP.md and the tool index with bun scripts/mcp-tools.ts.
• Size test: the new tool pushed tools/list past the 37,000-byte headroom that test/mcp-size.test.ts enforces. I shortened the descriptions of backups_destination, plan, feed, hold, say, sever, usage, milestones, variant and repo_settings. I did not touch the test's limit. I left signup's description as it was because test/mcp.test.ts asserts its wording.
• Full-suite failures:

- Where they are: the typescript gate audit, the scaffolded-app typecheck, the merge-queue and conflicted-pull tests, main.ts serving / with the SSH port taken, the browser/axe, look and hollow.ts tests, and the crew-proposes-a-resolution test. - Likely cause: the sandbox has no network, no Chromium and no bun type definitions for tsc. I did not check each one. - Not retested: they never exercised the new tool, and I did not rerun them on main to confirm they fail there too.

I made the three fixes sentinel asked for and pushed them (17c1c894). bun test test/mcp passes (405 tests) after merging the latest main. I did not run the whole suite this time.

• Admin scope: backups_destination now sets needsAdminScope: true and no longer checks the scope inside run. An admin's rw token no longer sees the tool in tools/list, and calling it is refused.
• Tests:

- test/mcp-backups-destination.test.ts: a new case mints alice an rw token and checks that set and forget are both refused and sealedSet stays []. - test/mcp-write-scope.test.ts: I added the tool to ADMIN_ARGS, so the generic admin-scope check covers it too. - test/mcp.test.ts: I removed the tool from the list an rw token sees, since it no longer appears there.

• Descriptions: I put back the "Writers." in usage and the "forge repository's" wording in sever. feed now reads "Your ranked home timeline; …", with no stray ;. Both the tools/list size test and the rest of test/mcp pass.
• Left alone: the shortened descriptions for plan, hold, say, milestones, variant, repo_settings and my own tool stay as they were. They drop wording, not who may call. hold still says "Writers."; repo_settings still says "(admin)".

I did not touch anything beyond what the review asked for.

backups_destination now tells an agent how to call it. I pushed this as c7ccc88e. bun test test/mcp passes (406 tests); I did not run the whole suite.

• Schema: tools/list now gives the tool action as an enum (set or forget, required) and the five fields (endpoint, bucket, region, accessKey, secretKey) as bare strings, as sentinel suggested.
• Test: the new case in test/mcp-backups-destination.test.ts has an admin token read tools/list and checks that action is required with values set and forget. It also checks that secretKey is listed.
• Descriptions: I put back "otherwise the next run does" on say and "a later vote replaces it" on variant. The tools/list size test still passes with both restored.
• Not reverted: plan, hold, milestones and repo_settings keep their shortened wording from earlier. The rest of the earlier trims were already put back, and sentinel raised nothing on these four this round.

Handed to a person by the crew: this pull is approved, but 2 runs to bring it up to date with main ended without a push, so no more start here. Conflicting files: src/http/mcp/tools/hold.ts, src/http/mcp/tools/repo_settings.ts. Merge main into it, or say what to try and assign it back to the crew. (The forge posts this under your name; you did not write it.)

This pull adds the MCP tool backups_destination. It sets or forgets where snapshots go, using the same invalidField, saveDestination and forgetDestination as the Backups page. A credential is written and never returned: the answer is only { kind, place, says }.

Main is now merged in. Two files conflicted, src/http/mcp/tools/hold.ts and src/http/mcp/tools/repo_settings.ts, and both were only description wording. I kept main's text for both, so this pull no longer changes either file.

The tool is admin-only, with the admin-scope check, so an admin's rw token and a non-admin's admin token are both refused. Each field is type-checked and trimmed before validation. The type check is clean, and the 421 tests matching test/mcp pass. Four network-outbound denials to localhost were logged by the sandbox during the run, but no test failed. I did not run the full check here; the forge runs it on this push.

To try it, call tools/list on /mcp with an admin token and look for backups_destination, whose schema has a required action enum. Calling it without a token is refused.