Step 3: AI agent (MCP)
⚡ 3 min readtranscodes-guard intercepts risky shell and MCP tool calls before they run. When RBAC requires step-up, the hook blocks, opens Transcodes Auth, and the agent waits for human MFA — then retries the same command.
Hook flow
- Agent runs a gated Bash command or protected MCP tool.
- PreToolUse hook calls
POST /guard/evaluate— AI classifies{ resource, action }, then the backend checks the member’s RBAC matrix. - If level 2: backend creates a step-up session → browser opens verify URL → hook returns deny with sid + URL for the agent.
- Human completes MFA on Transcodes Auth.
- Agent calls
poll_stepup_session_wait(or polls manually). - Agent retries the same command — verified record consumed → execution proceeds.
deny (step-up pending) → human MFA → poll verified → retry → allowThe hook is advisory for UX; MCP tool handlers re-check RBAC on execution (execProtectedTool). Stdio bypass cannot skip server enforcement.
MCP tools for step-up
| Tool | Purpose |
|---|---|
create_stepup_session | Open session + browser URL (same backend path as the hook) |
poll_stepup_session | Single status check (pending / verified / rejected) |
poll_stepup_session_wait | Block until terminal status (preferred after a deny) |
inspect_stepup_state | Show pending / verified local state |
Typical agent recovery after a deny:
poll_stepup_session_wait with the sid from the hook message, then retry the command.Gate audit and webhooks
A pending step-up (hook deny, browser opened, MFA not finished) writes no guard_gate_decision audit row. Active Webhook channels may still receive a session webhook with the verify URL.
After MFA, Transcodes Auth writes mcp:stepup (or {resource}:{action}) at high severity. When the agent retries and verification is consumed, the hook writes guard_gate_decision with decision: allow (low). See Audit Logs.
Host setup
Install per IDE — same step-up semantics everywhere: