---
type: reference
title: MCP tools reference
summary: Every Caputchin MCP tool, what it does, and the permission its token must hold, grouped by area.
---

These are the tools the [MCP server](/docs/automation/mcp) exposes, in both its local and hosted forms. Each one proxies a single [management API](/docs/automation/management-api) operation, so the permission a tool needs is the permission that operation needs; the agent's [token](/docs/automation/management-api#mint-an-access-token) must hold it. The catalogue and descriptions come from the server itself; for the exact request and response schema of the operation behind a tool, see the [interactive API reference](/docs/api-reference).

## How permissions work here

A tool runs only if the token behind it is allowed to perform the underlying operation. The **Permission** column uses these values, which map to the troop [permissions and scope](/docs/troops/permissions) model:

| Value | Means |
|---|---|
| **Account** | Any valid token on the account. Token- and seat-minting tools additionally require an account-master credential (a dashboard session or the [personal access token](/docs/account-management/personal-access-token)); a troop token cannot mint tokens or seats. |
| **read** | The `read` permission. Site-scoped tools also require the site key to be in the token's scope. |
| **create** | The `create` permission on the troop (creating a site key in it). |
| **edit** | The `edit` permission, scoped to the site key the tool targets. |
| **manage** | The `manage` permission: troop administration (members, tokens, troop-wide settings). |

A few tools also need a plan tier, noted in the description: white-labeling is **Apex**, game language and skin customization is **Alpha and up**, and audit logs are **Apex**.

## Account and health

| Tool | Does | Permission |
|---|---|---|
| `caputchin_ping` | Health check; returns the resolved account id when the token is valid. | Account |
| `caputchin_get_account` | The authenticated account (id, email, plan). | Account |
| `caputchin_me_billing` | Billing summary (plan, status, period). | Account |
| `caputchin_get_seats` | Seat usage for the account (used, total, breakdown). | Account |

## Tokens and seats

| Tool | Does | Permission |
|---|---|---|
| `caputchin_list_tokens` | List the account's tokens; never returns secrets. | Account |
| `caputchin_create_token` | Mint a token (`type` troop or account); value returned once. | Account (master) |
| `caputchin_rotate_token` | Rotate a token's secret; new value returned once. | Account (master) |
| `caputchin_revoke_token` | Revoke a token; effective immediately. | Account (master) |
| `caputchin_invite_seat_user` | Invite a user to a troop (seat-aware); consumes a seat if new. | Account (master) |
| `caputchin_remove_seat_user` | Remove a user from every troop in the account. | Account (master) |
| `caputchin_mint_seat_pat` | Mint and attach a troop token in one call; value returned once. | Account (master) |
| `caputchin_attach_seat_pat` | Attach an existing troop token to another troop. | Account (master) |
| `caputchin_revoke_seat_pat` | Revoke a troop token across the account. | Account (master) |

## Troops

| Tool | Does | Permission |
|---|---|---|
| `caputchin_list_troops` | List the account's troops. | Account |
| `caputchin_get_troop` | One troop by id. | read |
| `caputchin_create_troop` | Create a shared troop. | Account |
| `caputchin_rename_troop` | Rename a troop. | manage |
| `caputchin_delete_troop` | Delete a troop; refuses if it still owns site keys. | manage |
| `caputchin_list_troop_members` | A troop's members with their perms and scope. | read |
| `caputchin_add_troop_member` | Add a user by email with perms and scope; may consume a seat. | manage |
| `caputchin_update_troop_member` | Change a member's perms or scope. | manage |
| `caputchin_remove_troop_member` | Remove a member; frees their seat if it was their last. | manage |
| `caputchin_list_troop_pats` | The troop tokens attached to a troop. | read |
| `caputchin_attach_troop_pat` | Attach a troop token with perms and scope; consumes a seat. | manage |
| `caputchin_update_troop_pat` | Change an attached token's perms or scope. | manage |
| `caputchin_detach_troop_pat` | Detach a troop token; frees its seat. | manage |
| `caputchin_get_troop_security` | A troop's security settings (the force-game ceiling plus the preview-mode and verification-reuse defaults). | read |
| `caputchin_update_troop_security` | Set the force-game ceiling and the troop-wide preview-mode and verification-reuse defaults. | manage |

## Site keys

| Tool | Does | Permission |
|---|---|---|
| `caputchin_list_sites` | All site keys across the account's troops. | read |
| `caputchin_get_site` | One site key by id. | read |
| `caputchin_create_site` | Create a site key (in a troop, or Personal); returns the one-time secret. | create |
| `caputchin_update_site` | Update a key's name or disabled flag. | edit |
| `caputchin_delete_site` | Delete a key; cascades sessions and config. Irreversible. | edit |
| `caputchin_rotate_site_secret` | Rotate the secret; old one stops at once; new returned once. | edit |
| `caputchin_get_site_cap_config` | A key's proof-of-work config. | read |
| `caputchin_update_site_cap_config` | Update the proof-of-work config. | edit |
| `caputchin_get_site_security` | A key's security settings (require-game gate, preview mode, and verification reuse). | read |
| `caputchin_update_site_security` | Toggle the per-key require-game gate, preview mode, and verification reuse. | edit |
| `caputchin_list_site_sessions` | Recent verification sessions for a key. | read |

