Configure a Tool Group policy

A Tool Group bundles tools (from one or many MCP servers) under a single policy. The gateway applies the group's policy on every call to any tool in the group: rate limits are counted per-group, PII masks are read from the group, the HITL gate fires from the group, audit retention is set by the group. A tool can belong to multiple groups; when it does, the most restrictive policy wins.

The policy editor lives at /console/tool-groups on the right pane when a group is selected. Every save snapshots into tool_group_versions so you can roll back from the history drawer.

Free-text, your audience. Goes in the audit-log expanded view and on the regulator CSV exports under tool_groups.description. Useful for explaining a group to an NDPC auditor in plain language: "All Paystack payment tools subject to standard CBN AML logging."

Which roles can invoke any tool in this group. The six roles come from the canonical RBAC matrix in lib/console/team-types.ts:

• admin: full access to everything
• compliance: full access to compliance surfaces, read elsewhere
• developer: full access to servers and groups, read on audit
• customer_service: read-only on servers, no group access
• auditor: read-only across the board
• member: read-only on servers, no group access

A group with admin only is locked down. A group with admin, compliance, developer is what most payments groups should hold. Adding customer_service to a group implies that role can trigger calls; only add it if the workflow genuinely needs it.

Role enforcement happens in three layers: RLS on the underlying Supabase tables, the SECURITY DEFINER RPCs for mutations, and requireRole(...) in the server actions. The Allowed roles field is the policy-layer decision that the other layers enforce.

The canonical list of field names the gateway redacts on every payload. Defaults to bvn, nin, account_number, balance, phone, address, date_of_birth for new groups (matches the redactor's baseline in lib/ndpa/redactor.ts).

When to add: your partner API uses a non-standard sensitive field name (e.g., card_pan, id_passport, tax_id). Add the field, save the policy; the next call redacts it.

When to remove: rarely. The defaults are calibrated for Nigerian payment flows; removing a default risks NDPA exposure and triggers a compliance finding in any subsequent audit.

A JSON object that pins specific arguments on every call. The gateway merges the lock onto the call's arguments before dispatch; locked fields cannot be overridden by the agent.

Example: force a per-transaction limit on a transfer tool by locking the maximum amount:

{
  "max_amount": 500000,
  "currency": "NGN"
}

Now every create_charge or initiate_transfer call in this group has max_amount: 500000 and currency: NGN as floors regardless of what the agent asked for. Useful for sandboxing a new integration with a customer where you do not want the agent to be able to send millions of Naira during testing.

Locks are policy-time, not call-time, so they version into tool_group_versions with every other change. A parameter lock change is auditable.

The §7.8 human-in-the-loop gate. When on, every tool call in the group blocks on a 4-digit PIN from the calling user. The modal shows the transaction summary and a 60-second countdown before it auto-cancels.

Default is on for any new group. Turn it off only for groups that genuinely do not move money or otherwise carry irreversible side-effects: read-only verification, status checks, balance enquiries. Full walkthrough in Require human approval for transfers.

Two counters on the gateway. rate_limit_per_minute defaults to 60; rate_limit_per_hour defaults to 1,000. Both apply to the group as a whole; if multiple tools share a group, they share the budget.

Tune them up for high-volume integrations (e.g., a webhook- driven check tool can run at 600/min). Tune them down for high-risk groups where you would rather hit a limit than have a runaway agent.

Hits are visible in the audit log as status: error rows with an explanatory message. The dashboard counts include rate-limited rows so you can spot pressure before customers notice.

How long gateway_logs rows for this group survive before pruning. Three presets in the policy panel:

• 90 days: the regulatory floor. Allowed but flagged in the UI as below the standard CBN AML expectation for financial events.
• 365 days (default): aligns with CBN year-long retention.
• 2,555 days (~7 years): aligns with the FIRS tax horizon. Use for groups that touch invoiced transactions.

The pruner runs nightly. Pruned rows are gone; if you need long-term retention, set 2,555 from the start.

When a call arrives at the gateway, the controls fire in this order. Understanding the order helps when you are tuning the policy:

1. Authentication: the caller's identity is established.
2. Role check: allowed_roles is verified against the caller's role.
3. Rate limit: the per-minute and per-hour counters are checked and incremented.
4. Parameter lock: the policy's parameter_locks are merged into the call arguments.
5. PII redaction: the redactor scrubs pii_mask_keys before logging.
6. HITL gate: if hitl_required, the call blocks for PIN approval.
7. Tool execution: the call is dispatched to the partner MCP server.
8. Audit log write: the redacted payload, redacted-keys list, latency, and status land in gateway_logs.

A failure at any earlier step short-circuits the rest and writes an error row to gateway_logs.

Every save snapshots the previous state into tool_group_versions with the changing user, a timestamp, and an optional change summary. The History panel (top-right of the policy editor) shows the trail newest-first. Click any version to see its JSON snapshot; click Restore to roll back.

A restore is itself a save: it appears as a new version with change_summary: "restored to v3" so the audit trail is preserved end to end.

Three patterns that cover most Tool Groups in Phase 1:

• Payments policy: roles admin, compliance, developer; HITL on; rate limits at default; retention 365; PII keys default; parameter lock with max_amount during pilot.
• Identity verification policy: roles admin, compliance, developer; HITL off (reads only); rate limits higher (200/min for high-volume KYC); retention 365; PII keys default plus any partner-specific id field; no parameter locks.
• Read-only audit policy: roles admin, compliance, developer, auditor; HITL off; rate limits high (300/min); retention 2,555 (CBN AML); PII keys default; no parameter locks.

• Require human approval for transfers covers the HITL gate end to end.
• Read and export the audit log shows how the policy decisions you make here surface to the DPO and to regulators.