refactor(mcp): credential-migration tools are listed only for the keys the backend admits (#3435)

[vybe]

Fixes #3435. One of five independent stale-code PRs off dev. Draft until the live exercise below is recorded.

What

The issue was filed as "two credential tools fail on every call". The diagnosis found no defect: the requests are correct, and agent-scoped keys are refused by design (import and export are owner-or-admin and human-only; the encryption-key route is admin-only). This PR makes the catalog honest about that.

• Visibility — export_credentials, import_credentials and get_credential_encryption_key (src/mcp-server/src/tools/agents.ts) each gain a per-tool canAccess allow-list of user and system sessions. An agent session no longer lists them, and calling one by name answers "not found". The previous group default listed them for user, agent and system, so this can only remove a tool from a session.
• Wording — each description now says who may call the tool (a user-scoped or system-scoped key; admin for the key tool). Lengths 613 / 660 / 564 characters, under the 2,048 cap.
• Refusals — a backend 403 is returned as a typed denial (human_only / admin_only / not_authorized) and recorded as denied in the audit log. A 403 without a JSON detail returns a fixed sentence; the response body is never copied. 400, 404 and 503 are thrown exactly as before.
• Guards — a visibility test over the real transport, a shrink-only baseline of the nine other admin-only tools still listed for agents (a new one cannot be added undecided), and tests/unit/test_3435_credential_tool_gates.py, which pins the three backend routes' existing gates by explicit principal.
• Docs — the user-docs MCP list, the FAQ migration entry (including setting the key on the target instance), the credential-injection feature flow and the MCP-server architecture row.

No backend change: git diff origin/dev...HEAD -- src/backend docker is empty. Nobody gains access to anything.

Rulings carried (operator, recorded on the issue 2026-10-09)

• Keep all three tools; fix visibility and wording rather than remove the key tool.
• Allow-list is user + system, so what is advertised equals what the backend admits.
• Only 403 is mapped to the typed envelope.
• No backend access narrowing here, and the nine sibling admin-only tools are not converted here — both are follow-ups.

Review + security

/review (reading review, report-only): MERGEABLE, 0 critical. Hard limits verified: the access.ts rows keep their policy kinds (the owner strings are labels and enforce nothing), the allow-list is a filter on the registered set, a future scope defaults to hidden, and the system key is admitted by all three backend gates. /cso --diff: no findings; the attack surface shrinks. Fixed after review: the non-JSON 403 fallback no longer echoes the response body (test red first), "user-scoped or system-scoped" wording, and a list-formatting fix in the user doc.

Tests

• MCP server: npm test 836 / 836; the two changed test files 36 / 36.
• Backend pins, shuffled (seed 12345): test_3435_credential_tool_gates.py 25 passed, plus the auth-wiring, admin-gate and human-only route suites — 150 passed in six files.
• Mutation checks: dropping canAccess from one tool, hiding a baselined tool without shrinking the baseline, advertising an undecided admin-only tool, removing the audit stamp, and removing the agent-principal rejection from the import handler each turn a test red.
• git merge-tree against dev (21b4a11): clean.
• Not run here: the full unit island (CI) and anything needing a live stack.

Before merge

• Live exercise on a dev instance — record all nine results on refactor: hide the three credential-migration MCP tools from agent sessions that can never call them, and say who may #3435: call each of the three tools with (a) a user-scoped admin key: all succeed, import after an export; (b) a user-scoped non-admin owner key: export and import succeed, the key tool returns admin_only; (c) an agent-scoped key: none of the three is listed and a call by name answers "not found".
• Round trip: export_credentials(A) → read .credentials.enc from A's workspace → inject_credentials(B, …) → import_credentials(B) → get_credential_status(B) lists the files.
• Confirm the ops audit labels the refusals denied.
• Conflicts this branch adds with open PRs (merge-order calls): fix(auth): an agent key reaches only itself, its edges and the agents it spawned — on the raw backend routes too (trinity-enterprise#629) #3346 (src/mcp-server/src/access.ts), and tests/registry.json with fix(public-chat): an anonymous session finds its own history after a reload (#3443) #3477, fix(settings): the email whitelist validates what it stores and can remove whatever it holds (#3455, #3456) #3479 and refactor(api): remove nine uncalled routes and the orphan observability store (#3434) #3483.

Handoffs

• Nine other admin-only MCP tools are still listed for agent sessions that can never call them (baselined in the new guard) — follow-up issue to be filed.
• require_interactive on the encryption-key route — follow-up issue to be filed.
• Overlaps, nothing posted: refactor: domain-split mcp-server client.ts (1,500 lines) and tools/agents.ts #1029 (agents.ts grew ~50 lines), refactor(security): consolidate the eight private MCP in-tool permission-gate copies and add a generic denial sweep #3374 (a module-local refusal mapper), refactor(reliability): MCP tools that return a failure are audited as success — withAudit only sees throws #2926 (400/404/503 are still audited as failures).

🤖 Generated with Claude Code

[vybe]

CI note: the first run's regression diff reported 10 new failures, all in the new test_3435_credential_tool_gates.py (the cases that reach the service). Cause: tests/unit/test_inject_assigned_credentials.py replaces services.credential_encryption in sys.modules at collection and does not restore it; the export and import routes import that module per request, so the new test's stub sat on a stale copy and the real service returned 503. Fixed in c547fb4e (test file only): the fixture patches the module objects the running route reads. The reproducing pairing passes on 20 shuffle seeds and every check on c547fb4e is green. Handoff: the sibling file should restore the module in its teardown — not changed here.

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.