docs: MCP tiered tool-permissions design brief

[graycyrus]

Tracking issue

Part of #2373 — #2373 ("MCP: tiered tool-call permissions (design + rollout plan)"). This PR adds the design brief the issue points at; it does not close #2373 — the actual implementation work is follow-up, sequenced per the rollout plan below, and #2373 stays open to track that.

Summary

Adds docs/issues/mcp-refactoring-enhancing/, an implementation brief for
replacing the current flat read_only_tools allowlist with a per-tool,
three-tier permission model (Interactive / Read-only / Write-delete, each
with a bulk default and per-tool override) — the shape Claude's own
Connectors settings page uses.

Covers, across four files (each under the 500-line cap):

• Four prerequisite fixes and the order they need to land in, including
  closing the per-server scoping gap on mcp_registry grants (issue mcp: the console cannot discover servers, while OpenHuman's registry sits unwired in every tenant #1270's
  deliberately-deferred asymmetry)
• The actual tool-tier data model: new Rust types, the
  mcp_call_tool_consequence rewrite (including a genuinely new Blocked
  enforcement state), and a migration rule for existing read_only_tools
  data with a hard "byte-identical approval behavior" merge gate
• Why declared-server and registry-install storage stay structurally
  separate while the new policy shape unifies across both
• New API routes/DTOs and a six-step rollout order with blast-radius notes
• ASCII mockups of the resulting console UX (servers list, add-connector
  modal, directory/discover page, the per-server tool-permissions page)

Also fixes a real doc/code divergence found while researching this: the
existing docs/modules/mcp.md "Pool-staleness caveat" claimed MCP config
changes need a company restart to take effect. That's stale — the code
already does fingerprint-based hot reload (HarnessPool's
mcp_fingerprints), applying a change on the agent's next turn. Corrected
in the same commit, with a pointer to the new design brief.

Docs only — no code changes. This is a design/implementation brief for
future work, not the work itself.

Commands run locally

• wc -l on every new/changed file to confirm the 500-line cap
• Verified the fingerprint hot-reload claim by reading
  harness/built_in/mod.rs's mcp_fingerprints field and
  ensure_with_policy directly before writing the correction
• git status before and after to confirm only the intended files changed

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}