---
type: how-to
title: Use o servidor MCP
summary: Conecte um agente de IA ao Caputchin pelo servidor MCP, autentique-o com um token de acesso e conduza a API de gestão em linguagem natural, com um exemplo prático.
---

O servidor MCP do Caputchin deixa um agente de IA (Claude, Cursor ou qualquer cliente do [Model Context Protocol](https://modelcontextprotocol.io)) gerenciar sua conta chamando a mesma [API de gestão](/docs/automation/management-api) 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 [#mint-an-access-token]

O servidor se autentica com um token de acesso da variável de ambiente `CAPUTCHIN_TOKEN`. Qualquer tipo funciona (veja [autenticação na API](/docs/automation/management-api#mint-an-access-token)):

- um [token de acesso pessoal](/docs/account-management/personal-access-token) para controle de conta inteira, ou
- um [token de acesso de equipe](/docs/troops/tokens) 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 `api.caputchin.com/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:

```json
{
  "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:

```bash
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://api.caputchin.com/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):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/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](/docs/audit-logs/overview) 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](/docs/automation/mcp-tools). As ferramentas espelham a API de gestão uma a uma, então a [referência interativa da API](/docs/api-reference) é 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](/docs/automation/mcp-tools): cada ferramenta, sua descrição e a permissão de que precisa.
- [Gerencie o Caputchin pela API](/docs/automation/management-api): a API HTTP que cada ferramenta chama.
- [Use Terraform ou OpenTofu](/docs/automation/terraform): a superfície de infraestrutura como código.
- [Token de acesso pessoal](/docs/account-management/personal-access-token) e [tokens de equipe](/docs/troops/tokens): as credenciais que o servidor usa.