Step 3: AI agent (MCP)

⚡ 3 min read

transcodes-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 evaluates policy + 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 → allow

The 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 (before MFA)

When the hook blocks for step-up, transcodes-guard writes guard_gate_decision (deny-stepup-pending) to audit logs. Active Webhook channels also receive the verify link.

Host setup

Install per IDE — same step-up semantics everywhere:

Next: Step 4: Outcome and audit