# Claude Code Enterprise rollout

> Roll out Claude Code with settings delivery, MCP policy, analytics, auto mode and custom gateway boundaries.

URL: https://docs.passion8.cc/en/docs/claude-code/enterprise-rollout
Language: en
Publisher: Passion8

Design providers, identity, networking, permissions, MCP, observability and support together. Otherwise deployments tend to become usable but ungoverned, configured but ineffective, or impossible to attribute for billing and security.

See [enterprise controls](https://docs.passion8.cc/en/docs/claude-code/enterprise-controls) for governance and [adoption communications](https://docs.passion8.cc/en/docs/claude-code/adoption-communications) for announcements, champions, drip campaigns and FAQs.




With a custom base URL or Passion8, server-managed settings generally do not govern gateway behavior. Prioritize endpoint settings, templates, MDM/registry, system managed-mcp.json and gateway policy.




## Rollout decision map

```text
1. Provider / identity
   ├─ Direct Anthropic Team / Enterprise?
   │  ├─ Yes: organizational identity, SSO/SCIM, server settings and analytics
   │  └─ No: Passion8/custom gateway, enterprise IdP, key mapping and endpoint policy
   └─ Key ownership: individual, team service account, project or short-lived token

2. Network
   ├─ Direct access to api.anthropic.com / claude.ai / downloads.claude.ai?
   ├─ Corporate proxy, TLS inspection, CA or mTLS?
   └─ Gateway: define URL, allowlist, retries, limits and logging boundaries

3. Settings delivery
   ├─ Server-managed: official cloud delivery for Anthropic organizations
   └─ Endpoint-managed: MDM, registry, system files and templates for enforced/custom-provider policy

4. Permissions
   ├─ Default allow / ask / deny
   ├─ Auto mode: environment / allow / soft_deny / hard_deny
   └─ Disable bypass; protect sensitive files and dangerous shell; isolate risky projects

5. MCP
   ├─ Disable, fixed deployment, approved catalog, plugin-only or denylist
   ├─ System managed-mcp.json cannot be delivered through server settings
   └─ Govern OAuth, headersHelper, environment and token storage separately

6. Observability
   ├─ Adoption: users, sessions, acceptance and code contributions
   ├─ Cost: spend, tokens, model, project, team and cache hits
   ├─ Tools: Bash, Edit, MCP, hooks and auto decisions
   └─ Errors: auth, network, provider errors, tools and policy denials

7. Training / support
   ├─ Pilot users, champions, templates and default permissions
   ├─ Troubleshoot URL, token, proxy, CA, MCP and settings merge
   └─ Support queues, tickets, escalation and change announcements
```

## Settings delivery methods

| Method | Source | Best fit | Limitation |
| --- | --- | --- | --- |
| Server-managed | Official cloud, fetched at startup/runtime | Direct Team/Enterprise, unmanaged devices, lightweight consistency | Depends on official identity/endpoints; does not govern custom gateway behavior |
| Endpoint-managed | MDM, preferences, registry, system files or images | Managed devices, custom gateways and enforced policies | Needs device management/install scripts and IT change processes |
| Local templates | User/project settings and devcontainers | Pilots, small teams and project defaults | Users can edit them; not sole compliance enforcement |
| Gateway policy | Accounts, models, rates, logs and data controls | Custom providers, billing and routing | Controls gateway requests, not local Bash, MCP or files |

The difference is the trust boundary: server settings come from Anthropic for official identities/providers; endpoint settings come from enterprise devices and suit enforced client behavior and custom providers.




For Passion8, place model access, budgets, rates and retention in gateway policy; place file access, shell, MCP installation and auto-mode boundaries in endpoint settings.




## Passion8 and custom gateways

Do not assume official organizational settings automatically apply to a third-party path. Recommended controls:

| Control | Practice |
| --- | --- |
| Base URL | Deliver ANTHROPIC_BASE_URL=https://passion8.cc through managed settings or environment templates |
| Token | Enterprise vault, MDM secret, short-lived tokens or self-service; never repository commits |
| Models/budgets | Gateway model allowlist, project/team budgets and rates |
| Protocol | Verify tools, caching, streaming, discovery, beta fields and errors |
| Audit | Attribute requests to users, teams, projects, tokens, models and request IDs |
| Rollback | Retain an authorized fallback profile and explicit switching/verification commands |

```bash
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-ENTERPRISE_OR_PASSION8_TOKEN"
claude -p "Check the current provider, model and basic tools"
```

Gateway acceptance checks:

| Check | Passing condition |
| --- | --- |
| Request path | No extra /v1 on the Claude Code root; Messages API works |
| Streaming | Long output remains connected; errors are readable |
| Prompt cache | Read/write fields forwarded or an explicit alternative documented |
| Tool use | Calls, MCP references and results preserved |
| Model picker | Discovery shows gateway-permitted models when enabled |
| Errors | Distinguish keys, permissions, limits and upstream failures |

## Managed MCP policy

Deliver managed-mcp.json through administrators, MDM, images, installers or configuration management at the fixed system path; server-managed settings cannot distribute it.

| Platform | System 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` |

| Policy | Usage |
| --- | --- |
| Disable MCP | Empty server map for sensitive repositories or early pilots |
| Fixed deployment | Approved GitHub, Jira, read-only databases and retrieval |
| Approved catalog | Permit listed servers while blocking arbitrary URLs/stdio |
| Denylist | Block risky servers, unknown hosts and arbitrary command executors |
| Separate tokens | OAuth, headersHelper, keychain or short-lived credentials |

```json
{
  "mcpServers": {
    "github-enterprise": {
      "type": "http",
      "url": "https://github.example.com/mcp"
    },
    "docs-readonly": {
      "type": "stdio",
      "command": "/usr/local/bin/company-docs-mcp",
      "args": ["--readonly"]
    }
  }
}
```

Ensure trusted definitions, protected credentials, auditable output and interceptable writes. System files may be readable by users; do not place plaintext API keys there.

## Analytics and telemetry

Answer five questions: who uses it, what it costs, whether caching works, whether tools exceed boundaries and where failures cluster.

| Group | Metrics | Sources |
| --- | --- | --- |
| Adoption | Active users/teams, sessions, task types, acceptance and pilot conversion | Analytics, OTel, surveys and startup logs |
| Cost | Spend, tokens, models, cost centers and task cost | Provider/Passion8 consoles, gateway and OTel |
| Cache | Reads/writes, TTL hits, invalidation and schema changes | Usage, logs, OTel and reports |
| Tools | Tool counts, denials, hook failures and auto decisions | Logs/traces, debug and SIEM |
| Errors | HTTP status, TLS/proxy, MCP timeout, settings and hard denials | Gateway, OTel, helpdesk and client debug |

```bash
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.example.com:4317"
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,tool=claude-code"
```




Keep raw prompts, responses, tool content and API bodies disabled by default. They can contain code, customer data, secrets, tickets and designs. Enable briefly in isolated diagnostics only.




## Enterprise auto mode

Use auto mode for low-risk, reversible, bounded development. Define environment, allow, soft-deny and hard-deny policy while retaining "$defaults".

```json
{
  "autoMode": {
    "environment": [
      "Company source code lives under github.example.com/acme and approved internal GitLab groups.",
      "Production credentials are never available in developer workstations.",
      "Approved package registries are npm.corp.example.com and pypi.corp.example.com.",
      "Network egress goes through the corporate proxy and approved gateways."
    ],
    "allow": [
      "$defaults",
      "Read(./src/**)",
      "Read(./docs/**)",
      "Edit(./src/**)",
      "Edit(./tests/**)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git diff *)"
    ],
    "soft_deny": [
      "Bash(npm install *)",
      "Bash(pip install *)",
      "WebFetch(*)",
      "mcp__jira__create_*"
    ],
    "hard_deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*private_key*)",
      "Bash(curl * | sh)",
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "mcp__prod_database__write_*"
    ]
  }
}
```

Use soft_deny for actions needing confirmation or a different process, such as dependencies, internet access or tickets. Use hard_deny for forbidden secret reads, deletions, pushes or production writes.

## Security baseline

| Control | Requirement |
| --- | --- |
| Devcontainer/sandbox | Isolate risky repositories in containers, VMs, worktrees or sandboxes; no production secrets |
| Disable bypass | Prevent one-click policy bypass |
| Sensitive files | Deny environment files, keys, certificates, customer exports, dumps and cloud credentials |
| Proxy/CA/mTLS | Standardize configuration and startup allowlists independently of remote settings |
| Tokens | Short-lived/individual/service-account mapping with revocation, rotation, least privilege and attribution |
| ZDR | Does not automatically cover transcripts, MCP, OTel, debug, gateway or proxy logs |
| Versions | Minimum version, release windows, rollback and pilot rings |
| Support | Diagnostic scripts and escalation for endpoints, tokens, networks, MCP and policy |

Endpoint-managed example:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://passion8.cc",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.example.com:4317",
    "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*private_key*)",
      "Bash(curl * | sh)",
      "Bash(rm -rf *)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "forceRemoteSettingsRefresh": false
}
```

