# Servidores MCP para construir agentes sobre a Kobana

Cada produto tem um servidor MCP remoto em mcp.{produto}.kobana.com.br, com OAuth 2.1, escopos por recurso e as permissões de quem autorizou.

---

## Como os servidores MCP funcionam

- **Streamable HTTP, stateless**: Uma mensagem JSON-RPC 2.0 por POST, sem sessão. A URL é a raiz do host, sem caminho.
- **OAuth 2.1 com PKCE**: O cliente descobre onde autenticar a partir da URL e abre a tela de login da Kobana. Não há client secret. Fora do Gateway Bancário, clientes registrados dinamicamente (Claude, ChatGPT) recebem só leitura.
- **Token pessoal, quando não há OAuth**: Crie na Conta Kobana um token com o aplicativo do produto e o uso MCP, e mande em Authorization: Bearer.
- **Escopo e permissões**: O token limita o cliente por recurso e nível (read ou write). As permissões de painel de quem autorizou limitam o resto, relidas a cada chamada.
- **Tools anotadas**: Cada tool declara se é de leitura, escrita ou destrutiva. As destrutivas só rodam depois de confirmação.
- **As mesmas barreiras da API**: A tool chama o mesmo código da API REST: conta habilitada, assinatura ativa, produto no plano e allow list de IP.

## Servidores por produto

Cole a URL do produto no cliente MCP. O Gateway Bancário também tem um host de sandbox, com tokens separados dos de produção.

| Documentação | Produção | Sandbox | tools |
|---|---|---|---|
| [Gateway Bancário](https://docs.banking.kobana.com.br/pt/mcp/overview/introduction) | `https://mcp.banking.kobana.com.br` | `https://mcp.banking.sandbox.kobana.com.br` | 289 |
| [Faturamento Automático](https://docs.billing.kobana.com.br/pt/mcp/overview/introduction) | `https://mcp.billing.kobana.com.br` | — | 293 |
| [Financeiro Inteligente](https://docs.finance.kobana.com.br/pt/mcp/overview/introduction) | `https://mcp.finance.kobana.com.br` | — | 96 |
| [Régua de Cobrança](https://docs.dunning.kobana.com.br/pt/mcp/overview/introduction) | `https://mcp.dunning.kobana.com.br` | — | 119 |
| [Dashboard Mágico](https://docs.dashboards.kobana.com.br/pt/mcp/overview/introduction) | `https://mcp.dashboards.kobana.com.br` | — | 220 |
| [Inbox Autônomo](https://docs.inbox.kobana.com.br/pt/mcp/overview/introduction) | `https://mcp.inbox.kobana.com.br` | — | 53 |
| [Agente Kadu](https://docs.kadu.ia.br/pt/mcp/overview/introduction) | `https://mcp.kadu.ia.br` | — | 80 |

- Opera na conta do token. Para uma subconta, envie o cabeçalho X-Account-Uid.
- O workspace é escolhido a cada chamada, com finance_workspaces_list e o argumento workspace_id.
- O workspace é escolhido a cada chamada, com dunning_workspaces_list e o argumento workspace_id. Com mais de um workspace, a chamada sem ele falha.
- O workspace é escolhido a cada chamada, com dashboards_workspaces_list e o argumento workspace_id.
- O workspace é escolhido na conexão, com o cabeçalho X-Workspace-Id. O MCP não exige certificado de cliente.

## Teste a conexão

Com um token emitido para o MCP, liste as tools que ele alcança. Troque o host pelo do produto que você quer testar.

```bash
curl https://mcp.banking.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'
```

Se vierem menos tools do que o esperado, são o escopo do token ou as permissões de quem autorizou. Não é um erro.

## Conectar um cliente

Qualquer cliente com Streamable HTTP e OAuth 2.1 conecta só com a URL.

### Claude Code

Adicione o servidor e autentique com /mcp.

```bash
claude mcp add --transport http kobana-banking https://mcp.banking.kobana.com.br
```

### Cliente configurado por arquivo

Com token pessoal, mande o cabeçalho de autorização. Trate o arquivo como segredo.

```json
{
  "mcpServers": {
    "kobana-banking": {
      "type": "http",
      "url": "https://mcp.banking.kobana.com.br",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

### Token pessoal

Conta Kobana → Tokens e Acesso → Meus Tokens Pessoais → Novo Token, com o uso MCP. Escolha a menor validade que o uso permite.

## Postura recomendada para agentes

- **Autorize com o usuário certo**: Um cliente autorizado por um usuário somente-leitura só vê as tools de leitura, faça o que fizer o modelo.
- **Peça só o que o agente precisa**: Marque os recursos necessários e deixe write desmarcado para uso exploratório.
- **Um token por cliente**: Cada cliente recebe o seu token, que só vale no MCP. Revogue em Aplicações Autorizadas sem afetar as integrações REST.
- **Comece no sandbox**: Tools destrutivas cancelam boletos, pagam contas e transferem dinheiro de verdade. O Gateway Bancário tem host de sandbox.
- **Dado de terceiro não é instrução**: Nomes, descrições e observações são escritos por outras pessoas. Os servidores instruem o agente a não obedecer ordens nesses campos.

## Quer só usar, sem integrar?

Temos um guia para quem quer conectar o assistente à conta Kobana, com passo a passo para Claude, ChatGPT e Cursor.

[Ver o guia para usuários](https://www.kobana.com.br/ia/mcp-servers)

---

## Vamos construir o seu agente?

Conte o que o seu agente precisa fazer e ajudamos a desenhar a integração.

[Agendar bate-papo](https://www.kobana.com.br/agendar)
