# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.