> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/installation-and-setup.md).

# Installation and Setup

You can connect BalkanID MCP to any AI assistant that supports the Model Context Protocol. 

## Pre-requisites

* Node.js: 18 LTS or later
* npm: 9.x or later
* Active BalkanID tenant
* MCP-compatible AI

{% stepper %}
{% step %}

### Step 1 - API Key 

* Navigate to mcp.app.balkan.id -> Generate New API Key<br>

  <div data-with-frame="true"><figure><img src="/files/xrbh3C4DhpR2RM7zyZeG" alt=""><figcaption></figcaption></figure></div>
* Give the key a name (e.g. claude-mcp) and copy it and store it securely— it is only shown once<br>

  <div data-with-frame="true"><figure><img src="/files/zwC6RfEnp4sJ1IJAQQrl" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
**API Key Scopes:**\
Read: Allows all read operations\
Write: Allows write operations like create/edit\
\
API keys are not permitted to remain active for more than 90 days. This is because API keys are generally considered high-risk credentials across systems, and regular rotation is a recommended security best practice.
{% endhint %}
{% endstep %}

{% step %}

### Step 2 - Common Setups

#### Claude Desktop

* Click on "Connect" →  "Connect to Claude" and follow along the instructions
* Open Developer settings

  In Claude Desktop, go to **Settings** → **Developer**. If you have never used MCP, turn on Developer (or MCP) so the app can use a config file.
* Edit your config file

  Create or open this file on your computer:

  macOS

  ```
  ~/Library/Application Support/Claude/claude_desktop_config.json
  ```

  Windows

  <pre><code><strong>%APPDATA%\Claude\claude_desktop_config.json
  </strong></code></pre>
* Paste the JSON\
  **Copy full config** if the file is new or empty. If you already have other servers, use **Copy server entry** and paste it inside `mcpServers`, with a comma between entries so the JSON stays valid.\
  Copy the JSON that is prompted in the UI&#x20;
* Restart Claude

  Save the file, quit Claude Desktop completely, and open it again. You should see the MCP (hammer) icon by the chat box.

#### VS Code

* Click on “Connect” → “Connect to VS Code” and follow the one-click installation process.

  <div data-with-frame="true"><figure><img src="/files/omeads9xJR8Mob0RKw1X" alt=""><figcaption></figcaption></figure></div>

  <div data-with-frame="true"><figure><img src="/files/JhfqF6hv2EiE40s5yosy" alt=""><figcaption></figcaption></figure></div>

#### Cursor

* Click on “Connect” → “Connect to VS Code” and follow the one-click installation process

  <div data-with-frame="true"><figure><img src="/files/3vj9OTy5cygd4dFU1oNe" alt=""><figcaption></figcaption></figure></div>

  <div data-with-frame="true"><figure><img src="/files/CIWPeNQf8iGvzDXpAcUg" alt=""><figcaption></figcaption></figure></div>

{% endstep %}

{% step %}

### Step 3 - Verification

Verify the connection. The BalkanID MCP server should now be accessible through the setup MCP-compatible AI agent
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/balkanid-mcp/installation-and-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.