MCP Server - Korbit

O MCP server da Korbit (@korbitbr/mcp) conecta seus assistentes de IA à API Korbit: consultar saldo, criar cobrança PIX, cadastrar cliente, acompanhar saques e contestações — direto da conversa.

Segurança por padrão: as ferramentas que movimentam dinheiro (solicitar saque, criar refund, cadastrar beneficiário, cancelar assinatura) ficam desligadas até você definir KORBIT_MCP_ENABLE_MONEY_MOVEMENT=true. Sem a flag, elas nem aparecem para o agente. Ligue a flag apenas quando confiar no cliente MCP — e comece sempre por uma chave kbt_test_.

Instalação

Não precisa clonar nem compilar — o servidor roda via npx:

npx -y @korbitbr/mcp

Você precisa de uma chave de API. O ambiente é derivado do prefixo: kbt_test_… usa o sandbox, kbt_live_… usa produção.

Claude Desktop

Em claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "korbit": {
      "command": "npx",
      "args": ["-y", "@korbitbr/mcp"],
      "env": { "KORBIT_API_KEY": "kbt_test_EXEMPLO_NAO_USAR" }
    }
  }
}

Cursor

Em ~/.cursor/mcp.json — mesma estrutura do Claude Desktop, com "mcpServers": { "korbit": { ... } }.

Claude Code / Codex CLI

claude mcp add korbit --env KORBIT_API_KEY=kbt_test_EXEMPLO_NAO_USAR -- npx -y @korbitbr/mcp

Reinicie o cliente após alterar a configuração.

Como a segurança funciona

Idempotência automática: toda mutação envia Idempotency-Key UUID — o agente repetir um pedido nunca cobra duas vezes.
Menor privilégio herdado: o MCP não amplia poderes — a chave que você fornece define o que é possível (escopos, ambiente, sandbox).
Sem vazamento de chave: a chave nunca aparece em logs nem em mensagens de erro (erros trazem code e requestId para acionar o suporte).

Ferramentas disponíveis

Sempre disponíveis (25):

Grupo	Ferramentas
Saldo & saques	`get_balance`, `get_balance_breakdown`, `list_payout_requests`, `get_payout_request`, `list_payout_beneficiaries`
Pagamentos	`create_payment_intent`, `get_payment_intent`
Clientes & pedidos	`list_orders`, `get_order`, `list_customers`, `get_customer`, `create_customer`
Catálogo & checkout	`list_products`, `get_product`, `create_product`, `create_price`, `create_offer`, `publish_offer`, `get_checkout_link`
Assinaturas	`list_subscriptions`, `get_subscription`
Refunds	`list_refund_cases`, `get_refund_case`
Webhooks	`list_webhook_subscriptions`, `create_webhook_subscription`

Somente com KORBIT_MCP_ENABLE_MONEY_MOVEMENT=true (+4):

Ferramenta	O que faz
`create_payout_request`	Solicita saque do saldo disponível para um beneficiário
`create_payout_beneficiary`	Cadastra chave PIX de destino
`create_refund`	Devolve total ou parcial de um pagamento
`cancel_subscription`	Cancela uma assinatura

Mesmo com a flag ligada, as instruções do servidor orientam o agente a confirmar valor e destinatário com você antes de executar essas ações.

Variáveis de ambiente

Variável	Obrigatória	Descrição
`KORBIT_API_KEY`	sim	Chave `kbt_live_…` (produção) ou `kbt_test_…` (sandbox)
`KORBIT_MCP_ENABLE_MONEY_MOVEMENT`	não	`"true"` registra as ferramentas financeiras (padrão: desligado)

Um servidor MCP hospedado (endpoint HTTP, sem instalação local) está no nosso roadmap — por exigir infraestrutura de autenticação própria, ele não faz parte desta primeira versão.

​Instalação

​Claude Desktop

​Cursor

​Claude Code / Codex CLI

​Como a segurança funciona

​Ferramentas disponíveis

​Variáveis de ambiente

Instalação

Claude Desktop

Cursor

Claude Code / Codex CLI

Como a segurança funciona

Ferramentas disponíveis

Variáveis de ambiente