---
type: reference
title: Referência de ferramentas MCP
summary: Cada ferramenta MCP do Caputchin, o que ela faz e a permissão que seu token precisa ter, agrupadas por área.
---

Estas são as ferramentas que o [servidor MCP](/docs/automation/mcp) expõe, tanto na forma local quanto na hospedada. Cada uma faz proxy de uma única operação da [API de gestão](/docs/automation/management-api), então a permissão de que uma ferramenta precisa é a permissão de que essa operação precisa; o [token](/docs/automation/management-api#mint-an-access-token) do agente precisa tê-la. O catálogo e as descrições vêm do próprio servidor; para o esquema exato de requisição e resposta da operação por trás de uma ferramenta, veja a [referência interativa da API](/docs/api-reference).

## Como as permissões funcionam aqui

Uma ferramenta roda só se o token por trás dela tem permissão de realizar a operação subjacente. A coluna **Permissão** usa estes valores, que mapeiam para o modelo de [permissões e escopo](/docs/troops/permissions) da equipe:

| Valor | Significa |
|---|---|
| **Conta** | Qualquer token válido na conta. Ferramentas de acunhar tokens e assentos exigem adicionalmente uma credencial mestre da conta (uma sessão do painel ou o [token de acesso pessoal](/docs/account-management/personal-access-token)); um token de equipe não consegue acunhar tokens nem assentos. |
| **read** | A permissão `read`. Ferramentas delimitadas a um site também exigem que a chave de site esteja no escopo do token. |
| **create** | A permissão `create` na equipe (criar uma chave de site nela). |
| **edit** | A permissão `edit`, delimitada à chave de site que a ferramenta mira. |
| **manage** | A permissão `manage`: administração da equipe (membros, tokens, configurações de toda a equipe). |

Algumas ferramentas também precisam de um nível de plano, indicado na descrição: white-label é **Apex**, personalização de idioma e skin de jogo é **Alpha em diante**, e registros de auditoria são **Apex**.

## Conta e saúde

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_ping` | Checagem de saúde; retorna o id de conta resolvido quando o token é válido. | Conta |
| `caputchin_get_account` | A conta autenticada (id, e-mail, plano). | Conta |
| `caputchin_me_billing` | Resumo de faturamento (plano, status, período). | Conta |
| `caputchin_get_seats` | Uso de assentos da conta (usados, total, detalhamento). | Conta |

## Tokens e assentos

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_list_tokens` | Lista os tokens da conta; nunca retorna segredos. | Conta |
| `caputchin_create_token` | Acunha um token (`type` troop ou account); valor retornado uma vez. | Conta (mestre) |
| `caputchin_rotate_token` | Rotaciona o segredo de um token; novo valor retornado uma vez. | Conta (mestre) |
| `caputchin_revoke_token` | Revoga um token; efetivo na hora. | Conta (mestre) |
| `caputchin_invite_seat_user` | Convida um usuário para uma equipe (ciente de assentos); consome um assento se novo. | Conta (mestre) |
| `caputchin_remove_seat_user` | Remove um usuário de cada equipe da conta. | Conta (mestre) |
| `caputchin_mint_seat_pat` | Acunha e liga um token de equipe em uma chamada; valor retornado uma vez. | Conta (mestre) |
| `caputchin_attach_seat_pat` | Liga um token de equipe existente a outra equipe. | Conta (mestre) |
| `caputchin_revoke_seat_pat` | Revoga um token de equipe na conta toda. | Conta (mestre) |

## Equipes

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_list_troops` | Lista as equipes da conta. | Conta |
| `caputchin_get_troop` | Uma equipe por id. | read |
| `caputchin_create_troop` | Cria uma equipe compartilhada. | Conta |
| `caputchin_rename_troop` | Renomeia uma equipe. | manage |
| `caputchin_delete_troop` | Exclui uma equipe; recusa se ela ainda detém chaves de site. | manage |
| `caputchin_list_troop_members` | Os membros de uma equipe com suas permissões e escopo. | read |
| `caputchin_add_troop_member` | Adiciona um usuário por e-mail com permissões e escopo; pode consumir um assento. | manage |
| `caputchin_update_troop_member` | Muda as permissões ou o escopo de um membro. | manage |
| `caputchin_remove_troop_member` | Remove um membro; libera o assento se foi o último dele. | manage |
| `caputchin_list_troop_pats` | Os tokens de equipe ligados a uma equipe. | read |
| `caputchin_attach_troop_pat` | Liga um token de equipe com permissões e escopo; consome um assento. | manage |
| `caputchin_update_troop_pat` | Muda as permissões ou o escopo de um token ligado. | manage |
| `caputchin_detach_troop_pat` | Desliga um token de equipe; libera seu assento. | manage |
| `caputchin_get_troop_security` | As configurações de segurança de uma equipe (o teto de forçar jogo mais os padrões de modo Prévia e Reutilização de verificação). | read |
| `caputchin_update_troop_security` | Define o teto de forçar jogo e os padrões de toda a equipe de modo Prévia e Reutilização de verificação. | manage |

## Chaves de site

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_list_sites` | Todas as chaves de site nas equipes da conta. | read |
| `caputchin_get_site` | Uma chave de site por id. | read |
| `caputchin_create_site` | Cria uma chave de site (em uma equipe, ou na Pessoal); retorna o segredo de uso único. | create |
| `caputchin_update_site` | Atualiza o nome ou o flag de desativada de uma chave. | edit |
| `caputchin_delete_site` | Exclui uma chave; cascata para sessões e config. Irreversível. | edit |
| `caputchin_rotate_site_secret` | Rotaciona o segredo; o antigo para na hora; o novo retornado uma vez. | edit |
| `caputchin_get_site_cap_config` | A config de proof-of-work de uma chave. | read |
| `caputchin_update_site_cap_config` | Atualiza a config de proof-of-work. | edit |
| `caputchin_get_site_security` | As configurações de segurança de uma chave (o portão de exigir jogo, o modo Prévia e a Reutilização de verificação). | read |
| `caputchin_update_site_security` | Liga ou desliga por chave o portão de exigir jogo, o modo Prévia e a Reutilização de verificação. | edit |
| `caputchin_list_site_sessions` | Sessões de verificação recentes de uma chave. | read |

## Verificação hospedada

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_get_hosted_verification` | A config de verificação hospedada de uma chave. | read |
| `caputchin_set_hosted_verification` | Define o flag de ativação e os destinos. | edit |
| `caputchin_test_hosted_verification` | Dispara uma entrega sintética aos destinos configurados. | edit |

## Estatísticas, entrega e registros de auditoria

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_site_stats` | Estatísticas de verificação do site em um intervalo. | read |
| `caputchin_site_stats_dashboard` | Resumo de painel das estatísticas do site. | read |
| `caputchin_site_stats_activity` | Série de atividade das estatísticas do site. | read |
| `caputchin_site_stats_durations` | Percentis de tempo das estatísticas do site. | read |
| `caputchin_site_stats_rejections` | Contagens de rejeição do site. | read |
| `caputchin_troop_stats` | Totais vitalícios das estatísticas da equipe. | read |
| `caputchin_troop_stats_dashboard` | Resumo de painel das estatísticas da equipe. | read |
| `caputchin_troop_stats_activity` | Série de atividade das estatísticas da equipe. | read |
| `caputchin_troop_stats_durations` | Percentis de tempo das estatísticas da equipe. | read |
| `caputchin_troop_stats_rejections` | Contagens de rejeição da equipe. | read |
| `caputchin_quick_stats_sites` | Instantâneo compacto de estatísticas por site na conta. | read |
| `caputchin_quick_stats_troops` | Instantâneo compacto de estatísticas por equipe na conta. | read |
| `caputchin_site_delivery_dashboard` | Estatísticas de entrega da verificação hospedada de um site. Apex. | read |
| `caputchin_troop_delivery_dashboard` | Estatísticas de entrega da verificação hospedada de uma equipe. Apex. | read |
| `caputchin_account_audit_logs` | Registro de auditoria no nível da conta. Apex. | Conta |
| `caputchin_troop_audit_logs` | Registro de auditoria da equipe. Apex. | read |
| `caputchin_site_audit_logs` | Registro de auditoria da chave de site. Apex. | read |

## Jogos do marketplace

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_list_games` | Lista os jogos do marketplace. | Conta |
| `caputchin_search_games` | Busca jogos do marketplace por texto. | Conta |
| `caputchin_get_game` | Um jogo do marketplace por id. | Conta |

## Personalização de jogo

Estas miram um escopo (uma chave de site ou uma equipe), então uma mudança no escopo de site precisa de `edit` naquela chave e uma mudança em toda a equipe precisa de `manage`. Personalização de idioma e skin é **Alpha em diante**.

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_list_customized_games` | Os jogos registrados (instalados) de um escopo. | read |
| `caputchin_register_customized_game` | Registra (instala) um jogo em um escopo; fixa um instantâneo. | edit (site) ou manage (equipe) |
| `caputchin_repin_customized_game` | Refixa um jogo registrado para a versão mais recente. | edit (site) ou manage (equipe) |
| `caputchin_update_customized_game` | Atualiza as configurações de um jogo registrado (atualização automática). | edit (site) ou manage (equipe) |
| `caputchin_delete_customized_game` | Desinstala um jogo registrado de um escopo. | edit (site) ou manage (equipe) |
| `caputchin_list_game_presets` | Presets de personalização para um escopo e jogo. | read |
| `caputchin_set_game_preset` | Cria ou atualiza um preset de jogo. Alpha+. | edit (site) ou manage (equipe) |
| `caputchin_delete_game_preset` | Exclui um preset de jogo. Alpha+. | edit (site) ou manage (equipe) |
| `caputchin_set_game_default` | Define o preset de jogo padrão para um eixo. Alpha+. | edit (site) ou manage (equipe) |
| `caputchin_get_custom_game_schema` | O esquema de campos de um jogo personalizado para um escopo. | read |
| `caputchin_set_custom_game_schema` | Define o esquema de campos de um jogo personalizado. Alpha+. | edit (site) ou manage (equipe) |
| `caputchin_delete_custom_game_schema` | Exclui o esquema de campos de um jogo personalizado. Alpha+. | edit (site) ou manage (equipe) |
| `caputchin_upload_custom_game_run` | Faz upload do artefato de execução headless de um jogo personalizado. | edit (site) ou manage (equipe) |
| `caputchin_get_custom_game_run` | Obtém a referência do artefato de execução armazenado de um jogo personalizado. | read |
| `caputchin_delete_custom_game_run` | Exclui o artefato de execução de um jogo personalizado. | edit (site) ou manage (equipe) |

## White-label

White-label do shell do widget é um recurso **Apex**. Como na personalização de jogo, uma mudança no escopo de site precisa de `edit` e uma em toda a equipe precisa de `manage`.

| Ferramenta | Faz | Permissão |
|---|---|---|
| `caputchin_list_white_label_presets` | Presets de white-label de um escopo. | read |
| `caputchin_set_white_label_preset` | Cria ou atualiza um preset de white-label. Apex. | edit (site) ou manage (equipe) |
| `caputchin_delete_white_label_preset` | Exclui um preset de white-label. Apex. | edit (site) ou manage (equipe) |
| `caputchin_set_white_label_default` | Define o preset de white-label padrão para um eixo. Apex. | edit (site) ou manage (equipe) |

## Veja também

- [Use o servidor MCP](/docs/automation/mcp): conectar um agente por qualquer transporte.
- [Permissões e escopo](/docs/troops/permissions): o modelo read / create / edit / manage que a tabela acima usa.
- [Referência interativa da API](/docs/api-reference): o esquema exato da operação por trás de cada ferramenta.