MCP Approvals
Require human approval before AI models execute sensitive tool calls. Configure per-tool rules to gate dangerous operations while allowing safe ones to proceed automatically.
How It Works
- An AI model requests a tool call through your MCP server
- HookWatch checks explicit rules first, then applies the trust level policy based on the tool's category
- If approval is required, a pending approval record is created with a configurable TTL
- You review the request in the dashboard and approve or reject it
- The tool call proceeds or is blocked based on your decision
- If no decision is made before the TTL expires, the request is automatically expired
Approval Configuration
Each MCP server has an approval_config that controls which tools require approval.
Configure it when creating or updating a server.
Config Properties
| Field | Type | Description |
|---|---|---|
enabled | boolean | Enable approval workflows for this server |
default_action | string | Default when no rule matches: require or allow |
trust_level | string | Trust level: strict (default), moderate, or autonomous. Controls approval behavior when no explicit rule matches. |
ttl_seconds | number | Time-to-live for pending approvals (default: 300 seconds) |
rules | array | Ordered list of tool-matching rules (first match wins) |
Rule Matching
Rules use glob pattern matching and are evaluated in order. The first matching rule determines the action.
| Pattern | Matches | Action |
|---|---|---|
delete_* | delete_user, delete_file, delete_all | require |
write_file | write_file (exact match) | require |
read_* | read_file, read_config, read_user | allow |
Fallback
If no rule matches, the default_action is used. Set it to "require" for a secure-by-default approach.
Trust Levels
Trust levels provide a higher-level control over approval behaviour. They work together with explicit rules — explicit rules always take priority. When no rule matches a tool, the trust level determines the outcome.
| Level | Read tools | Write tools | Destructive tools | Use case |
|---|---|---|---|---|
strict | Falls back to default_action | Falls back to default_action | Falls back to default_action | Maximum oversight — default behaviour |
moderate | allow | require | require | Balanced — safe reads proceed, writes need approval |
autonomous | allow | allow | allow | Full autonomy — rate limits and budgets still apply |
Tool categories
Each managed adapter tool has a category: read (list_*, get_*), write (create_*, send_*,
update_*), or destructive (delete_*). Moderate trust
uses these categories to decide whether approval is required.
Approval Statuses
| Status | Description |
|---|---|
pending | Awaiting human review |
approved | Tool call allowed to proceed |
rejected | Tool call blocked |
expired | TTL exceeded without a decision |
Base URL
https://api.hookwatch.dev/v1/mcp/approvalsThe Approval Object
Properties
| Field | Type | Description |
|---|---|---|
id | string | Unique approval identifier |
mcp_server_id | string | MCP server that requested the tool call |
user_id | string | User who initiated the tool call |
tool_name | string | Name of the tool being requested |
request_body | object | Arguments passed to the tool call |
status | string | Current status: pending, approved, rejected, or expired |
decided_by | string | User ID of who made the decision |
decision_note | string | Optional note explaining the decision |
decided_at | string | ISO 8601 timestamp of the decision |
expires_at | string | ISO 8601 timestamp when the approval request expires |
List Pending Approvals
Retrieve all pending (non-expired) approval requests for the authenticated user.
GET /v1/mcp/approvalsQuery Parameters
| Field | Type | Description |
|---|---|---|
status | string | Filter by status: pending, approved, rejected, expired (default: pending) |
Response
Get Approval
Retrieve a specific approval request with full details.
GET /v1/mcp/approvals/:idApprove Request
Approve a pending tool call request, allowing it to proceed.
POST /v1/mcp/approvals/:id/approveRequest Body
| Field | Type | Description |
|---|---|---|
note | string | Optional note explaining the approval decision |
Response
Reject Request
Reject a pending tool call request, blocking execution.
POST /v1/mcp/approvals/:id/rejectRequest Body
| Field | Type | Description |
|---|---|---|
note | string | Optional note explaining the rejection |
Error Codes
| Status | Error | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing access token |
404 | Not Found | Approval request not found |
409 | Conflict | Approval is not pending (already decided or expired) |