MCP Server

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.

Instalação

Escolha sua ferramenta e siga as instruções:

Instale o servidor MCP

Claude Code

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:

export GARU_API_KEY=YOUR_API_KEY

Cursor

Adicione ao arquivo .cursor/mcp.json do seu projeto:

{
  "mcpServers": {
    "garu": {
      "command": "npx",
      "args": ["-y", "--package=@garuhq/mcp@latest", "garu-mcp"],
      "env": {
        "GARU_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Codex

codex mcp add garu --env GARU_API_KEY=YOUR_API_KEY -- npx -y --package=@garuhq/mcp@latest garu-mcp

Windsurf

Adicione ao arquivo .windsurf/mcp.json do seu projeto:

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

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 <UUID> 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:

`command not found: claude` (ou cursor, codex, windsurf)

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.

`Invalid API key` ou `401 Unauthorized`

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.

`network timeout` ao executar uma ferramenta

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 agente não vê as ferramentas da Garu

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.

`permission denied` ao executar `npx`

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 agente criou uma cobrança no ambiente errado

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.

O que é MCP?

Instalação

Transportes

Catálogo de Ferramentas

Produtos

Cobranças

Clientes

Cobranças agendadas

Exemplos de Prompts

Resolução de Problemas

Recursos

Repositório GitHub

Pacote npm

Próximos Passos

CLI

Skills

Documentation Index

​O que é MCP?

​Instalação

​Transportes

​Catálogo de Ferramentas

​Produtos

​Cobranças

​Clientes

​Cobranças agendadas

​Exemplos de Prompts

​Resolução de Problemas

​Recursos

Repositório GitHub

Pacote npm

​Próximos Passos

CLI

Skills

O que é MCP?

Instalação

Transportes

Catálogo de Ferramentas

Produtos

Cobranças

Clientes

Cobranças agendadas

Exemplos de Prompts

Resolução de Problemas

Recursos

Próximos Passos