Use o servidor MCP

O servidor MCP do Caputchin deixa um agente de IA (Claude, Cursor ou qualquer cliente do Model Context Protocol) gerenciar sua conta chamando a mesma API de gestão que o painel usa. O servidor é um shell fino de transporte e autenticação: ele expõe uma ferramenta MCP por operação de gestão e faz proxy de cada chamada para a API. Então o agente consegue fazer tudo o que você consegue, salvo faturamento, em linguagem natural.

Acune um token de acesso

O servidor se autentica com um token de acesso da variável de ambiente CAPUTCHIN_TOKEN. Qualquer tipo funciona (veja autenticação na API):

um token de acesso pessoal para controle de conta inteira, ou
um token de acesso de equipe para delimitar o agente a certas equipes com menor privilégio, que é o padrão mais seguro ao entregar acesso a um agente autônomo.

Copie o token na criação; ele é mostrado uma vez.

Duas formas de conectar

Há dois transportes, e eles expõem as mesmas ferramentas apoiadas na mesma API de gestão. Escolha conforme como seu cliente conecta:

	Local (stdio)	Hospedado (HTTP)
O que é	O pacote `@caputchin/mcp`, rodado na sua máquina	Um endpoint remoto em `caputchin.com/api/mcp`
O cliente precisa	Iniciar um processo local (stdio)	Conectar a um servidor MCP remoto (HTTP)
Autenticação	`CAPUTCHIN_TOKEN` no ambiente do processo	Cabeçalho `Authorization: Bearer` na conexão
Melhor quando	Dev local, um cliente desktop, sem rede de entrada	Um agente hospedado, sem processo local para iniciar

Local: o servidor npx (stdio)

O servidor é publicado como @caputchin/mcp no npm. Você normalmente não o roda na mão; você o conecta na config do seu cliente MCP e ele é iniciado por stdio, com o token no seu ambiente:

{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}

Para checar que ele roda, inicie-o diretamente; ele fala MCP por stdio e sai com um erro se o token estiver faltando:

CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp

Hospedado: o endpoint HTTP

Para clientes que conectam a um servidor MCP remoto em vez de iniciar um local, o Caputchin hospeda o mesmo servidor em:

https://caputchin.com/api/mcp

Ele se autentica com seu token como um cabeçalho Bearer na conexão (a mesma credencial, só que passada por HTTP em vez do ambiente):

{
  "mcpServers": {
    "caputchin": {
      "url": "https://caputchin.com/api/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}

O formato exato da config depende do seu cliente MCP; o que importa é a URL e o cabeçalho Authorization: Bearer. Nada para instalar, e nenhum processo local; a troca é que o token viaja para o endpoint hospedado a cada requisição em vez de ficar no ambiente de um processo local.

As ferramentas

Cada ferramenta se chama caputchin_<verb>_<noun> e mapeia para uma operação de gestão, por exemplo caputchin_list_troops, caputchin_create_site, caputchin_rotate_site_secret, caputchin_add_troop_member, caputchin_site_stats. O agente descobre o conjunto completo e os parâmetros de cada ferramenta automaticamente por MCP, então você descreve o objetivo e o agente escolhe as ferramentas.

Um exemplo prático

Com o servidor conectado ao seu cliente, você pode pedir ao agente em linguagem simples:

"Crie uma chave de site chamada shop-frontend na minha equipe shop-team, depois ligue o portão de jogo para ela."

O agente resolve isso em uma sequência de chamadas de ferramenta: caputchin_list_troops para achar o id da equipe, caputchin_create_site com esse troop_id, depois caputchin_update_site_security para exigir um jogo. Cada chamada bate na API de gestão sob seu token, e no Apex cada uma cai no seu registro de auditoria atribuída ao token, então as ações de um agente são tão rastreáveis quanto as de uma pessoa.

Como o agente age com todo o alcance do seu token, prefira um token de equipe delimitado quando puder, e revogue-o no instante em que a tarefa termina.

A referência completa

Para a lista completa de ferramentas, cada uma com uma descrição de uma linha e a permissão que seu token precisa ter, veja a referência de ferramentas MCP. As ferramentas espelham a API de gestão uma a uma, então a referência interativa da API é a descrição autoritativa dos parâmetros e da resposta de cada operação: leia a descrição MCP de uma ferramenta para o resumo voltado ao agente, e a referência da API para o esquema exato.

Veja também

Referência de ferramentas MCP: cada ferramenta, sua descrição e a permissão de que precisa.
Gerencie o Caputchin pela API: a API HTTP que cada ferramenta chama.
Use Terraform ou OpenTofu: a superfície de infraestrutura como código.
Token de acesso pessoal e tokens de equipe: as credenciais que o servidor usa.

Use o servidor MCP

Nesta página