## Hosted verification

| Tool | Does | Permission |
|---|---|---|
| `caputchin_get_hosted_verification` | A key's hosted-verification config. | read |
| `caputchin_set_hosted_verification` | Set the enable flag and destinations. | edit |
| `caputchin_test_hosted_verification` | Fire a synthetic delivery at the configured destinations. | edit |

## Statistics, delivery, and audit logs

| Tool | Does | Permission |
|---|---|---|
| `caputchin_site_stats` | Site verification stats over a range. | read |
| `caputchin_site_stats_dashboard` | Site stats dashboard rollup. | read |
| `caputchin_site_stats_activity` | Site stats activity series. | read |
| `caputchin_site_stats_durations` | Site stats timing percentiles. | read |
| `caputchin_site_stats_rejections` | Site rejection counts. | read |
| `caputchin_troop_stats` | Troop stats lifetime totals. | read |
| `caputchin_troop_stats_dashboard` | Troop stats dashboard rollup. | read |
| `caputchin_troop_stats_activity` | Troop stats activity series. | read |
| `caputchin_troop_stats_durations` | Troop stats timing percentiles. | read |
| `caputchin_troop_stats_rejections` | Troop rejection counts. | read |
| `caputchin_quick_stats_sites` | Compact per-site stats snapshot across the account. | read |
| `caputchin_quick_stats_troops` | Compact per-troop stats snapshot across the account. | read |
| `caputchin_site_delivery_dashboard` | Hosted-verification delivery stats for a site. Apex. | read |
| `caputchin_troop_delivery_dashboard` | Hosted-verification delivery stats for a troop. Apex. | read |
| `caputchin_account_audit_logs` | Account-level audit log. Apex. | Account |
| `caputchin_troop_audit_logs` | Troop audit log. Apex. | read |
| `caputchin_site_audit_logs` | Site-key audit log. Apex. | read |

## Marketplace games

| Tool | Does | Permission |
|---|---|---|
| `caputchin_list_games` | List marketplace games. | Account |
| `caputchin_search_games` | Search marketplace games by text. | Account |
| `caputchin_get_game` | One marketplace game by id. | Account |

## Game customization

These target a scope (a site key or a troop), so a site-scoped change needs `edit` on that key and a troop-wide change needs `manage`. Language and skin customization is **Alpha and up**.

| Tool | Does | Permission |
|---|---|---|
| `caputchin_list_customized_games` | A scope's registered (installed) games. | read |
| `caputchin_register_customized_game` | Register (install) a game on a scope; pins a snapshot. | edit (site) or manage (troop) |
| `caputchin_repin_customized_game` | Re-pin a registered game to the latest version. | edit (site) or manage (troop) |
| `caputchin_update_customized_game` | Update a registered game's settings (auto-update). | edit (site) or manage (troop) |
| `caputchin_delete_customized_game` | Uninstall a registered game from a scope. | edit (site) or manage (troop) |
| `caputchin_list_game_presets` | Customization presets for a scope and game. | read |
| `caputchin_set_game_preset` | Create or update a game preset. Alpha+. | edit (site) or manage (troop) |
| `caputchin_delete_game_preset` | Delete a game preset. Alpha+. | edit (site) or manage (troop) |
| `caputchin_set_game_default` | Set the default game preset for an axis. Alpha+. | edit (site) or manage (troop) |
| `caputchin_get_custom_game_schema` | A custom game's field schema for a scope. | read |
| `caputchin_set_custom_game_schema` | Set a custom game's field schema. Alpha+. | edit (site) or manage (troop) |
| `caputchin_delete_custom_game_schema` | Delete a custom game's field schema. Alpha+. | edit (site) or manage (troop) |
| `caputchin_upload_custom_game_run` | Upload a custom game's headless run artifact. | edit (site) or manage (troop) |
| `caputchin_get_custom_game_run` | Get a custom game's stored run artifact reference. | read |
| `caputchin_delete_custom_game_run` | Delete a custom game's run artifact. | edit (site) or manage (troop) |

## White-label

White-labeling the widget shell is an **Apex** feature. As with game customization, a site-scoped change needs `edit` and a troop-wide one needs `manage`.

| Tool | Does | Permission |
|---|---|---|
| `caputchin_list_white_label_presets` | White-label presets for a scope. | read |
| `caputchin_set_white_label_preset` | Create or update a white-label preset. Apex. | edit (site) or manage (troop) |
| `caputchin_delete_white_label_preset` | Delete a white-label preset. Apex. | edit (site) or manage (troop) |
| `caputchin_set_white_label_default` | Set the default white-label preset for an axis. Apex. | edit (site) or manage (troop) |

## See also

- [Use the MCP server](/docs/automation/mcp): connecting an agent over either transport.
- [Permissions and scope](/docs/troops/permissions): the read / create / edit / manage model the table above uses.
- [Interactive API reference](/docs/api-reference): the exact schema of the operation behind each tool.