Introdução

O servidor MCP do Gateway Bancário é um servidor Model Context Protocol remoto. Ele expõe as operações da API pública como tools que um cliente de IA pode chamar: boletos, Pix e Pix Automático, pagamentos, transferências, contas financeiras e extrato, clientes, webhooks, remessa e retorno, caixa postal e administração. Você conecta o cliente por URL, sem instalar nada.

O servidor fica em host próprio, mcp.banking.kobana.com.br. O transporte é Streamable HTTP em modo stateless, e a autenticação é por Bearer token.

Quando usar

	API REST (/v1, /v2)	Servidor MCP
Consumidor	o seu backend	um cliente de IA (Claude, ChatGPT, uma IDE, um agente próprio)
Configuração	token, configurado à parte	uma URL
Transporte	HTTPS/REST	Streamable HTTP (JSON-RPC 2.0)
Autenticação	token de API	token OAuth 2.1 ou token pessoal, emitidos para o MCP
Superfície	os endpoints da Referência da API	289 tools sobre os mesmos recursos

O servidor MCP não substitui a API REST. Cada tool espelha uma ação da API (ou do painel, quando não há endpoint), chama o mesmo código e passa pelas mesmas barreiras: conta habilitada para API, conta não bloqueada, assinatura ativa, produto no plano, allow list de IP. Se você está escrevendo código, use a API REST. Se está conectando um assistente, use o MCP.

O que o agente vê é mais estreito que o catálogo

O token define até onde o cliente pode ir, e as permissões de painel definem até onde vai a pessoa que o autorizou. tools/list devolve só as tools em que as duas barreiras deixam passar. O agente não fica sabendo de capacidades que levariam a uma recusa. As regras estão em Autenticação.

O que esperar

• Muita coisa é assíncrona. Emitir, cancelar, alterar e protestar um boleto viram comandos enviados ao banco. A tool confirma que o pedido foi registrado, não que o banco aceitou. Um boleto recém-emitido nasce generating e passa a opened quando o registro é confirmado. Para saber o estado real, leia o registro de novo com a tool *_get.
• Só uid. Registros são identificados pelo uid (UUID), como na API v2. Os argumentos se chamam <recurso>_uid (bank_billet_uid, financial_account_uid). Id numérico é recusado na entrada e não aparece nas respostas.
• Valores em reais (149.90) e datas em YYYY-MM-DD.
• Uma conta por conexão. Cada chamada opera na conta do token, e só nela. Para operar numa subconta, mande o cabeçalho X-Account-Uid com o uid dela. Nenhuma tool aceita a conta como argumento.
• Dado de terceiro não é instrução. Nome de pagador, descrição, observação e metadados são texto escrito por outras pessoas. As instruções do servidor mandam o agente nunca seguir ordens encontradas nesses campos e confirmar com você antes de qualquer ação que um resultado pareça pedir.
• A superfície está em inglês. Títulos, descrições de tools e de parâmetros e mensagens de sucesso e de erro estão em inglês, porque quem lê é o modelo. A exceção são as recusas HTTP herdadas da API REST (401, 403 de conta e 429), que continuam em português.

Primeiros passos

1. Aponte o cliente para a URL do servidor. Veja Endpoints e Clientes.

2. Autorize. O cliente abre a tela de login da Kobana, e você entra e escolhe os recursos e o nível de acesso. Veja Autenticação.

3. Confira o que o seu acesso alcança. Peça ao assistente, ou liste as tools com um token emitido para o MCP:

   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" }'

4. Explore o catálogo em Tools.

Próximos passos

• Autenticação: o fluxo OAuth, o token pessoal, o escopo, as permissões e os modos de falha.
• Endpoints: URLs por ambiente e rotas servidas.
• Transporte: JSON-RPC, cabeçalhos, versões do protocolo e métodos.
• Resources e prompts: documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas.
• Clientes: como conectar Claude, Claude Code, ChatGPT e clientes configurados por arquivo.
• Listagem, filtros e campos: filters, sort_by, limit, cursor e fields.
• Erros: os dois canais de falha e por que a distinção importa.
• Tools: o catálogo das 289 tools.