> ## Documentation Index
> Fetch the complete documentation index at: https://docs.garu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Conecte agentes de IA à API Garu com o protocolo MCP
## O que é MCP?
O **Model Context Protocol (MCP)** é um padrão aberto que permite que agentes de IA se conectem a ferramentas e serviços externos. Com o MCP Server da Garu, seu agente pode criar cobranças, consultar transações e gerenciar clientes diretamente pelo chat.
**Por que isso importa?**
* Seu agente de IA entende o contexto do seu código e cria cobranças sem sair do editor
* Menos copy-paste de documentação, mais produtividade
* Funciona com Claude Code, Cursor, Codex, Windsurf e qualquer cliente MCP
**Pré-requisito:** Você precisa de uma chave de API. Veja como obter em
[Autenticação](/api-reference/autenticacao).
## Instalação
Escolha sua ferramenta e siga as instruções:
### Instale o servidor MCP
```bash theme={null}
claude mcp add garu -- npx -y --package=@garuhq/mcp@latest garu-mcp
```
Depois, defina a variável de ambiente `GARU_API_KEY` no seu projeto ou shell:
```bash theme={null}
export GARU_API_KEY=YOUR_API_KEY
```
Adicione ao arquivo `.cursor/mcp.json` do seu projeto:
```json theme={null}
{
"mcpServers": {
"garu": {
"command": "npx",
"args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
"env": {
"GARU_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
```bash theme={null}
codex mcp add garu --env GARU_API_KEY=YOUR_API_KEY -- npx -y --package=@garuhq/mcp@latest garu-mcp
```
Adicione ao arquivo `.windsurf/mcp.json` do seu projeto:
```json theme={null}
{
"mcpServers": {
"garu": {
"command": "npx",
"args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
"env": {
"GARU_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
**Boa prática:** Use sempre `sk_test_` em desenvolvimento. O MCP não distingue
ambientes — quem distingue é a chave. Trocar para `sk_live_` em produção é
responsabilidade sua.
### Teste a conexão
Peça ao agente para executar um comando simples:
```
Liste minhas cobranças recentes
```
Se a conexão estiver funcionando, o agente vai usar a ferramenta `list_charges` e retornar os resultados.
## Transportes
O MCP Server da Garu suporta dois modos de transporte:
| Transporte | Descrição | Quando usar |
| ------------------ | ------------------------------------ | -------------------------------------------------- |
| **stdio** (padrão) | Comunicação via entrada/saída padrão | IDEs locais (Claude Code, Cursor, Codex, Windsurf) |
| **HTTP** | Servidor HTTP com Server-Sent Events | Integrações remotas, servidores web |
O modo **stdio** é o padrão e funciona automaticamente com os comandos de instalação acima. Para usar o modo HTTP:
```bash theme={null}
npx --package=@garuhq/mcp@latest garu-mcp --transport http --port 3100
```
## Catálogo de Ferramentas
O servidor expõe 20 ferramentas que o agente pode usar:
### Produtos
| Ferramenta | Descrição |
| --------------- | --------------------------------------------------------------- |
| `list_products` | Lista os produtos do vendedor autenticado com paginação e busca |
| `get_product` | Consulta um produto pelo UUID |
Para criar uma cobrança você precisa do **UUID do produto**. Use
`list_products` para descobrir os UUIDs disponíveis antes de chamar as
ferramentas de cobrança.
### Cobranças
| Ferramenta | Descrição |
| ---------------------- | ---------------------------------------------------------------------- |
| `create_pix_charge` | Cria uma cobrança PIX. Retorna um QR Code para o cliente pagar |
| `create_boleto_charge` | Cria um boleto bancário. Retorna a linha digitável para pagamento |
| `list_charges` | Lista cobranças do vendedor autenticado com paginação e filtros |
| `get_charge` | Consulta detalhes de uma cobrança pelo ID numérico (inclui o `status`) |
| `refund_charge` | Reembolsa uma cobrança total ou parcialmente (valor em BRL) |
### Clientes
| Ferramenta | Descrição |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `create_customer` | Cadastra um cliente e vincula ao vendedor atual |
| `list_customers` | Lista clientes com paginação, busca e filtro `status: "overdue"` (clientes com cobrança em atraso) |
| `get_customer` | Consulta detalhes de um cliente pelo ID numérico |
| `update_customer` | Atualiza dados de um cliente do vendedor atual |
| `set_customer_billing_email_override` | Define ou limpa o e-mail fixo de cobrança do cliente |
| `delete_customer` | Remove o cliente do vendedor atual (não exclui globalmente) |
Cobranças agendadas
| Ferramenta | Descrição |
| ----------------------------- | -------------------------------------------------------------------------------------- |
| `create_scheduled_charge` | Agenda uma cobrança PIX/Boleto para uma data futura. Valor em BRL decimal |
| `list_scheduled_charges` | Lista com filtros de status (single ou array), cliente, intervalo de datas e busca |
| `get_scheduled_charge` | Detalhes da cobrança + linha do tempo + transações geradas |
| `postpone_scheduled_charge` | Adia para uma nova data; limpa lembretes pendentes |
| `pause_scheduled_charge` | Pausa a cobrança; nenhum lembrete é enviado enquanto pausada |
| `resume_scheduled_charge` | Retoma uma cobrança pausada |
| `mark_paid_scheduled_charge` | Marca como paga (pagamento feito fora do Garu) |
| `charge_now_scheduled_charge` | Dispara a cobrança e o e-mail na hora, sem esperar o vencimento; idempotente por ciclo |
Cobranças agendadas usam **BRL decimal** (`297.50`), não centavos. As
transações geradas (`transactions[]` no detalhe) seguem o padrão Garu de
**centavos**. Converta antes de comparar valores.
## Exemplos de Prompts
Experimente pedir ao seu agente:
```
Liste meus produtos no Garu
```
```
Crie uma cobrança PIX do produto "Curso Avançado" para joao@email.com
```
```
Gere um boleto do produto para maria@email.com
```
```
Liste todas as cobranças do último mês com status "paid"
```
```
Qual o status da cobrança #12345?
```
```
Reembolse a cobrança #67890
```
```
Cadastre um cliente: Maria Silva, maria@email.com, CPF 123.456.789-00
```
```
Atualize o telefone do cliente 42 para (11) 98765-4321
```
```
Agende uma cobrança PIX de R$ 297,50 para o cliente 42, vencimento 15/06
```
```
Quais cobranças estão em atraso?
```
```
Adia a cobrança sch_abc123 para o dia 1 de julho — o cliente pediu mais prazo
```
```
Marque a cobrança sch_abc123 como paga, pagamento via TED em 20/06, comprovante 4472881
```
```
Quanto faturei esse mês? Mostre o total das cobranças pagas.
```
## Resolução de Problemas
Erros comuns ao instalar e usar o MCP Server:
O cliente MCP não está instalado ou não está no `PATH`. Reinstale o
Claude Code/Cursor/Codex/Windsurf seguindo o guia oficial e reabra o
terminal antes de tentar de novo.
Confira se `GARU_API_KEY` está definida no ambiente em que o cliente MCP
está rodando. No Claude Code, o cliente herda o shell — então `export
GARU_API_KEY=...` no `~/.zshrc` (ou `~/.bashrc`) resolve. No Cursor e
Windsurf, a chave fica no campo `env` do `mcp.json`.
Confira também se a chave começa com `sk_test_` ou `sk_live_`. Chaves
antigas ou rotacionadas no dashboard deixam de funcionar imediatamente.
Provavelmente firewall ou proxy corporativo bloqueando
`https://garu.com.br/api`. Adicione `garu.com.br` à lista de exceções da sua
rede ou use uma conexão fora da rede corporativa para testar.
O cliente MCP geralmente carrega o servidor só na primeira conversa. Reinicie
completamente o IDE (não só recarregar a janela). No Claude Code, rode `claude
mcp list` para confirmar que `garu` aparece na lista.
Ambiente Node desatualizado ou sem permissão de escrita no cache do `npx`.
Atualize o Node para 20.x ou superior e rode `npx --yes --package=@garuhq/mcp@latest garu-mcp --version`
uma vez no terminal para popular o cache antes de o cliente MCP tentar.
O MCP usa exatamente a chave que você passou — ele não detecta sozinho
se é teste ou produção. Mantenha chaves de teste no ambiente de
desenvolvimento e revogue qualquer chave `sk_live_` que tenha vazado
para o ambiente local. Cobranças criadas em produção por engano podem
ser canceladas pelo dashboard, ou reembolsadas com `refund_charge` se
já tiverem sido pagas.
## Recursos
Código-fonte e documentação técnica
@garuhq/mcp no npm
## Próximos Passos
Use a Garu direto no terminal
Ensine boas práticas ao seu agente