Pular para o conteúdo principal

MCP - Documentação da API

O MCP do Koncili permite que a IA que você já usa para programar consulte a documentação da API de Integração Financeira (ERP).

O MCP é exclusivo para clientes Koncili. Para usar qualquer uma das ferramentas é preciso uma credencial válida da sua conta Koncili (a mesma usada para autenticar na API de Integração Financeira — não é a conta usada para fazer login no sistema/painel do Koncili).

Pré-requisitos:

  • Um cliente de IA com suporte a MCP.
  • Ter um usuário e senha com permissão de acesso a API de integração financeira.

Como adicionar o MCP à sua IA​

Hoje damos suporte oficial as seguintes IAs: Claude Code, opencode, GitHub Copilot CLI, Claude Desktop/Web e ChatGPT Web.

Outros agentes compatíveis com MCP via HTTP podem funcionar com a autenticação manual descrita mais abaixo.

Claude Code​

Isto é o Claude Code, a CLI — não a extensão do VS Code

As instruções abaixo são para o Claude Code, a CLI oficial da Anthropic (instalação em code.claude.com/docs/pt/quickstart). Você pode rodar os comandos abaixo no terminal integrado do VS Code (ou em qualquer outro terminal), mas o Claude Code precisa estar instalado antes — digitar os comandos em um terminal comum, sem o Claude Code instalado, não irá funcionar.

Requer uma conta paga da Anthropic

O Claude Code não funciona com conta gratuita. É preciso um plano pago (Pro, Max, Team ou Enterprise) ou créditos de API na Anthropic Console para usá-lo.

1. Adicione o servidor MCP

No terminal, dentro do projeto onde você quer usar o MCP:

claude mcp add --transport http koncili-mcp-erp https://erp.koncili.com/mcp

Depois de adicionar o servidor, abra uma nova sessão do Claude Code (ou reinicie a atual) para que o MCP apareça disponível.

2. Faça login

Você pode autenticar de duas formas:

Opção A — pelo menu /mcp:

No Claude Code, digite:

/mcp

Ele vai apresentar a lista de MCPs adicionados. Selecione o koncili-mcp-erp usando a tecla Enter e, em seguida, selecione authenticate.

Opção B — pelo comando direto:

claude mcp login koncili-mcp-erp

Em ambos os casos, o Claude Code leva você até a tela de login do Koncili. Dependendo do ambiente:

  • Abre o navegador automaticamente;
  • Fornece um link para você clicar. Se ele apenas exibir o link, abra no seu navegador, efetue o login e avise o Claude que já concluiu esse passo.

Depois de autorizar, o Claude Code guarda a credencial e passa a usá-la nas próximas perguntas. Ao deslogar o login acontece automaticamente na primeira pergunta que exigir o MCP.

Conta empresarial (Team/Enterprise)

Se o comando claude mcp add falhar ou o servidor não ficar disponível por política da organização, peça ao administrador/TI para liberar essa permissão, ou para adicionar o servidor koncili-mcp-erp (mesma URL acima) nas configurações gerenciadas. Em caso de dúvida encaminhe um email para erp@koncili.com.

Claude Desktop/Web​

1. Adicione o servidor MCP

No Claude Desktop ou no Claude.ai (Web), vá em Configurações → Conectores → Adicionar conector personalizado e preencha:

  • Nome: koncili-mcp-erp
  • URL: https://erp.koncili.com/mcp

2. Faça login

Na primeira pergunta que exigir o MCP ou ao clicar em Vincular, o Claude abre a tela de login do Koncili automaticamente no navegador. Depois de entrar com e-mail e senha, a credencial fica salva e passa a ser usada nas próximas perguntas.

Conta empresarial (Team/Enterprise)

Se a opção de adicionar conector personalizado não aparecer, ou a conexão falhar por política da organização, peça ao administrador do workspace para habilitar conectores personalizados nas configurações do Claude para times/empresas.

opencode​

O opencode lê a configuração de um arquivo opencode.json (ou opencode.jsonc, que aceita comentários). Você pode criar em dois níveis:

  • Global (vale para todos os projetos): ~/.config/opencode/opencode.json
  • Por projeto: opencode.json na raiz do repositório
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "koncili-mcp-erp": {
      "type": "remote",
      "url": "https://erp.koncili.com/mcp",
      "enabled": true,
      "oauth": {}
    }
  }
}

O bloco "oauth": {} habilita o login automático: o opencode detecta que o servidor exige credencial e abre o navegador na tela de login do Koncili sozinho, na primeira pergunta que precisar do MCP.

Depois de salvar o arquivo de configuração, abra uma nova sessão do opencode (ou reinicie a atual) para que o MCP apareça disponível.

Se quiser disparar o login antes de perguntar algo, ou conferir se já está autenticado:

opencode mcp auth koncili-mcp-erp

GitHub Copilot CLI​

1. Adicione o servidor MCP

copilot mcp add koncili-mcp-erp --transport http https://erp.koncili.com/mcp

Depois de adicionar o servidor, abra uma nova sessão do Copilot CLI (ou reinicie a atual) para que o MCP apareça disponível.

2. Faça a primeira pergunta

Na primeira pergunta que exigir o MCP, o Copilot CLI abre o navegador na tela de login do Koncili automaticamente.

Isto é a CLI, não a extensão do VS Code

Estas instruções valem para o GitHub Copilot CLI e não para a extensão GitHub Copilot presente em diversas IDEs.

ChatGPT Web​

1. Adicione o servidor MCP

No ChatGPT (web), vá em Configurações → Plugins, clique em Explorar conectores/plugins e depois no + para adicionar um conector personalizado. Preencha:

  • Nome: koncili-mcp-erp
  • URL do MCP: https://erp.koncili.com/mcp
  • Autenticação: OAuth

