> 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

## Installation and Setup

### Overview

BalkanID MCP is a **hosted** server. You connect your AI client to BalkanID over HTTPS — you do not run the BalkanID MCP server on your laptop.

MCP UI and endpoint:

* UI: <https://mcp.balkanid.app>
* MCP URL: `https://mcp.balkanid.app/server/mcp`

{% hint style="info" %}
Your customer success representative can confirm MCP is enabled for your tenant. If MCP is disabled, tool calls fail until it is enabled.
{% endhint %}

### Prerequisites

* Active BalkanID tenant with MCP enabled
* BalkanID user who can complete OAuth consent (preferred) or create an MCP API key
* MCP-compatible AI client (Claude, Claude Code, Cursor, VS Code, or similar)

### Preferred path — OAuth

**OAuth is the recommended connection method.** Open the [MCP UI](https://mcp.balkanid.app), sign in, confirm the correct **tenant**, and use the **OAuth Connectors** section:

1. Copy the MCP URL (`https://mcp.balkanid.app/server/mcp`), or
2. Use one-click **Connect to VS Code**, **Connect to Cursor**, **Connect to Claude**, **Connect to ChatGPT**, or **Connect to Perplexity**, or open **Microsoft Copilot** for the Teams app flow

Then complete sign-in and consent in your client. No API token is pasted into the config for this flow.

{% hint style="info" %}
OAuth currently grants **both Read and Write** scopes. Read-only OAuth is not available yet — see Authentication and Permissions. Use an API key when you need Read-only access.
{% endhint %}

### Client setup guides

| Client                                               | Guide                                        |
| ---------------------------------------------------- | -------------------------------------------- |
| **Claude** (Claude.ai connectors and Claude Desktop) | Claude Desktop                               |
| **Claude Code**                                      | Claude Code                                  |
| **Cursor**                                           | Cursor                                       |
| **VS Code**                                          | VS Code                                      |
| **Microsoft Copilot**                                | Microsoft Copilot (OAuth via Teams app only) |
| **ChatGPT**                                          | ChatGPT                                      |
| **Perplexity**                                       | Perplexity                                   |

\
Each guide covers one-click / guided install from the MCP UI and a manual fallback.

### API key (when OAuth is unavailable)

Use **Bearer Auth Keys** in the MCP UI when your client does not support OAuth, or when you need a Read-only key.

1. Open <https://mcp.balkanid.app> and sign in.
2. Confirm the correct **tenant** is selected.
3. Click **Generate New API Token** (or **Generate New API Key**).
4. Name the key, choose an expiry (up to **90 days**), and select scopes (**Read** required; add **Write** for mutating actions).
5. Generate the key and copy the connection token. It is shown **only once**.

Store the token securely. Treat it like a password.

Then open **Connect** next to the key and choose your client (VS Code, Cursor, or Claude Desktop), or paste the manual config from the client guides.

### Other MCP clients

| Setting            | Value                                                     |
| ------------------ | --------------------------------------------------------- |
| **URL**            | `https://mcp.balkanid.app/server/mcp`                     |
| **Transport**      | HTTP (streamable)                                         |
| **Authentication** | OAuth 2.1 (preferred), or `Authorization: Bearer <token>` |

### Verify the connection

In your AI assistant, ask:

* “Use BalkanID MCP and call whoami.”
* or “Show my BalkanID email and tenant.”

You should see your email and tenant ID. Then try:

* “List my BalkanID integrations.”
* or “Call help on BalkanID MCP.”

If verification fails, see Troubleshooting.

### Org-wide deployment

For Claude Enterprise connector rollout and Claude Code `managed-mcp.json`, see Enterprise Rollout. VS Code and Cursor support enterprise **allowlisting** only — not fleet-wide MCP push.


---

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