Skip to main content

MCP - API Documentation

What is MCP?

MCP (Model Context Protocol) is an open standard that connects an AI to external information sources and tools. An MCP server exposes a set of tools (functions) that the AI can call whenever it needs data it does not already have. Koncili's MCP server is that information source: it delivers API documentation to your AI on demand.

The Koncili MCP allows the AI you already use for development (Claude Code, GitHub Copilot, Cursor, opencode, and others) to query the Financial Integration API (ERP) documentation in natural language, without leaving your editor.

Instead of opening a browser, finding the right page, and copying examples, you can ask your AI directly - "how long is the token valid?", "which endpoints are available to settle entries?", "return a curl example to resolve an extract" - and it will answer using official documentation, right inside your workflow.

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

Koncili's MCP server is a documentation 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 only from documented content. If it cannot find the answer in the official source, it says it did not find it instead of inventing one. This ensures you never get a non-existent endpoint or parameter.
  • ❌ Does not execute Koncili API calls. It does not send requests, retrieve your entries, or perform settlements. It only explains how to do it.
  • ❌ Does not access your data. It does not require login and does not receive your token - responses come from public documentation.

Available Tools​

Your AI automatically chooses which tool to use based on your question - you do not need to call them manually:

ToolPurpose
search_documentationNatural-language documentation search
list_endpointsLists the ERP integration endpoint catalog
detail_endpointShows full endpoint specification (parameters, schemas, errors)
list_common_errorsLists common protocol errors (e.g., missing token, 403, 429, 412)
generate_request_exampleGenerates a ready-to-use curl example for an endpoint (token as placeholder)

Prerequisites​

  1. An MCP-compatible AI client - Claude Code, GitHub Copilot (VS Code), Cursor, opencode, or any other client that supports MCP servers via HTTP.
  2. Koncili MCP server URL (endpoint below). Access is open: you do not need a token or login to connect.
MCP Server URL

Use Koncili's official MCP server URL: https://developers.koncili.com/mcp.

How to Add MCP to Your AI Client​

The step is always the same in any client: register an HTTP MCP server pointing to the Koncili URL. Below is a quick setup guide for each one.

Claude Code​

Option A - using terminal (recommended):

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

This command registers the server as koncili-mcp-erp. It takes effect in a new Claude Code session - already-open sessions do not auto-reload.

By default the server is available only in the current project. To make it available across all of your projects, use the user scope:

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

Option B - using configuration file (.mcp.json at project root, commit it to your repository to share the server with the whole team):

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

Confirm with /mcp inside a new session, or claude mcp list in the terminal.

.mcp.json details
  • The type field is required. An entry with a url but no type is read as a local (stdio) server and Claude Code rejects it with MCP server "koncili-mcp-erp" has a "url" but no "type". The value streamable-http is also accepted as an alias for http.
  • There is no global .mcp.json: this file is always project-scoped. The local and user scopes are stored in ~/.claude.json and managed by the claude mcp add command.
  • The first time you open the project, Claude Code asks for approval of the server coming from .mcp.json (it shows as ⏸ Pending approval in claude mcp list). Just run claude and approve it.

GitHub Copilot (VS Code)​

Copilot reads MCP servers from an mcp.json file. Create .vscode/mcp.json in your project root (or use MCP: Add Server from the command palette, Ctrl/Cmd+Shift+P):

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

After saving, open Copilot Chat in Agent mode, click Configure Tools (tools icon in the chat input) and confirm that Koncili tools appear in the list.

Mind the top-level key

In VS Code the top-level key is servers - not mcpServers, as in other clients.

info

MCP support in Copilot requires a recent VS Code version and a recent Copilot Chat extension. If mcp.json is not recognized, update both.

Cursor​

Cursor uses an mcp.json file. You can define it in two scopes:

  • Global (for all projects): ~/.cursor/mcp.json
  • Project-level: .cursor/mcp.json in the repository root
{
  "mcpServers": {
    "koncili-mcp-erp": {
      "url": "https://developers.koncili.com/mcp"
    }
  }
}

For remote servers Cursor only requires the url field - type is not needed.

Alternatively, use the Customize page in the Cursor sidebar to add and manage MCP servers, and confirm there that koncili-mcp-erp shows up as connected.

opencode​

opencode reads config from opencode.json (or opencode.jsonc, which allows comments). You can define it in two scopes:

  • Global (for all projects): ~/.config/opencode/opencode.json
  • Project-level: opencode.json in the repository root

Config files are merged, not replaced - the project file complements and overrides the global one. Remote MCP servers use "type": "remote":

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

The tools become available to the model as soon as the server is added to the config file. If they do not show up, restart opencode.

Verifying the Connection​

After configuration, run a quick test by asking your AI something that only Koncili documentation should answer. For example:

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

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

If the AI answers by citing documentation (instead of a generic guess), the connection is working. If it says the tool is unavailable, review the configured URL and restart or open a new session in your client.

Best Practices and Limitations​

  • Ask short, objective questions. Avoid very long prompts and go straight to the point to increase response accuracy.
  • Include Koncili context in the question. Whenever possible, include the word "Koncili" in the prompt. Example: prefer "What is an entry in Koncili?" instead of "What is an entry?" to avoid out-of-context interpretations.
  • Rate limit: MCP accepts up to 90 requests per minute.

Privacy and Data Handling​

Koncili MCP is designed to collect as little as possible:

  • No login or token required - MCP does not identify you or your company.
  • Searches with answers are not stored. When documentation can answer your question, nothing is recorded.
  • Unanswered searches are stored to improve documentation. When MCP cannot find an answer, it stores:
    • the text of your question - to understand what is missing in documentation;
    • an identifier derived from your IP address - the IP itself is not stored in plain text and is transformed cryptographically first;
    • date/time and which tool was used.

These records are used exclusively for documentation curation - not to track, profile, or identify integrators.

Do Not Send Sensitive Data in Questions

Because unanswered-question text is stored, do not include personal data, tokens, credentials, or sensitive information in MCP questions. Ask about documentation - do not paste real production data.

By connecting to and using Koncili MCP, you acknowledge this data handling process. Privacy questions: erp@koncili.com.

Support​

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