Skip to main content

MCP - API Documentation

The Koncili MCP allows the AI you already use for development to query the Financial Integration API (ERP) documentation.

The MCP is exclusive to Koncili customers. Using any of its tools requires a valid credential from your Koncili account (the same one used to authenticate against the Financial Integration API — not the account used to log into the Koncili system/ dashboard).

Prerequisites:

  • An MCP-compatible AI client.
  • A user and password with access permission to the Financial Integration API.

How to Add MCP to Your AI Client​

We currently officially support the following AIs: Claude Code, opencode, GitHub Copilot CLI, Claude Desktop/Web, and ChatGPT Web.

Other agents compatible with MCP over HTTP may work using the manual authentication described further below.

Claude Code​

This is Claude Code, the CLI — not a VS Code extension

The instructions below are for Claude Code, Anthropic's official CLI (install it from code.claude.com/docs/en/quickstart). You can run the commands below in VS Code's integrated terminal (or any other terminal), but Claude Code needs to be installed first — typing the commands into a plain terminal without Claude Code installed will not work.

Requires a paid Anthropic account

Claude Code does not work with a free account. You need a paid plan (Pro, Max, Team, or Enterprise) or API credits on the Anthropic Console to use it.

1. Add the MCP server

In the terminal, inside the project where you want to use the MCP:

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

After adding the server, open a new Claude Code session (or restart the current one) so the MCP shows up as available.

2. Log in

You can authenticate in two ways:

Option A — via the /mcp menu:

In Claude Code, type:

/mcp

It will show the list of added MCPs. Select koncili-mcp-erp with the Enter key, then select authenticate.

Option B — via the direct command:

claude mcp login koncili-mcp-erp

In both cases, Claude Code takes you to Koncili's login screen. Depending on the environment:

  • It opens the browser automatically;
  • It provides a link for you to click. If it only shows the link, open it in your browser, log in, and let Claude know you've finished this step.

After authorizing, Claude Code stores the credential and uses it for future questions. When you log out, login happens automatically on the first question that needs the MCP.

Enterprise account (Team/Enterprise)

If the claude mcp add command fails or the server does not become available due to an organization policy, ask your administrator/IT to grant this permission, or to add the koncili-mcp-erp server (same URL above) in the managed settings. If in doubt, send an email to erp@koncili.com.

Claude Desktop/Web​

1. Add the MCP server

In Claude Desktop or Claude.ai (Web), go to Settings → Connectors → Add custom connector and fill in:

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

2. Log in

On the first question that needs the MCP, or by clicking Connect, Claude automatically opens Koncili's login screen in the browser. After entering your e-mail and password, the credential is saved and used for future questions.

Enterprise account (Team/Enterprise)

If the option to add a custom connector doesn't show up, or the connection fails due to an organization policy, ask your workspace administrator to enable custom connectors in Claude's settings for teams/enterprises.

opencode​

opencode reads its configuration from an opencode.json file (or opencode.jsonc, which allows comments). You can create it at two levels:

  • Global (applies to every project): ~/.config/opencode/opencode.json
  • Per project: opencode.json at the repository root
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "koncili-mcp-erp": {
      "type": "remote",
      "url": "https://erp.koncili.com/mcp",
      "enabled": true,
      "oauth": {}
    }
  }
}

The "oauth": {} block enables automatic login: opencode detects that the server requires a credential and opens the browser on Koncili's login screen on its own, on the first question that needs the MCP.

After saving the configuration file, open a new opencode session (or restart the current one) so the MCP shows up as available.

If you'd rather trigger the login before asking anything, or check whether you're already authenticated:

opencode mcp auth koncili-mcp-erp

GitHub Copilot CLI​

1. Add the MCP server

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

After adding the server, open a new Copilot CLI session (or restart the current one) so the MCP shows up as available.

2. Ask your first question

On the first question that needs the MCP, Copilot CLI opens the browser on Koncili's login screen automatically.

This is the CLI, not the VS Code extension

These instructions apply to the GitHub Copilot CLI and not to the GitHub Copilot extension found in several IDEs.

ChatGPT Web​

1. Add the MCP server

