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

Your customer success representative can confirm MCP is enabled for your tenant. If MCP is disabled, tool calls fail until it is enabled.

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, etc.)

Preferred path — OAuth

OAuth is the recommended connection method. Open the MCP UI, 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; open Microsoft Copilot for the Teams app flow; or select Windsurf, Cline, Zed, Codex CLI, ChatGPT Desktop, OpenCode, or LibreChat to copy the matching config (or follow the guide link)

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

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.

Client setup guides

Client	Guide
Claude (Claude.ai connectors and Claude Desktop)	Claude Desktop
Claude Code	Claude Code
Cursor	Cursor
VS Code	VS Code
Windsurf (Cascade)	Windsurf
Cline	Cline
Zed	Zed
Codex CLI (and ChatGPT IDE extension)	Codex CLI
ChatGPT Desktop	ChatGPT Desktop
OpenCode	OpenCode
LibreChat	LibreChat
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.