Pular para o conteúdo principal

Clientes

Qualquer cliente que fale Streamable HTTP e faça o fluxo OAuth 2.1 do MCP consegue conectar. Você informa só a URL: o cliente descobre onde autenticar, abre a tela de login da Kobana no navegador e guarda o token. Veja Autenticação.

Cliente sem suporte a OAuth também conecta, com um token pessoal: crie em Conta Kobana → Tokens e Acesso → Meus Tokens Pessoais → Novo Token, com o aplicativo Gateway Bancário e o uso MCP, e configure o cliente para mandá-lo no cabeçalho Authorization: Bearer <token>.

Claude​

Nas configurações de conectores do Claude, adicione um conector personalizado com a URL https://mcp.banking.kobana.com.br. Na opção de cliente OAuth, use a identidade publicada do Claude (o padrão) e deixe o client secret em branco. O fluxo OAuth roda dentro do próprio app.

Claude Code​

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

Depois, rode /mcp numa sessão e escolha Authenticate para entrar na Kobana.

Com um token pessoal, sem fluxo OAuth:

claude mcp add --transport http kobana-banking https://mcp.banking.kobana.com.br \
  --header "Authorization: Bearer <token pessoal>"

ChatGPT e outros clientes por URL​

Clientes que conectam servidor remoto pela URL recebem https://mcp.banking.kobana.com.br nas configurações de conectores e fazem o fluxo OAuth sozinhos. Um cliente que se registra sozinho (registro dinâmico) recebe só leitura: veja Leitura para todos, escrita para quem foi verificado.

Clientes configurados por arquivo​

Clientes que leem um arquivo JSON de configuração pedem a URL e o transporte. Pelo fluxo OAuth, não há cabeçalho de autenticação:

{
  "mcpServers": {
    "kobana-banking": {
      "type": "http",
      "url": "https://mcp.banking.kobana.com.br"
    }
  }
}

Com um token pessoal, acrescente o cabeçalho. A conta é a do token; para operar numa subconta, acrescente também X-Account-Uid:

{
  "mcpServers": {
    "kobana-banking": {
      "type": "http",
      "url": "https://mcp.banking.kobana.com.br",
      "headers": {
        "Authorization": "Bearer <token pessoal>",
        "X-Account-Uid": "<uid da subconta>"
      }
    }
  }
}

Trate o arquivo como segredo: quem o lê usa o token.

Postura recomendada para agentes​

  • Autorize com o usuário certo. As tools se estreitam para as permissões de painel de quem autorizou. Um cliente autorizado por um usuário somente-leitura expõe só as tools de leitura, faça o que fizer o modelo. É a forma mais forte de restringir um agente.
  • Peça só o que o agente precisa. Na tela de consentimento, ou no wizard do token pessoal, marque só os recursos necessários e deixe write desmarcado para uso exploratório.
  • Um token por cliente. Cada cliente faz o próprio fluxo e recebe o próprio token, que só vale no MCP: ele não chama a API REST. Para desligar um agente, revogue a autorização dele em Conta Kobana → Tokens e Acesso → Aplicações Autorizadas sem afetar as suas integrações.
  • Token pessoal com validade curta. Escolha a menor validade que o uso permite.
  • Comece no sandbox. As tools destrutivas cancelam boletos, pagam contas e transferem dinheiro de verdade. Use https://mcp.banking.sandbox.kobana.com.br na primeira exploração.

Verificando a conexão​

O jeito mais simples é pedir ao assistente: "liste meus boletos vencidos". Ele chama banking_charge_bank_billet_list.

Com um token emitido para o MCP, dá para conferir por curl:

# Quantas tools este token alcança?
curl -s 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"}' | jq '.result.tools | length'

# Os três boletos mais recentes
curl -s 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":2,"method":"tools/call",
       "params":{"name":"banking_charge_bank_billet_list","arguments":{"limit":3,"fields":["status","amount"]}}}'

Se o número de tools for menor do que você esperava, são as permissões de quem autorizou ou o escopo do token: veja Autenticação. Não é um erro.