Pular para o conteúdo principal

MCP - Documentação da API

O que é MCP?

MCP (Model Context Protocol) é um padrão aberto que conecta uma IA a fontes externas de informação e ferramentas. Um servidor MCP expõe um conjunto de tools (funções) que a IA pode chamar quando precisa de um dado que não tem. O servidor MCP do Koncili é essa "fonte de informação": ele entrega à sua IA a documentação da API sob demanda.

O MCP do Koncili permite que a IA que você já usa para programar (Claude Code, GitHub Copilot, Cursor, opencode, entre outras) consulte a documentação da API de Integração Financeira (ERP) em linguagem natural, sem você sair do editor.

Em vez de abrir o navegador, procurar a página certa e copiar o exemplo, você pergunta direto para a IA — "quanto tempo o token vale?", "quais endpoints existem para baixar lançamentos?", "retorne um exemplo de curl para resolver um extrato" — e ela responde usando a documentação oficial, já dentro do seu fluxo de trabalho.

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

O servidor MCP do Koncili é uma base de conhecimento da documentação — 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 só com o que está documentado. Quando não encontra a resposta na base oficial, ele diz que não encontrou — em vez de "inventar" (alucinar) uma resposta. Assim você nunca recebe um endpoint ou parâmetro que não existe.
  • ❌ 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 seus dados. Não pede login e não recebe seu token — as respostas vêm de documentação pública.

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:

FerramentaPara quê serve
search_documentationBusca em linguagem natural
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)

Pré-requisitos​

  1. Um cliente de IA compatível com MCP — Claude Code, GitHub Copilot (VS Code), Cursor, opencode ou qualquer outro que suporte servidores MCP via HTTP.
  2. A URL do servidor MCP do Koncili (endpoint abaixo). O acesso é aberto: você não precisa de token nem de login para conectar o MCP.
URL do servidor MCP

Use a URL oficial do servidor MCP do Koncili: https://developers.koncili.com/mcp.

Como adicionar o MCP à sua IA​

O passo é sempre o mesmo em qualquer cliente: registrar um servidor MCP do tipo HTTP, apontando para a URL do Koncili. Abaixo o passo a passo de cada um.

Claude Code​

Opção A — pelo terminal (recomendado):

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

O comando registra o servidor com o nome koncili-mcp-erp. Ele passa a valer em uma sessão nova do Claude Code — a que já estava aberta na hora de adicionar não recarrega sozinha.

Por padrão o servidor vale só no projeto atual. Para deixá-lo disponível em todos os seus projetos, use o escopo user:

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

Opção B — pelo arquivo de configuração (.mcp.json na raiz do projeto, versionado junto com o repositório para valer para todo o time):

{
  "mcpServers": {
    "koncili-mcp-erp": {
      "type": "http",
      "url": "https://developers.koncili.com/mcp"
    }
  }
}

Confirme com o comando /mcp dentro de uma sessão nova, ou claude mcp list no terminal.

Detalhes do .mcp.json
  • O campo type é obrigatório. Uma entrada com url e sem type é lida como servidor local (stdio) e o Claude Code recusa com a mensagem MCP server "koncili-mcp-erp" has a "url" but no "type". O valor streamable-http também é aceito como sinônimo de http.
  • Não existe um .mcp.json global: esse arquivo é sempre por projeto. Configurações de escopo local e user ficam em ~/.claude.json e são gerenciadas pelo comando claude mcp add.
  • Na primeira vez que você abrir o projeto, o Claude Code pede aprovação para o servidor vindo do .mcp.json (ele aparece como ⏸ Pending approval no claude mcp list). Basta rodar claude e aprovar.

GitHub Copilot (VS Code)​

O Copilot lê servidores MCP de um arquivo mcp.json. Crie .vscode/mcp.json na raiz do seu projeto (ou use o comando MCP: Add Server na paleta de comandos, Ctrl/Cmd+Shift+P):

{
  "servers": {
    "koncili-mcp-erp": {
      "type": "http",
      "url": "https://developers.koncili.com/mcp"
    }
  }
}

Depois de salvar, abra o Chat do Copilot no modo Agent, clique em Configure Tools (ícone de ferramentas no campo de mensagem) e confirme que as ferramentas do Koncili aparecem na lista.

Atenção à chave do JSON

No VS Code a chave de topo é servers — e não mcpServers, como em outros clientes.

informação

O suporte a MCP no Copilot exige uma versão recente do VS Code e do plugin do Copilot Chat. Se o mcp.json não for reconhecido, atualize os dois.

Cursor​

O Cursor usa um arquivo mcp.json. Você pode criar em dois níveis:

  • Global (vale para todos os projetos): ~/.cursor/mcp.json
  • Por projeto: .cursor/mcp.json na raiz do repositório
{
  "mcpServers": {
    "koncili-mcp-erp": {
      "url": "https://developers.koncili.com/mcp"
    }
  }
}

Para servidores remotos o Cursor exige apenas o campo url — o type não é necessário.

Alternativamente, use a página Customize na barra lateral do Cursor para adicionar e gerenciar servidores MCP, e confirme ali que o koncili-mcp-erp aparece como conectado.

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

Os arquivos são mesclados, não substituídos — o do projeto complementa e sobrescreve o global. Servidores MCP remotos usam "type": "remote":

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "koncili-mcp-erp": {
      "type": "remote",
      "url": "https://developers.koncili.com/mcp",
      "enabled": true
    }
  }
}

As ferramentas ficam disponíveis para o modelo assim que o servidor entra no arquivo de configuração. Se elas não aparecerem, reinicie o opencode.

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 (e não um palpite genérico), a conexão está funcionando. Se ela disser que não tem acesso à ferramenta, revise a URL configurada e reinicie/abra uma sessão nova do cliente.

Boas práticas e limitações​

  • Faça perguntas curtas e objetivas. Evite perguntas muito longas e 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 foi desenhado para coletar o mínimo possível:

  • Não exige login nem token — o MCP não identifica você nem a sua empresa.

  • Buscas com resposta não são armazenadas. Quando a documentação responde à sua pergunta, nada é gravado.

  • Buscas sem resposta são registradas para melhorar a documentação. Quando o MCP não encontra uma resposta, ele guarda, para que a equipe do Koncili evolua a base de conhecimento. O que armazenamos:

    • o texto da sua pergunta — para entender o que faltava na documentação;
    • um identificador derivado do seu endereço IP — o IP não é gravado em texto puro; ele passa antes por uma transformação criptográfica;
    • a data/hora e qual ferramenta foi usada.

    Esses registros servem exclusivamente para a curadoria da documentação — não são usados para rastrear, perfilar ou identificar integradores.

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, 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.