Pular para o conteúdo principal

Introdução

O servidor MCP do Financeiro Inteligente é um servidor Model Context Protocol remoto que expõe as operações da API pública — contas a pagar e a receber, lançamentos, conciliações, contas financeiras, fluxo de caixa e cadastros — como tools que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar.

Ele é servido em host próprio, mcp.finance.kobana.com.br, no mesmo domínio da API, com transporte Streamable HTTP em modo stateless e autenticação por Bearer token emitido para o MCP pela Conta Kobana. Nenhum certificado de cliente está envolvido.

:::info Disponibilidade O servidor, suas 95 tools, os resources e os prompts estão implementados, e a autenticação é pelo authorization server da Kobana: pelo fluxo OAuth 2.1, em que o cliente recebe só a URL e faz o login sozinho, ou por um token pessoal criado na sua Conta Kobana. A borda dedicada (distribution mcp.finance.*, WAF e DNS) ainda está sendo provisionada. :::

Quando usar​

API REST (/v1)Servidor MCP (este)
Consumidorseu backendum cliente de IA (Claude, ChatGPT, uma IDE)
Configuraçãotoken e X-Workspace-Id, fora de bandasó uma URL; o workspace vai em cada chamada
TransporteHTTPS/RESTStreamable HTTP (JSON-RPC 2.0)
AutenticaçãoBearer token emitido para a APIOAuth 2.1 ou token pessoal, sempre emitido para o MCP
Autorizaçãoescopo do tokenescopo do token e permissões da pessoa
Superfícieos endpoints de /v195 tools, uma por operação desses endpoints, mais resources e prompts sobre elas

O servidor MCP não substitui a API REST. Cada tool despacha in-process para o endpoint que implementa a operação, então filtros, validação, regras de baixa, rateio e isolamento por workspace são exatamente os mesmos. Se você está escrevendo código, use a API REST. Se está conectando um assistente, use isto.

O princípio​

Uma capability só existe no MCP se existir na API pública.

Não há uma segunda implementação de nada. A tool chama o handler do endpoint com a identidade que o token do chamador já provou — a mesma pessoa, a mesma organização, o mesmo workspace —, então ele roda, confere o escopo e audita como faria para qualquer requisição HTTP. Uma tool faz o que o endpoint faz por REST — nunca mais.

A consequência prática: o que hoje só existe no dashboard (aprovar pagamentos, importar extratos, gerenciar membros) não vira tool antes de virar endpoint.

tools/list devolve apenas as tools que este chamador pode rodar: as que os escopos do token alcançam e que a pessoa do token tem permissão de fazer na organização. Um agente não é informado de capacidades que só levariam negativa. Os dois eixos estão em Autenticação.

Primeiros passos​

  1. Aponte seu cliente para a URL do servidor — https://mcp.finance.kobana.com.br, sem mais nada. Veja Endpoints e Clientes.

  2. Autorize. O cliente abre o login da Kobana; entre com uma conta da organização e autorize o acesso. Veja Autenticação.

  3. Escolha o workspace. O agente chama finance_workspaces_list e passa o id escolhido como workspace_id nas outras tools. Se você alcança um workspace só, ele é o padrão e o argumento é dispensável. Veja Autenticação → O workspace.

  4. Liste as tools para confirmar o que o seu acesso alcança — peça ao assistente, ou, com um token emitido para o MCP em mãos:

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

  5. Explore o catálogo em Tools.

Próximos passos​

  • Autenticação — o fluxo OAuth, o token pessoal, o workspace, o escopo e as permissões aplicados, e os modos de falha.
  • Endpoints — URLs por ambiente e rotas servidas.
  • Transporte — JSON-RPC, cabeçalhos e métodos.
  • Clientes — como conectar Claude Code e clientes por arquivo.
  • Listagem, filtros e campos — cursor, filters, sort_by, fields.
  • Idempotência — e as ações que movem dinheiro.
  • Resources e prompts — documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas.
  • Erros — os dois canais de falha, e por que a distinção importa.
  • Tools — o catálogo completo.