Automation
MCP tools reference
These are the tools the MCP server exposes, in both its local and hosted forms. Each one proxies a single management API operation, so the permission a tool needs is the permission that operation needs; the agent's 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.
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 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); 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.
| 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 |
| 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) |
| 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). | read |
caputchin_update_troop_security | Set the force-game ceiling for the troop. | manage |
| 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 (the require-game gate). | read |
caputchin_update_site_security | Toggle the per-key require-game gate. | edit |
caputchin_list_site_sessions | Recent verification sessions for a key. | read |
| 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 |
| 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 |
| 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 |
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-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) |
