> 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/claude-desktop.md). # Claude Desktop Connect [Claude](https://claude.com/docs/connectors/custom/remote-mcp) to BalkanID MCP from [Claude Desktop](https://claude.ai/download) or [Claude.ai](https://claude.ai). **Recommended:** have your **organization administrator** deploy BalkanID as a [**custom connector**](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for Claude Team / Enterprise (see Enterprise Rollout). Personal or developer-only setup is supported when your plan allows it, but is **at your own risk** and must follow your company's AI and data policies. Use **`mcp-remote`** in Claude Desktop's config file only when the org connector path is not available. ### Choose your path | Path | When to use | Auth | | -------------------------------------- | ------------------------------------------------------------------- | ---------------- | | **Org custom connector** (recommended) | Your Claude org admin has deployed BalkanID for the organization | OAuth | | **Personal custom connector** | Individual Claude account; confirm this is allowed by your employer | OAuth | | **Claude Desktop + `mcp-remote`** | Org connector not available; developer fallback only | OAuth or API key | ### Custom connector — OAuth (recommended) This is the preferred way to connect. BalkanID uses Claude's remote MCP connector flow — no local `mcp-remote` config required. For employees at a company with Claude Team or Enterprise, **we recommend the organization path below** — not a personal connector or developer config on a work machine. #### Organization accounts (recommended) On Claude **Team / Enterprise**, **organization administrators** should add BalkanID as a connector for the org. This keeps rollout, access, and audit aligned with company policy. 1. Open , sign in, and confirm the correct **tenant**. 2. In **OAuth Connectors**, click **Connect to Claude** — or add the connector from Claude admin / connectors settings. 3. Set the connector URL to `https://mcp.balkanid.app/server/mcp`. 4. Complete BalkanID sign-in, pick your **tenant**, and grant consent. 5. Assign or publish the connector for your organization as required by your Claude plan. {% hint style="warning" %} If you are **not** a Claude org admin, ask your admin to deploy BalkanID (see Enterprise Rollout). Do **not** use personal or developer setup on a work account unless your company explicitly allows it. {% endhint %} #### Personal accounts Use this only on a **personal** Claude account, or when your employer has confirmed that individual connector setup is permitted. {% hint style="warning" %} Personal or self-service connector setup is **at your own risk**. You are responsible for complying with your organization's policies on AI tools, identity data, and third-party integrations. BalkanID recommends **org-wide deployment by an administrator** whenever you access a **company BalkanID tenant**. {% endhint %} 1. Open , sign in, and confirm the correct **tenant**. 2. In **OAuth Connectors**, click **Connect to Claude** — or open [Claude connectors](https://claude.ai/customize/connectors) and add a custom connector. 3. Set the connector URL to: `https://mcp.balkanid.app/server/mcp` 4. Complete BalkanID sign-in, pick your **tenant**, and grant consent. 5. Confirm BalkanID appears among your connected tools in Claude. {% hint style="info" %} OAuth currently requires **both Read and Write** scopes at consent. See Authentication and Permissions. {% endhint %} ### Claude Desktop — `mcp-remote` (when connector is unavailable) Use this path only when you cannot add or use an org or personal custom connector — for example while waiting for admin rollout — or when you need a **Read-only** API key. {% hint style="warning" %} Developer / **`mcp-remote`** setup (Settings → Developer, editing `claude_desktop_config.json`) is a **fallback**, not the recommended production path. It is **at your own risk** and must be **explicitly allowed** under your company's AI, security, and data-handling policies. BalkanID recommends **org-wide connector deployment** for access to a company tenant. {% endhint %} Claude Desktop does not support one-click HTTP install. It runs a local [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) helper (via `npx`) and reads `claude_desktop_config.json`. #### Prerequisites * [Node.js 18+](https://nodejs.org/) on the machine running Claude Desktop (Claude runs `npx`; `mcp-remote` may download on first connect) #### 1. Open Developer settings and the MCP config file 1. In Claude Desktop, open **Settings** → **Developer**. 2. If you have never used MCP, turn on **Developer mode** (or **MCP**) so the app can use a config file. 3. Click **Edit Config**. Claude opens `claude_desktop_config.json` in your default editor. If the file does not exist yet, enabling Developer mode creates it. You can also edit the file manually: * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` #### 2. OAuth via `mcp-remote` (no API token in the file) Paste a **full config** if the file is new or empty. If you already have other MCP servers, add a new entry inside `mcpServers` (comma-separated from existing entries): ```json { "mcpServers": { "BalkanID MCP Server": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.balkanid.app/server/mcp", "--transport", "http-only" ] } } } ``` No `Authorization` header is required — `mcp-remote` runs the OAuth flow in a browser on first connect. #### 3. Restart Claude and sign in 1. Save `claude_desktop_config.json`. 2. Fully quit Claude Desktop and open it again. 3. On first connect, complete BalkanID sign-in, pick your **tenant**, and grant consent in the browser window. 4. Confirm the MCP (hammer) icon appears near the chat input. #### API key via `mcp-remote` (Read-only or OAuth unavailable) Use an API key when OAuth via `mcp-remote` fails, or when you need **Read-only** access. **Guided setup from the MCP UI** 1. Create an API key in the [MCP UI](https://mcp.balkanid.app) (see Installation and Setup). 2. Open **Connect → Connect to Claude** (Claude Desktop modal). 3. Use **Copy full config** (new setup) or **Copy server entry** (merge into an existing `mcpServers` block). 4. In Claude Desktop, open **Settings → Developer → Edit Config** and paste the JSON. 5. Save, fully quit and reopen Claude Desktop. **Manual configuration (fallback)** ```json { "mcpServers": { "BalkanID MCP Server": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.balkanid.app/server/mcp", "--transport", "http-only", "--header", "Authorization:${BALKANID_MCP_AUTH_HEADER}" ], "env": { "BALKANID_MCP_AUTH_HEADER": "Bearer YOUR_TOKEN_HERE" } } } } ``` ### Verify Ask Claude: “Call whoami on BalkanID MCP.” You should see your email and tenant ID. ### Official documentation Anthropic documentation for custom connectors (remote MCP): * [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) — Claude Help Center * [Third party connectors with remote MCP](https://claude.com/docs/connectors/custom/remote-mcp) — Claude Docs --- # 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/claude-desktop.md?ask=&goal= ``` `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.