Pular para o conteúdo principal

Clientes

Qualquer cliente que fale Streamable HTTP MCP e saiba fazer o fluxo OAuth 2.1 do MCP consegue conectar. Você só informa a URL e o cliente descobre sozinho onde autenticar, abre o 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 → Novo Token Pessoal, com o app Financeiro Inteligente e o uso MCP, e configure o cliente para mandá-lo no cabeçalho Authorization: Bearer <token>. É também o caminho para um agente que precisa escrever, já que pelo fluxo OAuth o acesso é só de leitura hoje.

A URL não leva workspace. O agente escolhe onde agir a cada chamada: finance_workspaces_list lista os workspaces que você alcança, e as outras tools aceitam workspace_id. Se você alcança um só, nem isso é preciso. Para fixar um workspace padrão na conexão, acrescente ?workspace_id= à URL ou, quando o cliente deixa, o cabeçalho X-Workspace-Id — os dois são opcionais. Veja Autenticação → O workspace.

Claude Code​

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

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

Para definir um workspace padrão — opcional —, use a URL com ele:

claude mcp add --transport http kobana-finance \
  "https://mcp.finance.kobana.com.br/?workspace_id=$WORKSPACE_ID"

Com um token pessoal, sem fluxo OAuth:

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

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-finance": {
      "type": "http",
      "url": "https://mcp.finance.kobana.com.br"
    }
  }
}

Na primeira conexão o cliente abre o navegador para você autorizar. Você escolhe a organização na tela de consentimento, e ela fica gravada no token; o workspace vem de cada chamada (ou do padrão, se você puser ?workspace_id= na URL).

Com um token pessoal, acrescente os cabeçalhos — a organização é a da conta em que você criou o token:

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

Para um workspace padrão, acrescente "X-Workspace-Id": "<uuid>" aos headers — opcional.

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

Clientes que conectam por URL​

Claude e ChatGPT conectam um servidor remoto colando a URL — https://mcp.finance.kobana.com.br, sem mais nada — nas configurações de conectores. O fluxo OAuth roda dentro do próprio app, e o assistente descobre os workspaces sozinho, com finance_workspaces_list.

Usando o Faturamento junto​

As tools deste servidor começam com finance_, e as do Faturamento Automático com billing_; os resources, com kobana://finance/ e kobana://billing/. Os dois servidores convivem no mesmo cliente sem colisão — conecte os dois quando o agente precisa das duas pontas.

Postura recomendada para agentes​

  • Autorize com a conta certa. O MCP estreita as tools para o que a pessoa que autorizou pode fazer no dashboard. Um cliente autorizado por um analista somente-leitura expõe só as tools de leitura, faça o que fizer o modelo do outro lado. É a forma mais forte de restringir um agente.
  • 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 serve para chamar a API REST. Para desligar um agente, remova a autorização dele na Kobana sem afetar as suas integrações.
  • Token pessoal: validade curta e escopo mínimo. Marque só os recursos e acessos de que o agente precisa, e a validade mais curta que o uso permite: revogar o token na Kobana não corta o acesso antes da validade — veja Revogação do token pessoal. Um agente que lança títulos não precisa de finance/payable_dispatches.
  • Deixe o canal MCP fechado para pagar. Por padrão, a aba Segurança › Canais não deixa agentes de IA enviarem ao banco. Abra só se for intencional.
  • Comece no sandbox. O servidor pede confirmação nas tools destrutivas, mas a primeira exploração não deve ser em produção.
  • Tools destrutivas pedem um cliente que confirme. Apagar, mandar ao banco, cobrar, transferir, conciliar ou ajustar saldo só roda num cliente que fale a revisão 2026-07-28 com elicitation de formulário; nos demais, essas tools voltam confirmation_required e o resto funciona normalmente. Veja Confirmação de tools destrutivas.

Verificando a conexão​

O jeito mais simples é pedir ao assistente: "em quais workspaces você pode agir?" — ele chama finance_workspaces_list. Depois, "quais empresas existem no workspace Matriz?" chama finance_companies_list com o workspace_id dele.

Com um token emitido para o MCP — um token pessoal com uso MCP, por exemplo —, dá para conferir por curl:

# Quantas tools este token alcança?
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

# Os workspaces que a pessoa do token alcança
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"finance_workspaces_list","arguments":{}}}'

# As empresas de um workspace
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"finance_companies_list",
                 "arguments":{"workspace_id":"'"$WORKSPACE_ID"'","fields":["name","cnpj"]}}}'

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.