mcp-registry-template.yaml

# MCP Registry Template
# Copy to: .claude/mcp-registry.yaml in your shared config repo
#
# Purpose: Track approved MCP servers, their scope, and review status.
# This is the org-level source of truth for permitted MCP usage.
#
# Related: guide/security/enterprise-governance.md §3.2

metadata:
  organization: "[Your Organization Name]"
  review_cycle: quarterly
  last_reviewed: "YYYY-MM-DD"
  next_review: "YYYY-MM-DD"
  owner: "platform-team@company.com"
  policy_doc: "https://your-wiki/ai-usage-charter"

# ─────────────────────────────────────────────────────────────────
# APPROVED MCPs
# ─────────────────────────────────────────────────────────────────
approved:

  # Example: Read-only documentation lookup (LOW risk)
  - name: context7
    version: "1.2.3"                # Pin exact version — never "latest"
    source: "https://github.com/context7/mcp-server"
    npm_package: "@context7/mcp-server"
    approved_by: "john.doe@company.com"
    approved_date: "2026-01-15"
    expires: "2026-07-15"           # 6 months default
    data_scope: PUBLIC              # PUBLIC | INTERNAL | CONFIDENTIAL | RESTRICTED
    risk: LOW                       # LOW | MEDIUM | HIGH
    rationale: "Read-only documentation lookup. No data egress, no credentials."
    config:
      command: npx
      args: ["-y", "@context7/mcp-server@1.2.3"]
      env: {}

  # Example: Local reasoning (LOW risk)
  - name: sequential-thinking
    version: "0.6.2"
    source: "https://github.com/modelcontextprotocol/servers"
    npm_package: "@modelcontextprotocol/server-sequential-thinking"
    approved_by: "jane.smith@company.com"
    approved_date: "2026-01-15"
    expires: "2026-07-15"
    data_scope: INTERNAL
    risk: LOW
    rationale: "Local reasoning only. No network access, no file I/O beyond scratch."
    config:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-sequential-thinking@0.6.2"]
      env: {}

  # Example: Read-only internal database (MEDIUM risk, shorter expiry)
  - name: internal-db-readonly
    version: "2.1.0"
    source: "internal"              # "internal" for company-built MCPs
    approved_by: "security@company.com"
    approved_date: "2026-02-01"
    expires: "2026-05-01"           # Shorter expiry for higher risk
    data_scope: CONFIDENTIAL
    risk: MEDIUM
    rationale: "Read-only replica. Allowlisted tables exclude PII, payments, audit."
    restrictions:
      - "Read-only database user only (no INSERT/UPDATE/DELETE)"
      - "No access to: users, payments, audit_log, sessions tables"
      - "Only connect to readonly replica, never primary"
    config:
      command: npx
      args: ["-y", "@company/db-mcp@2.1.0"]
      env:
        DB_HOST: "readonly-replica.internal"
        DB_USER: "claude_readonly"
        # DB_PASS: loaded from secrets manager at runtime

# ─────────────────────────────────────────────────────────────────
# PENDING REVIEW
# ─────────────────────────────────────────────────────────────────
pending_review:

  - name: github-mcp
    requested_by: "dev@company.com"
    requested_date: "2026-03-05"
    source: "https://github.com/modelcontextprotocol/servers"
    use_case: "Automated PR creation, issue management"
    proposed_data_scope: INTERNAL
    status: under_review            # under_review | sandbox_trial | awaiting_security
    reviewer: "jane.smith@company.com"
    expected_decision: "2026-03-20"
    notes: "Check GitHub token scope — should be limited to specific repos"

# ─────────────────────────────────────────────────────────────────
# DENIED
# ─────────────────────────────────────────────────────────────────
denied:

  - name: browser-automation-mcp
    denied_date: "2026-02-10"
    requested_by: "dev2@company.com"
    reason: >
      Full browser automation with no scope restriction. Can navigate to arbitrary URLs,
      exfiltrate data via screenshots, and access internal sites via authenticated sessions.
      Risk too high without a sandboxed browser environment.
    alternative: "Use Playwright MCP with restricted URL allowlist if browser access required."

  - name: filesystem-mcp-unrestricted
    denied_date: "2026-01-20"
    requested_by: "dev3@company.com"
    reason: >
      Unrestricted filesystem access. CVE-2025-53109/53110 not patched in requested version.
      Would allow sandbox escape via prefix bypass + symlinks.
    alternative: "Use Claude Code's built-in Read/Write/Edit tools with permissions.deny rules."

# ─────────────────────────────────────────────────────────────────
# VERSION BUMP POLICY
# ─────────────────────────────────────────────────────────────────
version_bump_policy:
  patch:                            # e.g., 1.2.3 → 1.2.4
    requires: check_release_notes   # Check for CVEs/breaking changes, then auto-approve
    approver: tech_lead
    turnaround: "48h"
  minor:                            # e.g., 1.2.3 → 1.3.0
    requires: full_security_review
    approver: security_team
    turnaround: "1 week"
  major:                            # e.g., 1.2.3 → 2.0.0
    requires: full_security_review + sandbox_trial
    approver: security_team + engineering_director
    turnaround: "2 weeks"

# ─────────────────────────────────────────────────────────────────
# SECURITY INCIDENT CONTACTS
# ─────────────────────────────────────────────────────────────────
incident_response:
  report_to: "security@company.com"
  slack: "#security-incidents"
  response_time_sla: "4 hours business hours"
  escalation: "engineering-director@company.com"