Do not require remote refresh from api.anthropic.com on offline or gateway-only devices; this can block startup.

## 30 / 60 / 90 rollout

| Phase | Goal | Controls | Metrics |
| --- | --- | --- | --- |
| Days 0–30 | Pilot providers, network, permissions and cost | 20–50 users, gateway profile, proxy/CA/mTLS, no bypass, sensitive-file deny, read-only/no MCP, basic OTel | Installation/first-task success, error distribution, daily cost, cache fields and ticket categories |
| Days 31–60 | Expand to core teams and standard templates | MDM/registry settings, project templates, approved MCP, low-risk auto policy, dashboards and attribution | Weekly activity, completion, denials, MCP timeouts, cache hits, team costs, errors and training |
| Days 61–90 | Scale into routine governance | Ring releases, team policies, layered gateway controls, token rotation, retention audit and support playbook | Coverage, retention, lower task cost, zero severe incidents, explainable policy and rollback drills |

## Release checklist

| Check | Acceptance criterion |
| --- | --- |
| Provider | Identity, tokens, models, budgets and rollback established |
| Network | Proxy, CA, mTLS, allowlist, offline install and startup verified |
| Settings | Clear server/endpoint roles; custom gateways do not rely solely on server settings |
| Permissions | Sensitive-file/command denies, no bypass, no keys in templates |
| MCP | System deployment, protected credentials and write policies |
| Auto mode | Environment/allow/soft_deny/hard_deny configured with defaults retained |
| Observability | Adoption, costs, caching, tools and errors have dashboards/alerts |
| Privacy | Documented retention boundaries across provider, local and gateway systems |
| Training | Pilot materials, troubleshooting, support, announcements and escalation published |

## Related pages



- [Adoption communications](https://docs.passion8.cc/en/docs/claude-code/adoption-communications): Champions, launch announcements, drip campaigns, FAQs and Passion8 guidance.
- [Auto-mode policy](https://docs.passion8.cc/en/docs/claude-code/auto-mode-policy): Trusted infrastructure, allow/deny rules, shell classification and denial review.
- [Enterprise controls](https://docs.passion8.cc/en/docs/claude-code/enterprise-controls): Managed settings, MCP, plugins, analytics, compliance and GHES.