Skip to main content
Some capabilities reach a real person or cannot be undone. Pramaan marks them, and the MCP server never runs one for an agent without a person saying yes first.

​
Which capabilities need approval

A capability needs approval when either is true:
  • It is listed with requires_approval: true (in the SDK, requiresApproval). These reach or lock out a real person, for example auth.user.ban or auth.invitation.create.
  • Its effect class is external_irreversible or external_unknown_effect: sending to a person, calls, payments, deletes.
Read-only capabilities and reversible ones without the flag run without asking. The API only declares this. A direct API or SDK call runs as usual, so if your own app calls these capabilities, ask your user before you call.

​
Approvals for team members

If your organisation has team members (roles, invites and limits are set in the dashboard), a call made as a member can need an approval that the API itself enforces. Send Pramaan-Member: <member id> to act as a member. A call made as a member needs an approver when the capability needs approval (above), or when its price is over the organisation’s approval threshold. The approver is the member themselves, if they may approve. Otherwise send Pramaan-Approved-By: <member id> naming a member who may approve (GET /v1/members shows may_approve for each). You are telling Pramaan that this person said yes, so ask them first. Without an approver the call is refused with 403 forbidden and error.reason: "approval_required". Check the reason, not the message. A key made for one member can name only that member in Pramaan-Approved-By. In the SDK, pass { member, approvedBy } in the call options. A call with a plain organisation key and no Pramaan-Member is not gated.

​
The rule for agents

Before running a capability that needs approval, show the user exactly what will happen, with the exact inputs, and wait for an explicit yes.

​
What the MCP server does

The MCP server enforces the rule itself:
  1. The agent calls run_capability (or a named tool) for a capability that needs approval.
  2. The server does not run it yet. It asks the person through the MCP client, for example: “Run auth.user.ban (Ban a user …) with these inputs? { "userId": "user_123" } This affects a real person.”
  3. The person ticks “Yes, run it” and accepts: the call runs with exactly those inputs.
  4. They decline, cancel or don’t answer within 10 minutes: nothing runs, and the agent gets { "ran": false, "reason": "declined_by_user" } (or "no_answer").
Every call asks again, so a changed input always needs a new yes. The agent cannot approve on the person’s behalf: an approved argument from the agent is ignored. The question is shown with MCP elicitation. A client that does not support elicitation cannot run these capabilities: the call is refused with the error code approval_required, and the agent is told to ask the user. Run them from a client that supports elicitation, or from your own app after asking your user. Your client’s own tool-call timeout also applies while the question is open.