In ChatGPT (web), go to Settings → Plugins, click Explore connectors/plugins, then click + to add a custom connector. Fill in:

  • Name: koncili-mcp-erp
  • MCP URL: https://erp.koncili.com/mcp
  • Authentication: OAuth

2. Log in

The first time you use the connector in a conversation, ChatGPT automatically opens Koncili's login screen in the browser. After entering your e-mail and password, the credential is saved and used on its own for future questions.

Corporate account (Team/Enterprise)

On corporate accounts, custom connectors may be disabled by default. Ask your workspace administrator to enable custom connectors in ChatGPT's admin settings.

Manual Authentication​

If automatic login doesn't work in your environment, you can authenticate by pasting a token manually:

1. Open https://erp.koncili.com/mcp/login.html in your browser and log in with your Koncili account's e-mail and password.

2. Copy the token shown on the screen — the credential is valid for approximately 2 hours.

3. Paste the token into the Authorization header of your client's configuration:

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

When the token expires, go back to the login screen and generate a new one.

What It Does (and What It Does Not Do)​

Koncili's MCP server is a knowledge base — it is not the API itself.

  • ✅ Answers integration questions: authentication, initial setup (IP allowlist, releasetype), endpoint catalog, common errors, and request examples.
  • ✅ Answers business-rule questions: about entries, routines, etc.
  • ✅ Answers only from documented content. When it cannot find the answer in the official source, it says it did not find it — and stores the information in order to improve the MCP's knowledge base.
  • ❌ Does not execute calls to the Koncili API. It does not send requests, does not fetch your entries, and does not perform settlements. It only explains how to do it.
  • ❌ Does not access your account's data. Even though it requires login, the MCP only queries documentation and the FAQ — it does not read your entries, reconciliations, or settlements. This will be implemented in the future.

Available Tools​

Your AI automatically picks which of these tools to use based on the question — you do not need to call them by hand. All of them require the same credential.

ToolWhat it's for
search_documentationNatural-language search over the public documentation
list_endpointsLists the ERP integration endpoint catalog
detail_endpointShows the full specification of an endpoint (parameters, schemas, errors)
list_common_errorsLists the most common protocol errors (e.g., missing token, 403, 429, 412)
generate_request_exampleGenerates a ready-to-use curl example for an endpoint (with the token as a placeholder)
search_faqSearches business-rule answers that aren't in the public documentation

Verifying the Connection​

After configuring it, run a quick test by asking your AI something that only Koncili's documentation can answer. For example:

"Using Koncili's MCP, how long is the access token valid?"

"List the endpoints of Koncili's Financial Integration API."

If the AI answers citing the documentation, the connection is working.

If you get an error instead, the status code helps identify the cause:

  • 401 — missing, invalid, or expired credential. Log in again according to your AI.
  • 403 — the credential is valid, but your account doesn't have the required permission enabled. Contact erp@koncili.com.

Best Practices and Limitations​

  • Ask short, objective questions. Avoid very long questions and multiple questions at once, go straight to the point to improve answer accuracy.
  • Include the Koncili context in the question. Whenever possible, use the word "Koncili" in the question. Example: prefer "What is an entry in Koncili?" instead of "What is an entry?" to avoid interpretations outside the integration's context.
  • Rate limit: the MCP accepts up to 90 requests per minute.

Privacy and Data Handling​

Koncili's MCP requires a valid credential for any question, on any tool:

  • Every call is tied to your account. Since a credential is mandatory, we store the Koncili account identifier and e-mail used in the call, along with the date/time and which tool was used.

  • Answered questions are not stored. When the documentation or the FAQ answers your question, the content of the question is not recorded. For statistical purposes, we store the e-mail and access date to build indicators.

  • Unanswered questions are stored to improve the documentation and the FAQ. When the MCP cannot find an answer, it stores the text of the question, so the Koncili team can evolve the knowledge base.

    These records are used for documentation curation and account support — not for purposes unrelated to the integration.

Do not send sensitive data in your questions

Since the text of unanswered questions is stored, do not include personal data, tokens, credentials, or sensitive information in questions asked to the MCP. Ask about the documentation — do not paste real data.

By connecting to and using Koncili's MCP with your credential, you acknowledge this data handling. Privacy questions: erp@koncili.com.

Support​

Questions about the Financial Integration API (ERP), including the MCP: erp@koncili.com.