Deploying the registry

Almost everything the registry writes lives in committed files, so most of the rollout is “merge the catalog and let existing entry points run sync”. No per-developer install campaign: choose the channels that match your org and layer them.

Choosing channels

Channel	Covers	Dev-machine footprint
Repo + CI drift gate	Project configs for every dev who pulls	none
Claude Code SessionStart hook	Self-healing configs each session	none (npx on demand)
OpenCode autosync	OpenCode users at startup	none (plugin already loads)
MDM / login script	User-level configs (Claude Desktop, ~/.claude.json)	one scripted command

CI drift gate

registry sync --check exits 1 when committed configs drift from the catalog — pair it with the scan gate:

.github/workflows/mcp-registry.yml

name: MCP registry drift

on:
  pull_request:
    paths:
      - '.ringzero/**'
      - '**/.mcp.json'
      - '**/.vscode/mcp.json'
      - '**/.cursor/mcp.json'
      - '**/opencode.json'
      - '**/opencode.jsonc'

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx @ringzero/mcp-scan@latest registry validate
      - run: npx @ringzero/mcp-scan@latest registry sync --check

When the catalog changes, run registry sync locally (or let a bot do it) and commit the updated configs + lock file in the same PR.

Tip

A conflict (a hand-added server shadowing a catalog name) keeps CI red on purpose — it means a dev’s private entry and the org’s entry disagree. Resolve by removing the local entry or renaming one side; sync never overwrites what it doesn’t own.

Claude Code SessionStart hook

Commit the hook once and every session self-heals its MCP config:

.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "npx -y @ringzero/mcp-scan registry sync --quiet" }
        ]
      }
    ]
  }
}

ringzero-mcp init --print-hooks claude-code prints this together with the usage-auditing hooks. --quiet prints nothing when clean and a single line when it applied changes, so session startup stays clean. Repos without a catalog are a silent no-op.

OpenCode autosync

If your org already ships @ringzero/opencode-mcp-guard, the registry deploys itself: the plugin applies a project-scope sync at startup whenever a catalog is present.

• Changes to opencode.json take effect on the next OpenCode restart — the plugin says so on stderr when it applied changes.
• Failures never block the session (fail-open), conflicts are reported.
• Opt out per environment with RINGZERO_MCP_REGISTRY_AUTOSYNC=0.

Machine scope via MDM or login scripts

User-level configs (Claude Desktop, ~/.claude.json, ~/.cursor/mcp.json, user OpenCode) are the one surface a repo can’t carry. Ship one command through whatever your org already runs on login:

Windows (Intune / GPO)

# Scheduled task or Intune remediation script — run at logon
$env:RINGZERO_MCP_REGISTRY = '\\fileserver\ringzero\mcp-registry.json'
npx -y @ringzero/mcp-scan registry sync --machine --quiet

macOS (Jamf / launchd)

# LaunchAgent or Jamf policy — run at login
export RINGZERO_MCP_REGISTRY=/Library/RingZero/mcp-registry.json
npx -y @ringzero/mcp-scan registry sync --machine --quiet

Linux (profile / systemd user)

# ~/.profile, or a systemd user unit
export RINGZERO_MCP_REGISTRY="$HOME/.config/ringzero/mcp-registry.json"
npx -y @ringzero/mcp-scan registry sync --machine --quiet

Caution

Run machine-scope sync at login or before harness apps start — a running Claude Desktop or Claude Code session can rewrite its own config file and race the sync. Machine state lives in ~/.ringzero/mcp-registry-state.json.

Rollout playbook

1. Seed the catalog — ringzero-mcp registry add the servers your org already blesses (or registry pull once the platform catalog ships — the pulled catalog also carries your org’s control level, so runtime enforcement rides the same file). Merge it with "harnesses" limited to one harness if you want a canary.

2. Turn on the CI drift gate so the catalog and configs can’t diverge.

3. Commit the SessionStart hook / plugin entry — devs start receiving servers as they pull and restart sessions.

4. Widen harnesses to "all", then add the MDM machine-scope job for Claude Desktop coverage.

5. Retire a server by flipping "enabled": false (managed removal everywhere on next sync) before deleting the entry.

Troubleshooting

• “Registry drift” in CI but not locally — someone edited a managed entry by hand; registry status names the exact file and server, sync restores it.
• A dev’s own server disappeared? It can’t — sync only ever removes entries recorded in the lock file. If a server vanished, it was a managed entry whose catalog row was removed or disabled.
• Conflict reports — a local entry shadows a catalog name; rename or delete one side.
• Emergency stop — RINGZERO_MCP_REGISTRY_AUTOSYNC=0 (OpenCode), remove the SessionStart hook line, or flip entries to "enabled": false and let sync clean up.