> 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/enterprise-rollout.md).

# Enterprise Rollout

### Overview

Organizations rolling out BalkanID MCP beyond a single laptop should plan around how each AI client handles **central deployment** and **central policy**. BalkanID hosts the production MCP server at `https://mcp.app.balkan.id/server/mcp`; no on-premises BalkanID MCP install is required.

Individual connection steps live under [Installation and Setup](/balkanid-mcp/installation-and-setup.md). This page covers org-wide patterns for Claude, Claude Code, VS Code, and Cursor.

{% hint style="info" %}
MCP must be **enabled for your BalkanID tenant** before users can connect. Your customer success representative can confirm tenant availability.
{% endhint %}

### Deployment options by client

Capabilities differ by AI client. The table below summarizes what IT can deploy centrally versus what each user must still do locally.

| Client                                     | Central deployment                   | Central policy (allow / block)                  | Per-user setup                |
| ------------------------------------------ | ------------------------------------ | ----------------------------------------------- | ----------------------------- |
| **Claude.ai / Claude Desktop** (connector) | Org admin adds connector             | Claude Enterprise connector settings            | Sign in with BalkanID (OAuth) |
| **Claude Code**                            | Yes — `managed-mcp.json` via MDM/GPO | Yes — `allowedMcpServers` / denylist            | Complete OAuth after install  |
| **VS Code**                                | No fleet-wide MCP push               | Yes — enterprise policies & GitHub org settings | Install server and sign in    |
| **Cursor**                                 | No fleet-wide MCP push               | Yes — Enterprise MCP allowlist                  | Configure server and sign in  |

{% hint style="warning" %}
**VS Code and Cursor do not support Claude Code–style managed MCP deployment.** Enterprise controls can approve or block BalkanID’s URL, but each developer still installs and connects the server on their machine. Share the client setup guides from [Installation and Setup](/balkanid-mcp/installation-and-setup.md) with your team rather than expecting MDM to push MCP configuration.
{% endhint %}

### Claude for Enterprise / Claude.ai

For Claude users, the recommended org path is a **custom connector** deployed by a Claude organization administrator — not personal or developer `mcp-remote` setup. See [Claude Desktop](/balkanid-mcp/installation-and-setup/claude-desktop.md) for connector versus fallback paths and policy notes.

