> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korbit.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use a Korbit a partir de Claude, Cursor, Codex e qualquer cliente MCP — com movimentação de dinheiro desligada por padrão.

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.

<Warning>
  **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_`.
</Warning>

## Instalação

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

```bash theme={null}
npx -y @korbitbr/mcp
```

Você precisa de uma [chave de API](/guias/autenticacao). 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):

```json theme={null}
{
  "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

```bash theme={null}
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](/recursos/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) |

<Note>
  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.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.