Tool Approvals

MCPlexer supports a two-phase approval flow for sensitive tool calls. When enabled on a route rule, tool calls are blocked until a human (or another agent) explicitly approves or denies them.

Enabling Approvals

Add requires_approval and an optional approval_timeout to any route rule:

yaml

route_rules:
  - id: prod-writes
    workspace_id: ws-prod
    server_id: github-mcp
    tool_pattern: "github__create_*"
    requires_approval: true
    approval_timeout: 300  # seconds, default 300

Name	Type	Default	Description
`requires_approval`	boolean	false	When true, matching tool calls require explicit approval before execution
`approval_timeout`	integer	300	Seconds to wait for approval before the request times out

Approval Lifecycle

Every approval request follows a strict state machine:

pending → approved → (tool executes)
        → denied   → (error returned to client)
        → timeout  → (error returned to client)
        → cancelled → (client disconnected)

Pending — the tool call is blocked, waiting for a decision
Approved — a reviewer approved the call; MCPlexer forwards it to the downstream server
Denied — a reviewer denied the call; the client receives an error with the reviewer's reason
Timeout — no decision was made within approval_timeout seconds
Cancelled — the requesting client disconnected before a decision

Two-Phase Flow

When a tool call matches an approval-required route rule, MCPlexer runs a two-phase process:

Phase 1: Request Justification

MCPlexer asks the calling client to provide a justification for the tool call. This gives reviewers context about why the call is being made.

Phase 2: Block Until Resolved

The tool call is held in a pending state. MCPlexer publishes the request via SSE and makes it available through the dashboard and MCP tools. The call remains blocked until a reviewer approves, denies, or the timeout expires.

Self-approval prevention

A session cannot approve its own tool call requests. This prevents an AI agent from approving its own actions. The approver must be a different session, the dashboard, or a system process.

Approval Record

Each approval request captures full context for the reviewer:

Name	Type	Default	Description
`id`	string	—	Unique approval request ID
`status`	string	—	Current state: pending, approved, denied, timeout, cancelled
`request_session_id`	string	—	Session that made the tool call
`request_client_type`	string	—	Client type (e.g., claude-desktop, cursor)
`request_model`	string	—	AI model that initiated the call
`workspace_id`	string	—	Workspace the call was made from
`workspace_name`	string	—	Human-readable workspace name
`tool_name`	string	—	Namespaced tool name (e.g., github__create_issue)
`arguments`	JSON	—	Tool call arguments
`justification`	string	—	Reason provided by the calling client
`route_rule_id`	string	—	Route rule that triggered the approval
`downstream_server_id`	string	—	Target downstream server
`auth_scope_id`	string	—	Auth scope used for this call
`approver_session_id`	string	—	Session that resolved the request
`approver_type`	string	—	How it was resolved: mcp_agent, dashboard, or system
`resolution`	string	—	Reviewer's reason for approving or denying
`timeout_sec`	integer	—	Configured timeout in seconds

SSE Streaming

Subscribe to real-time approval events via Server-Sent Events:

GET/api/v1/approvals/stream

SSE stream of approval events. Emits events when approvals are created, approved, denied, timed out, or cancelled.

This powers the dashboard's real-time approval notifications and can be consumed by any SSE client.

Dashboard UI

The MCPlexer dashboard provides a dedicated approval queue where reviewers can:

See all pending approval requests with full context
View the tool name, arguments, justification, and requesting session
Approve or deny requests with an optional reason
Monitor approval metrics (pending count, approval rate, average wait time)

REST API

GET/api/v1/approvals

List approval requests. Supports filtering by status, workspace, and session.

Query parameters: status, workspace_id, session_id, limit, offset

POST/api/v1/approvals/:id/approve

Approve a pending tool call request.

Body: {"resolution": "Looks good, approved for production"}

POST/api/v1/approvals/:id/deny

Deny a pending tool call request.

Body: {"resolution": "Too risky without a backup plan"}

MCP Tools

MCPlexer exposes three built-in tools for programmatic approval management. These allow AI agents to participate in the approval workflow.

available MCP tools

mcplexer__list_pending_approvals List all pending approval requests with full context mcplexer__approve_tool_call Approve a pending tool call by approval ID mcplexer__deny_tool_call Deny a pending tool call by approval ID with a reason

Agent-in-the-loop

You can set up a supervisory agent that reviews and approves tool calls from other agents. The supervisor connects to MCPlexer as a separate session and uses the MCP approval tools to manage the queue.

Metrics

The dashboard displays approval metrics including:

Pending count — number of requests awaiting review
Approved / Denied / Timeout counts — historical resolution breakdown
Average wait time — how long requests typically wait before resolution

These metrics help teams tune timeout values and identify bottlenecks in the approval workflow.

Secrets Audit Logging