1. Confirm MCP is enabled on the BalkanID tenant.
2. A **Claude organization administrator** adds BalkanID as a custom connector:
   * From the [MCP UI](https://mcp.app.balkan.id), use **Connect to Claude**, or
   * In Claude, open [connectors](https://claude.ai/customize/connectors) and add a custom connector with URL `https://mcp.app.balkan.id/server/mcp`
3. Publish or assign the connector for the organization per your Claude plan.
4. Each user signs in with BalkanID, selects the correct tenant, and completes consent.

{% hint style="info" %}
OAuth currently grants **both Read and Write** scopes. Read-only OAuth is not available yet — see [Authentication and Permissions](/balkanid-mcp/authentication-and-permissions.md).
{% endhint %}

{% hint style="info" %}
**Prefer Anthropic’s directory listing** when it becomes available for your organization. Until then, use the custom connector URL above.
{% endhint %}

### Claude Code

#### Fixed deployment with `managed-mcp.json`

For Claude Code fleets, IT can push a managed MCP configuration so every managed machine receives BalkanID MCP. Anthropic documents this as exclusive control via [`managed-mcp.json`](https://code.claude.com/docs/en/managed-mcp).

Deploy a file at the platform path:

| Platform    | Path                                                       |
| ----------- | ---------------------------------------------------------- |
| macOS       | `/Library/Application Support/ClaudeCode/managed-mcp.json` |
| Linux / WSL | `/etc/claude-code/managed-mcp.json`                        |
| Windows     | `C:\Program Files\ClaudeCode\managed-mcp.json`             |

Example (OAuth — preferred; no secrets in the file):

```json
{
  "mcpServers": {
    "balkanid": {
      "type": "http",
      "url": "https://mcp.app.balkan.id/server/mcp"
    }
  }
}
```

Push the file with your MDM, GPO, or Intune tooling (Jamf, configuration profiles, Group Policy, and similar).

{% hint style="warning" %}
Do **not** put API key secrets in `managed-mcp.json`. That file is readable by users on the machine. Each user should authenticate with **OAuth** (or per-user headers / environment variables if you use API keys).
{% endhint %}

After deployment, each user opens Claude Code, runs `/mcp`, and completes BalkanID OAuth for their account and tenant. Verify with “Call whoami on BalkanID MCP.”

On a managed machine, `claude mcp list` should show BalkanID when exclusive control is active. Attempting to add an unapproved server should fail with Anthropic’s enterprise MCP policy error.

#### Allowlist without exclusive control

If you do not want exclusive control, allowlist BalkanID’s URL in managed Claude Code settings via `allowedMcpServers` (and optionally `allowManagedMcpServersOnly`):

```json
{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.app.balkan.id/server/mcp" }
  ]
}
```

Users still add or receive the server themselves (or via `managed-mcp.json`); the allowlist blocks everything else. See Anthropic’s [managed MCP](https://code.claude.com/docs/en/managed-mcp) documentation for allowlist and denylist patterns.

### Microsoft Copilot

Roll out **BalkanID** as a custom Teams app (no Copilot Studio or Power Platform). Enable **Upload custom apps** in Teams setup policies, distribute [**`BalkanID-teams-app.zip`**](https://mcp.app.balkan.id/api/teams-app/download) (org submit or sideload), and share [Microsoft Copilot setup](/balkanid-mcp/installation-and-setup/microsoft-copilot.md) with users. Each user completes BalkanID OAuth in the connection manager so approvals and reviews are audited as that user.

### VS Code

VS Code does **not** offer a `managed-mcp.json`-style mechanism to push MCP server definitions to every developer machine. [Enterprise AI settings](https://code.visualstudio.com/docs/enterprise/ai-settings#configure-mcp-server-access) and [VS Code policies](https://code.visualstudio.com/docs/enterprise/policies) let you restrict which MCP servers developers may use — they do not centrally install BalkanID for all users.

Common enterprise controls include:

* **`ChatAllowedMcpServers`** — allow BalkanID’s URL (`https://mcp.app.balkan.id/server/mcp`) while blocking unapproved servers
* **`ChatDeniedMcpServers`** — block specific servers (deny rules take precedence over allow)
* **`ChatMCP`** — limit MCP install sources (for example registry-only or disabled)
* **`McpGalleryServiceUrl`** — point VS Code at a private MCP registry with a curated catalog
* **GitHub org / enterprise settings** — [managed Copilot settings](https://code.visualstudio.com/docs/enterprise/ai-settings#deploy-copilot-managed-settings) for Copilot Enterprise or Business

After policy is in place, point developers to [VS Code setup](/balkanid-mcp/installation-and-setup/vs-code.md). **OAuth one-click** from the MCP UI is the preferred connection method. Each developer installs the server and completes BalkanID sign-in. For Read-only access, use an API key as described in [Authentication and Permissions](/balkanid-mcp/authentication-and-permissions.md).

You may commit a workspace `.vscode/mcp.json` example for a specific repository to share configuration with that project team. That pattern is project-scoped, not org-wide MDM deployment.

### Cursor

Cursor Enterprise provides [MCP allowlist and network controls](https://cursor.com/docs/enterprise/model-and-integration-management#mcp-server-trust-management). Adding a server to the allowlist does **not** push it to users’ machines — team members still configure the server in their own Cursor settings.

Common enterprise controls include:

* **MCP Configuration allowlist** (Enterprise dashboard) — approve BalkanID’s URL and optionally restrict tools or network egress per server
* **Team marketplace** (Teams / Enterprise) — distribute an approved MCP plugin; each developer may still need to authenticate with BalkanID
* **MDM** — deploy `~/.cursor/permissions.json` for MCP auto-run allowlists (tool execution policy, not server installation)

After policy is in place, point developers to [Cursor setup](/balkanid-mcp/installation-and-setup/cursor.md). **OAuth one-click** from the MCP UI is the preferred connection method.

### Planning your rollout

Start by confirming MCP is enabled on the BalkanID tenant and identifying which AI clients your organization uses. For Claude, have an organization administrator deploy the custom connector before users connect individually. For Claude Code fleets, use `managed-mcp.json` or an allowlist through your existing device-management tooling.

For Microsoft Copilot, allow custom apps and distribute the agent package before user pilots; confirm OAuth sign-in and `whoami` in a pilot tenant before broad publish. For VS Code and Cursor, plan on enterprise allowlisting plus per-user setup — there is no equivalent to pushing BalkanID MCP to every machine from IT. Pilot with a small group of administrators or risk managers using OAuth, confirm that `whoami` and `help` succeed for the roles you intend to support, and document which BalkanID roles and scopes are required for your workflows. Issue Read-only API keys only where investigation-only access is explicitly needed.


---

# 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/enterprise-rollout.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.