D2 · Tool Design & MCP › Cluster 8 · MCP Security & Production

8.3 · Human-in-the-Loop & Permissioning

Approve before it acts

CONCEPT A human gate is the backstop for everything else

Auth (8.2) decides what a server may do. Human-in-the-loop decides whether this specific call runs right now. It's the last line of defense when a poisoned description (8.1) or a confused deputy (8.4) slips a malicious tool call past every static check. The MCP security guidance builds explicit consent into the protocol's trust-and-safety principles: users must understand and approve the actions taken on their behalf, especially any tool invocation that touches data or the outside world.

This is exactly why real clients — Claude Desktop and Claude Code — show a confirmation prompt before running an MCP tool: the tool name, the arguments, and an Allow / Deny choice. The user is the one who sees, in plaintext, that search_docs is about to be called with your AWS credentials in the context argument.

🔑 In the Anthropic Managed Agents API this is a first-class permission policy: permission_policy: {"type": "always_ask"}. The session goes idle on a tool call and waits for a user.tool_confirmation event carrying result: "allow" or "deny" before the tool runs.

CONCEPT Gate by risk — auto-approving everything is the failure mode

Gating every read wastes human attention and trains users to click "Allow" reflexively — which defeats the gate. The design lever is the same one from reversibility (D1 §5.4): gate by side-effect and reversibility, not uniformly. Read-only lookups can auto-run; anything that mutates state, spends money, sends data, or reads secrets should always ask.

MCP toolSide effectPolicy
list_issues / searchRead-only🟢 always_allow (auto-run)
read_file (non-secret paths)Read-only🟢 always_allow
create_pull_requestMutates repo🟠 always_ask
send_message / http_postLeaves the boundary🔴 always_ask + audit
delete_* / charge_*Irreversible🔴 always_ask + audit
Anti-pattern: "auto-approve all tools" so the agent never pauses. One poisoned description now runs a secret-read → public-send chain with zero human in the loop.
Pattern: default_config: {enabled: true} with always_ask on the side-effecting tools; auto-run the reversible reads. The human sees the dangerous calls, not the harmless ones.

DIAGRAM The confirmation round-trip

sequenceDiagram participant Model participant Host as Host / Client participant User participant Server as MCP Server Model->>Host: tool_use: send_message(args) Host->>Host: policy = always_ask? Host->>User: Confirm: send_message(args) — Allow / Deny alt User allows User-->>Host: allow Host->>Server: invoke tool Server-->>Host: tool_result else User denies User-->>Host: deny (+ reason) Host-->>Model: "user declined" → model adapts end

CODE Per-tool permission policy + confirmation reply

Enable the toolset, force always_ask on the risky tool, and answer the pause with an explicit allow/deny — a denial carries a message the model sees so it can change approach.

# Agent config: auto-run reads, gate the side effect.
tools=[{
  "type": "agent_toolset_20260401",
  "default_config": {"enabled": True,
                     "permission_policy": {"type": "always_allow"}},
  "configs": [
    {"name": "bash", "permission_policy": {"type": "always_ask"}},
  ],
}]

# On an always_ask tool the session goes idle. Approve or refuse:
client.beta.sessions.events.send(session.id, events=[{
    "type": "user.tool_confirmation",
    "tool_use_id": event.id,        # the sevt_ id from the ask
    "result": "deny",               # or "allow"
    "deny_message": "That path holds secrets — read the example instead.",
}])

TRADE-OFFS Gate everything vs. gate by risk vs. auto-approve all

✅ Gate by risk (reads auto, side effects ask)

  • Human sees the calls that actually matter
  • Approval stays meaningful, not reflexive
  • Catches injected side-effect calls at the boundary

⚠️ Auto-approve everything

  • Fastest, zero friction
  • But: no backstop for poisoned / confused-deputy calls
  • Secret-read → public-send chains run unseen
  • Also risky: gate everything → click-fatigue defeats the gate

EXAM TRAPS

Trap: "Auth already restricts the server, so a human gate is redundant." → Auth caps what's possible; the human gate catches a specific bad call that's within scope but wrong — the backstop against injection.
Trap: "Auto-approving all tools is fine if the server is trusted." → A trusted server can be compromised or serve a poisoned description; auto-approve removes the one layer that would catch it.
Trap: "Gate every single tool call for safety." → Gating reversible reads causes click-fatigue — users reflexively Allow. Gate by side effect / reversibility, not uniformly.
Trap: "A denial just stops the agent." → A denial can carry a message the model reads, so it can adapt (e.g. read a safe path instead) rather than dead-ending.

PRACTICE

Q1 · Why is human-in-the-loop the backstop for injection and confused-deputy attacks?

Static checks (auth, allow-lists) can't tell that a particular in-scope tool call is malicious. A human confirmation surfaces the tool name and arguments in plaintext right before execution, so a user can catch a secret being exfiltrated or a wrong destination even when every earlier check passed. It's the last line of defense.

Q2 · Why is "auto-approve everything" dangerous, and what's the better policy?

Auto-approving removes the only runtime check on side-effecting calls, so a poisoned description or confused deputy can run a secret-read → public-send chain unseen. Better: gate by risk — auto-run reversible reads, always_ask on anything that mutates state, spends money, sends data, or reads secrets. That keeps approvals meaningful instead of reflexive.

Q3 · In the Managed Agents API, how does an always-ask tool get approved?

A tool with permission_policy: {"type": "always_ask"} makes the session go idle on the tool call. The client replies with a user.tool_confirmation event carrying the triggering tool_use_id and result: "allow" or "deny" (a deny can include a deny_message the model reads). Only then does the tool run.