> 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.balkanid.app/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, Cursor, Windsurf, Cline, Zed, Codex CLI, ChatGPT Desktop, OpenCode, and LibreChat.

{% 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  |
| **Windsurf** (Cascade)                     | No fleet-wide MCP push                                  | Team MCP allowlist (Devin-branded desktop app)  | Configure server and sign in  |
| **Cline**                                  | Yes — `remoteMCPServers` enterprise config              | Yes — `blockPersonalRemoteMCPServers`           | Complete OAuth after install  |
| **Zed**                                    | No fleet-wide MCP push                                  | No enterprise-specific control                  | Configure server and sign in  |
| **Codex CLI / ChatGPT Desktop**            | Yes — `requirements.toml` via file, MDM, or admin panel | Yes — `mcp_servers` identity allowlist          | Complete OAuth after install  |
| **OpenCode**                               | Central org config exists for providers/SSO, not MCP    | No MCP-specific allowlist                       | Configure server and sign in  |
| **LibreChat**                              | Yes — `librechat.yaml` is the operator-owned config     | Yes — role-based overrides for remote servers   | Sign in with BalkanID (OAuth) |

{% hint style="warning" %}
**VS Code, Cursor, Windsurf, Zed, and OpenCode do not support Claude Code–style managed MCP deployment.** Enterprise controls (where available) 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 for these clients.
{% 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 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.balkanid.app), use **Connect to Claude**, or
   * In Claude, open [connectors](https://claude.ai/customize/connectors) and add a custom connector with URL `https://mcp.balkanid.app/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.
{% 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.balkanid.app/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.balkanid.app/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.balkanid.app/api/teams-app/download) (org submit or sideload), and share Microsoft Copilot setup 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.balkanid.app/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. **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.

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. **OAuth one-click** from the MCP UI is the preferred connection method.

### Windsurf

Classic Cascade has no fleet-wide MCP push or admin allowlist — each developer configures `mcp_config.json` individually. On the newer Devin-branded desktop app, **team admins** can toggle MCP access for the team and allowlist approved MCP servers; once any server is allowlisted, all non-allowlisted servers are blocked for that team.

* **Team MCP allowlist** (Devin Desktop team settings, admin only) — approve BalkanID's server URL for the team
* **Custom MCP registry** (Enterprise) — replace the default marketplace with a curated internal registry

After policy is in place, point developers to Windsurf setup. **OAuth one-click** from the MCP UI is the preferred connection method; each developer still installs and connects the server themselves.

### Cline

Cline Enterprise can push a hosted remote MCP server to every user's client centrally — this is the closest fit among the newer clients to Claude Code's `managed-mcp.json` pattern.

```json
{
  "remoteMCPServers": [
    {
      "name": "BalkanID MCP Server",
      "url": "https://mcp.balkanid.app/server/mcp",
      "alwaysEnabled": true
    }
  ],
  "blockPersonalRemoteMCPServers": true
}
```

Configure this through your organization's Cline remote configuration. `alwaysEnabled` prevents users from disabling the server; `blockPersonalRemoteMCPServers` stops users from adding their own remote servers alongside it. Each user still completes BalkanID OAuth on first use — the push installs the connection, not the authentication.

### Zed

Zed has no enterprise-specific mechanism for centrally deploying or restricting MCP context servers today. Each developer adds BalkanID under **Settings → AI → MCP Servers**, or teams can commit a project-level `.zed/settings.json` with the `context_servers` block so contributors on that project share the same server definition (each still authenticates individually).

Share the Zed setup guide with your team; there is no MDM or admin allowlist to configure.

### Codex CLI and ChatGPT Desktop

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share one enterprise mechanism: a `requirements.toml` file that allowlists MCP servers by identity. An empty or missing `mcp_servers` allowlist disables all MCP servers; a present allowlist permits only servers matching an approved identity.

Deploy `requirements.toml` at the platform path:

| Platform    | Path                                           |
| ----------- | ---------------------------------------------- |
| macOS/Linux | `/etc/codex/requirements.toml`                 |
| Windows     | `%ProgramData%\OpenAI\Codex\requirements.toml` |

Allow BalkanID by matching on its URL, since it's a Streamable HTTP server:

```toml
[mcp_servers.balkanid]
identity = { url = "https://mcp.balkanid.app/server/mcp" }
```

Push the file with your existing MDM (on macOS, as a base64-encoded `com.openai.codex:requirements_toml_base64` payload), or assign it through OpenAI's cloud-managed admin panel for ChatGPT Enterprise plans instead of a local file. After policy is in place, each user runs `codex mcp login balkanid` (or completes OAuth in the desktop app) to authenticate.

### OpenCode

OpenCode supports a single central organization config for AI providers and SSO, but does not document an MCP-server-specific allowlist. Central deployment and policy for BalkanID MCP on OpenCode is not currently available — share the OpenCode setup guide with your team for individual configuration.

### LibreChat

LibreChat is self-hosted, so `librechat.yaml` is inherently your organization's central, operator-owned configuration — there is no separate "enterprise" tier to unlock.

```yaml
mcpServers:
  balkanid:
    type: streamable-http
    url: 'https://mcp.balkanid.app/server/mcp'
```

Deploying this in `librechat.yaml` makes BalkanID available to every user of your LibreChat instance. Each user still completes their own BalkanID OAuth consent, so tool calls run under their identity. Use LibreChat's role-based permissions if you need to restrict which users may add or override remote MCP servers beyond what's centrally configured.

### 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 and Cline fleets, use `managed-mcp.json` / `remoteMCPServers` or an allowlist through your existing device-management tooling. For Codex CLI and ChatGPT Desktop, deploy `requirements.toml` through MDM or the cloud-managed admin panel before broad rollout.

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, Cursor, Windsurf, Zed, and OpenCode, plan on enterprise allowlisting (where available) plus per-user setup — there is no equivalent to pushing BalkanID MCP to every machine from IT. For LibreChat, add BalkanID to `librechat.yaml` once for your whole instance. 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balkan.id/balkanid-mcp/enterprise-rollout.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.