2. Faça login

Ao usar o conector pela primeira vez em uma conversa, o ChatGPT abre a tela de login do Koncili automaticamente no navegador. Depois de entrar com e-mail e senha, a credencial fica salva e passa a ser usada sozinha nas próximas perguntas.

Conta corporativa (Team/Enterprise)

Em contas corporativas, conectores personalizados podem estar desabilitados por padrão. Peça ao administrador do workspace para habilitar conectores personalizados nas configurações de administração do ChatGPT.

Autenticação manual​

Se o login automático não funcionar no seu ambiente é possivel para autenticar colando um token manualmente:

1. Abra https://erp.koncili.com/mcp/login.html no navegador e entre com o e-mail e a senha da sua conta Koncili.

2. Copie o token exibido na tela — a credencial vale por aproximadamente 2 horas.

3. Cole o token no cabeçalho Authorization da configuração do seu cliente:

{
  "mcpServers": {
    "koncili-mcp-erp": {
      "type": "http",
      "url": "https://erp.koncili.com/mcp",
      "headers": {
        "Authorization": "Bearer <SEU_TOKEN>"
      }
    }
  }
}

Quando o token expirar, volte à tela de login e gere um novo.

O que ele faz (e o que não faz)​

O servidor MCP do Koncili é uma base de conhecimento — não é a API em si.

  • ✅ Responde dúvidas sobre a integração: autenticação, setup inicial (whitelist de IP, releasetype), catálogo de endpoints, erros comuns e exemplos de requisição.
  • ✅ Responde dúvidas de regra de negócio: Sobre lançamentos, rotinas, etc.
  • ✅ Responde só com o que está documentado. Quando não encontra a resposta na base oficial, ele diz que não encontrou — e armazena a informação com intuito de aprimorar a base de conhecimento do MCP.
  • ❌ Não executa chamadas na API do Koncili. Ele não envia pedidos, não busca seus lançamentos e não faz baixa. Ele só explica como fazer isso.
  • ❌ Não acessa os dados da sua conta. Mesmo exigindo login, o MCP só consulta documentação e FAQ — ele não lê seus lançamentos, conciliações ou repasses. Isso será implementado futuramente.

Ferramentas (tools) disponíveis​

A sua IA escolhe automaticamente qual dessas ferramentas usar conforme a pergunta — você não precisa chamá-las na mão. Todas exigem a mesma credencial.

FerramentaPara quê serve
search_documentationBusca em linguagem natural na documentação pública
list_endpointsLista o catálogo de endpoints da integração ERP
detail_endpointMostra a especificação completa de um endpoint (parâmetros, schemas, erros)
list_common_errorsLista os erros de protocolo mais comuns (ex.: token ausente, 403, 429, 412)
generate_request_exampleGera um exemplo de curl pronto para um endpoint (com o token como placeholder)
search_faqBusca respostas de regras de negócio que não estão na documentação pública

Verificando a conexão​

Depois de configurar, faça um teste rápido pedindo algo à sua IA que só a documentação do Koncili responde. Por exemplo:

"Usando o MCP do Koncili, por quanto tempo o token de acesso é válido?"

"Liste os endpoints da API de Integração Financeira do Koncili."

Se a IA responder citando a documentação, a conexão está funcionando.

Se a resposta for um erro, o código ajuda a identificar a causa:

  • 401 — credencial ausente, inválida ou expirada. Refaça o login de acordo com sua IA.
  • 403 — a credencial é válida, mas sua conta não tem a permissão necessária liberada. Fale com erp@koncili.com.

Boas práticas e limitações​

  • Faça perguntas curtas e objetivas. Evite perguntas muito longas e múltiplas perguntas ao mesmo tempo, vá direto ao ponto para aumentar a precisão da resposta.
  • Inclua o contexto Koncili na pergunta. Sempre que possível, use a palavra "Koncili" no enunciado. Exemplo: prefira "O que é um lançamento no Koncili?" em vez de "O que é um lançamento?" para evitar interpretações fora do contexto da integração.
  • Rate limit: o MCP aceita até 90 requisições por minuto.

Privacidade e tratamento de dados​

O MCP do Koncili exige uma credencial válida para qualquer pergunta, em qualquer ferramenta:

  • Toda chamada fica associada à sua conta. Como a credencial é obrigatória, armazenamos o identificador e o e-mail da conta Koncili usados na chamada, além da data/hora e de qual ferramenta foi usada.

  • Perguntas respondidas não são armazenadas Quando a documentação ou o FAQ respondem à sua pergunta, o conteúdo da pergunta não é gravado. A fim de estatísticas, armazenamos o email e data de acesso para contrução de indicadores.

  • Perguntas não respondidas são armazenadas para melhorar a documentação e o FAQ. Quando o MCP não encontra uma resposta, ele guarda o texto da pergunta, para que a equipe do Koncili evolua a base de conhecimento.

    Esses registros servem para curadoria de documentação e suporte à sua conta — não são usados para fins alheios à integração.

Não envie dados sensíveis nas perguntas

Como o texto das perguntas sem resposta é armazenado, não inclua dados pessoais, tokens, credenciais ou informações sensíveis nas perguntas feitas ao MCP. Pergunte sobre a documentação — não cole dados reais.

Ao conectar e utilizar o MCP do Koncili com sua credencial, você está ciente deste tratamento de dados. Dúvidas sobre privacidade: erp@koncili.com.

Suporte​

Dúvidas sobre a API de Integração Financeira (ERP), inclusive sobre o MCP: erp@koncili.com.