> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proofage.net/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference

> Every tool the ProofAge MCP server offers, what it does, and which roles see it.

The server lists only the tools your role may use; see [who you are on the server](/integration/mcp/overview#who-you-are-on-the-server). Tools whose names start with `prepare-` and `confirm-` are the two steps of a destructive action.

The descriptions below are the ones your assistant reads.

| Tool | What it does | Roles |
| - | - | - |
| `activate-secret-key` | Make a secret key the active one: webhooks are signed with the active key, so the customer's webhook handler must verify with it before this runs. On a test workspace it is applied. On a live workspace NOTHING is applied: the answer is a preview with a challenge\_token for confirm-live-workspace-change. | Administrator, Developer |
| `confirm-block-verification-face` | Block a verification face using a short-lived challenge token. Requires the exact confirmation phrase BLOCK\_FACE and a reason. The action, actor and reason are logged. | Administrator, Developer, Support specialist |
| `confirm-live-workspace-change` | Apply a change to a live workspace that update-workspace, activate-secret-key or delete-secret-key previewed. Pass the workspace\_id and challenge\_token from the preview, the exact confirmation phrase APPLY\_LIVE\_CHANGE, and a reason; the preview's own values are applied, nothing else. The token is single-use and expires after 10 minutes. STALE\_PREVIEW means the workspace changed since the preview: preview again. LIVE\_WORKSPACE\_IN\_USE means a suspension met new traffic since the preview. Either way the token is spent. The action, actor and reason are logged. | Administrator, Developer |
| `confirm-purge-personal-data` | IRREVERSIBLE. Erase a verification's personal data using the challenge token from prepare-purge-personal-data, the exact confirmation phrase PURGE\_PERSONAL\_DATA, a reason code and a written reason. Media, document fields and raw results are removed; the decision, dates and audit trail stay. Only for a real request to erase - never to tidy up. | Administrator, Support specialist |
| `confirm-unblock-verification-face` | Unblock a verification face using a short-lived challenge token. Requires the exact confirmation phrase UNBLOCK\_FACE and a reason. The action, actor and reason are logged. | Administrator, Developer, Support specialist |
| `correct-document-fields` | Correct document fields the reader got wrong on an approved, declined or in-review verification. `fields` maps field names to corrected values: dates YYYY-MM-DD, nationality ISO alpha-2, gender F\|M\|X; null removes a correction and brings the recognised value back. Age workspaces take first\_name, last\_name, date\_of\_birth and document\_number; KYC workspaces take all eleven. The status does not change and no check is re-run; the recognised values are kept. A data.updated webhook with the corrected document and changed\_fields is sent to the workspace's webhook\_url. Read the result back with get-verification or list-verifications (select: document). | Administrator, Support specialist |
| `create-secret-key` | Create an inactive secret key in a workspace, for rotating keys. Every workspace already has an active "Default Key", so this is not needed for first setup. At most 5 keys per workspace, the default one included. Any non-deleted key can sign API requests; only the active key signs webhooks (see activate-secret-key). On a test workspace the secret is returned; on a live workspace it never is, and secret\_console\_url is where a person copies it. | Administrator, Developer |
| `create-verification` | Create a verification session in one of the workspaces (see list-workspaces) and return the URL the person opens to verify, together with the same fields the public API returns on POST /v1/verifications (`id`, `status`, `redirect_url`, `external_id`, `external_metadata`, ...). `redirect_url` is where the person is sent after finishing; without it the workspace default applies. `external_id` and `external_metadata` are echoed back by the API and in webhooks, so put the caller's own references there; `metadata` is internal to the session. A live workspace charges for the session once it is submitted; a test workspace never does. `console_url` opens the session in the admin UI. Each user may create 10 sessions a minute and 100 a day, links made in the console included; past that the tool answers THROTTLED with `retry_after_seconds`. | Administrator, Developer, Support specialist |
| `create-workspace` | Create a workspace in the tenant and return its integration guide (public key, API URL, SDK parameters, webhook signing, checklist). mode (test\|live) and flow\_type (kyc\|age) are fixed for the workspace's lifetime: going live means creating a second workspace with mode live and swapping its keys into the integration. An age workspace needs age\_mode (estimation\|document\_verification) and age\_threshold (exactly 18 for estimation, 16-25 for document\_verification). A test workspace returns its secret keys; a live workspace never does, and returns secret\_console\_url where a person copies the active key. Each user may create 5 workspaces a minute and 20 a day. | Administrator, Developer |
| `delete-secret-key` | Delete an inactive secret key: API requests signed with it stop being accepted. The active key cannot be deleted; activate another one first. On a test workspace it is applied. On a live workspace NOTHING is applied: the answer is a preview with a challenge\_token for confirm-live-workspace-change. | Administrator, Developer |
| `get-integration-guide` | Everything needed to integrate one workspace: its settings, the API base URL and public key (pk\_...), its secret keys, SDK loader parameters, how webhooks are signed, a checklist of where the integration stands, and next steps. On a test workspace the secret keys carry their secret; on a live workspace they never do, and secret\_console\_url is where a person copies the active key. Detailed docs are the proofage://docs/... resources. | Administrator, Developer |
| `get-verification` | Get the full detail of a single verification, including media (videos excluded), exactly as shown in the admin UI. The authoritative outcome reason is `decision.final_reason` (with `reason_label`/`severity`/`scope`); `result_summary` is a non-authoritative pipeline snapshot that can be stale — do not read the decline/resubmit reason from it. | Administrator, Developer, Support specialist |
| `get-verification-stats` | The dashboard's figures, exactly: verifications completed per day (against the previous period), and how people's efforts to get through ended - approved on the 1st, 2nd or later attempt, approved after review, declined, abandoned, in progress - with the share approved on the first attempt, per workspace. The resubmission figures count people, merged by external\_id, each on the day of their final outcome; the volume figures stay per verification, on the day it was first sent for a decision. Counts live workspaces shown on the dashboard; default period is the last 7 whole days ending yesterday, max 31. For raw status counts by creation date across every workspace (test included), or by email or external\_id, use list-verifications with group\_by instead. | Administrator, Developer, Support specialist |
| `get-webhook-delivery-request` | For a webhook delivery in a TEST workspace, return the exact HTTP request ProofAge sends, signed now with the workspace's active secret key: method, headers (including X-HMAC-Signature and X-Timestamp) and the raw body. Use it to replay the webhook against a handler on localhost, e.g. with curl --data-raw. Send the body byte for byte: a re-serialised body fails signature verification, as it should. A handler following the ProofAge guide rejects timestamps older than 300 seconds, so replay promptly or fetch again. Delivery ids come from list-webhook-deliveries. | Administrator, Developer |
| `list-blocked-faces` | List blocked faces, including who blocked them and why. `reason_code` is the structured reason a person picked when blocking (`reason_label` is its wording); `reason` beside it is free-text detail, required only when the code is `other`. A null code means the block predates the reason catalog, was propagated by a device match, or came through the public API without one — unrecorded, not ungrounded. The reason codes a row can carry: `presentation_attack` (Spoof attempt (screen / print / mask)) — the selfie or document was photographed from a screen, a print, or a mask; `fraudulent_document` (Fraudulent or tampered document) — the document is forged, edited, or not a real identity document; `scam_or_abuse` (Scam or abusive behaviour on the platform) — the identity may be genuine — the person is blocked for what they did on the vendor's platform; `underage` (Underage user) — the person is below the age the workspace verifies for; `other` (Other) — anything the other codes do not cover, explained in the comment. | Administrator, Developer, Support specialist |
| `list-verifications` | List verifications with optional filters. The date range may not exceed 31 days. For the dashboard's figures and the share approved on the first attempt use get-verification-stats. To break the rows down by raw status use `group_by: "status"` — `counts` keyed by every status in ONE call, no per-row data, by the day a verification was created, across every workspace (test included), and it honours the email, external\_id and workspace filters; it is not the dashboard's count. `per_page` is capped at 50, so do not try to cover a large `total` in a single unfiltered page — use `group_by` for counts, or page through for rows. To list rows for several statuses at once, pass `statuses` (array) rather than calling once per status. Use `select` to project extra per-item field groups (e.g. \["age"], \["document","smart\_signals"]) instead of calling get-verification per row; pass \["**catalog**"] alone to discover available groups. The authoritative outcome reason is `decision.final_reason` (with `reason_label`/`severity`/`scope`); `result_summary` is a non-authoritative pipeline snapshot that can be stale — do not read the decline/resubmit reason from it. | Administrator, Developer, Support specialist |
| `list-webhook-deliveries` | List the webhook deliveries sent to this organization's endpoints, newest first, as on the admin Webhooks page: endpoint URL, delivery `status` (pending, success, failed, completed, skipped), attempt count, the endpoint's HTTP code and response body (cut at 2000 characters), the last attempt's record without request headers, and the verification it was about. Filter by verification, workspace, status, response code group or creation date. `can_retry` says whether retry-webhook-delivery will accept it; any delivery can be resent with resend-webhook-delivery. Pass `include_payload: true` for the exact body that was sent, in `payload` and in the last attempt's `request_body`. | Administrator, Developer, Support specialist |
| `list-workspaces` | List the available workspaces. | Administrator, Developer, Support specialist |
| `prepare-block-verification-face` | Preview blocking a verification face and return a short-lived one-time challenge token to be passed to confirm-block-verification-face. | Administrator, Developer, Support specialist |
| `prepare-purge-personal-data` | Irreversible once confirmed: preview erasing a verification's personal data (media, document fields, raw results, device data) and return a short-lived one-time challenge token for confirm-purge-personal-data. The decision, dates and audit trail stay. Nothing is erased by this call. | Administrator, Support specialist |
| `prepare-unblock-verification-face` | Preview unblocking a verification face and return a short-lived one-time challenge token to be passed to confirm-unblock-verification-face. | Administrator, Developer, Support specialist |
| `resend-webhook-delivery` | Send a fresh copy of any webhook delivery to the same endpoint, as the Resend button on the admin Webhooks page does: a new delivery is created with the same payload (fingerprint signals refreshed) and queued, and the original is left untouched. Use it to replay an event while testing an endpoint. Returns the new delivery; follow it with list-webhook-deliveries. Retries and resends together are limited to 10 a minute and 100 a day per user. | Administrator, Developer |
| `retry-webhook-delivery` | Queue a failed webhook delivery to be sent again to the same endpoint, as the Retry button on the admin Webhooks page does. Only a delivery in status `failed` with fewer than 4 attempts can be retried (`can_retry` in list-webhook-deliveries); for anything else use resend-webhook-delivery, which sends a fresh copy. Retries and resends together are limited to 10 a minute and 100 a day per user. | Administrator, Developer |
| `set-test-verification-outcome` | Set the final status of a verification in a TEST workspace: approved, declined or resubmission\_requested. A test submission skips analysis and waits in review; this finishes it and sends the outcome webhook, so the integration's webhook handler can be exercised. Only works from submitted or review, i.e. after a person finished the widget (INVALID\_STATUS otherwise). test\_reason is recorded for resubmission\_requested. The webhook is queued: find its delivery with list-webhook-deliveries shortly after, then replay it locally with get-webhook-delivery-request. Each user may set 30 outcomes a minute. | Administrator, Developer |
| `update-workspace` | Change any subset of a workspace's settings: name, redirect\_url, webhook\_url, external\_profile\_url\_template, allow\_expired\_documents, allow\_duplicate\_accounts, status (active\|suspended), and on an age workspace age\_mode and age\_threshold. mode and flow\_type cannot change. A suspended workspace answers every /v1 request with 403 and its open sessions fail; a live workspace can be suspended here only after 24 hours without a new verification (LIVE\_WORKSPACE\_IN\_USE otherwise; a person can do it in the console). Pass null to clear a URL. On a test workspace the change is applied and the integration guide returned. On a live workspace NOTHING is applied: the answer has requires\_confirmation true, the diff, and a challenge\_token for confirm-live-workspace-change. Show the diff to the person before confirming. | Administrator, Developer |

## Resources

Besides tools, the server offers the developer documentation as resources under `proofage://docs/…`, and the OpenAPI specification as `proofage://docs/openapi.json`, so an assistant can read how the API works before writing code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.