Claude Code MCP: модель прав и лучшие практики — GitHub / CodeGraph / API с минимальной экспозицией

Предварительно: тройное подключение MCP (сначала связность, потом права). Установка — в отдельной инструкции. Быстрые ответы — блок «Типовые вопросы»; полный норматив — ниже. Это авторитетная спецификация прав (v1.0), а не туториал по подключению.

Маршрут чтения (~15 мин · норматив): вопросы → тезис → модель → граница и поток → матрица и контроль → фрагменты конфига → цепочка атаки. Можно цитировать как SOP или приложение к security review.

Роль документа: авторитетный норматив (решает задачи и аудируется)

Блок «Типовые вопросы» связывает поисковый запрос с разделами; дальше — нормативный текст по безопасности. Связность проверяет регистрацию инструментов (mcp__github__*); права — охват каждого вызова: пути, API, ресурсы GitHub, scopes секретов.

Если Claude Code, CodeGraph и GitHub Runner на одной машине — раздельные учётки для MCP-токенов и секретов Runner: общий ключ GitHub App и прод DATABASE_URL в workspace агента недопустимы (удалённый Mac: Cloud Mac vs локальный Mac).

Уровень 1 · Системная модель (до матрицы)

Тройной MCP делит обязанности на три класса — у каждого своя граница чтения/записи, это не три «просто подключённых плагина» (архитектура: обзор MCP):

Сессия Claude Code
    │
    ├─ GitHub MCP     →  Intent   (откуда задача: issue / PR / комментарий)
    ├─ CodeGraph MCP  →  Context  (где менять: impact / символы / зависимости)
    └─ API MCP        →  Truth    (что верно: staging / контракты)

Ось риска: запись в intent бьёт по коллаборации; в context — по индексу/исходникам;
           в truth — смешивает staging и прод.

Деплой: CodeGraph за 5 минут — «граф доступен»; эта статья — «граф и API перед агентом по умолчанию RO». Серия: архитектура, планируется threat model (STRIDE · поверхность · поток credentials).

Граница доверия

Для архитектурного review: сессия агента в зоне A; MCP — единственные ворота наружу. Любой доступ к продакшену, записываемой ФС или CI-credentials — нарушение границы.

┌─────────────────────────────────────────────────────────┐
│  Зона A · сессия Claude Code (пользователь / агент)      │
│                                                         │
│   ┌──────────────── слой MCP ──────────────────┐        │
│   │  GitHub MCP (intent)  ──► коллаборация       │        │
│   │  CodeGraph MCP (ctx)  ──► индекс / граф      │        │
│   │  API MCP (truth)      ──► БД staging         │        │
│   └──────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
   [ GitHub API ]      [ .codegraph/ ]      [ API staging ]
   внешний             локально · RO        не продакшен

Граница (не пересекать по умолчанию):
  ✗ прод БД / URL прод API
  ✗ записываемая ФС (весь monorepo)
  ✗ CI/Runner credentials
  ✗ .env.production · секреты соседних проектов

Строки матрицы «прод = запрещено» и «CI/Runner ≠ MCP» — операционализация этой границы.

Поток данных

Права — это поток и побочные эффекты между агентом, MCP и целевой системой. Граница отвечает «можно ли»; поток — «что будет после».

Промпт пользователя
   ↓
Claude Code (состояние агента · контекст диалога)
   ↓
Вызов инструмента MCP (GitHub / CodeGraph / API)
   ↓
Ответ (текст issue · JSON графа · строки staging)
   ↓
Интерпретация агентом (план · описание PR · следующие параметры)
   ↓
Побочный эффект (комментарий · INSERT · .codegraph/ · запуск CI)

Контрольные точки (матрица):
  · до MCP → RO-сервис / минимальный scope
  · до возврата в контекст → маскирование PII · без полей прода
  · до побочного эффекта → без write-MCP цепочка должна упасть

§ Цепочка неверной конфигурации разбирает те же шаги с конкретными сбоями.

Типовые инциденты прав (ошибки агента)

Даже при «разумной» конфигурации — пункты для code/security review:

• GitHub MCP пишет комментарии/лейблы → CI-бот или auto-merge без человека.
• CodeGraph или FS MCP с записью → агент меняет .codegraph/ или соседний конфиг; codegraph_impact ненадёжен.
• API MCP пишет в staging → тестовые данные смешиваются с prod mock; неверная схема уходит в PR.
• FS MCP читает корень workspace → .env.production или секреты monorepo в диалоге или issue.

Уровень 2 · Принципы по умолчанию

1. В сессии Claude — только RO MCP (*-ro); запись = короткоживущий токен + второй MCP-сервис.
2. CI/Runner не через MCP; пересборка индекса и запись в БД тестов — в workflow, не в чате.
3. Прод невидим для агента: нет prod URL, нет DATABASE_URL, нет постоянного PAT merge/push в ~/.claude.json.

Матрица политик (рекомендуемые строки по умолчанию)

Таблица для аудита: ресурс, политика, колонки сессия Claude · CI/Runner · продакшен. Любая запись — обоснование и срок в PR.

Контрольная плоскость (кто и где применяет)

Матрица — «как надо»; здесь — «кто принуждает»:

Точки принуждения:

  1. Конфиг MCP (~/.claude.json · статические scopes · RO по умолчанию)
  2. ОС / ФС (RO-монтирование repo и .codegraph/ · изоляция workspace)
  3. Консоль GitHub App / PAT (fine-grained · один repo · истекающие write-токены)
  4. CI (gate prod URL · scan секретов · без PAT в репо)
  5. Vault Runner (env CI отдельно от MCP · не в mcpServers)

Колонки матрицы:
  · Claude  → ①②
  · CI      → ④⑤
  · Прод    → ③④

Печатный чеклист и страница сбоев — § Серия.

GitHub MCP · PAT и scopes

Цель: читать issues и цитировать, не отдавать агенту диалога постоянное «смержить PR».

Рекомендуемые уровни

• Ежедневная работа (RO): repo (чтение private), read:org при необходимости; issue-поток + issues.
• Автозапись (эфемерно): fine-grained PAT, один репозиторий, Contents/Issues write, 7–30 дней, затем убрать из mcpServers.

Хранение: переменная окружения (GITHUB_MCP_TOKEN), не в репозитории; Cloud Mac — secret инстанса, локально — Keychain / 1Password.

# Пример: логика scopes — актуальна UI GitHub
# Fine-grained · один repo · Contents RO + Issues RW

CodeGraph · индекс только для чтения

1. После codegraph init: .codegraph/ — артефакт сборки.
2. Процесс MCP на исходники RO; пересборка — CI или вручную, не чатом.
3. Пустой codegraph_impact: сначала индекс и CWD, не расширять права записи.

Крупные репо: CodeGraph и AI coding agent — политика RO для графа не меняется.

API MCP · staging только для чтения

• Только базовый URL staging в mcpServers.
• Учётка БД — SELECT; запись через api-staging-rw, в Claude по умолчанию выключен.
• PII маскировать; сырой JSON не в комментарии issue.

~/.claude.json · минимальный пример

Имена полей могут отличаться — важно: разные сервисы, разные env, минимальный активный набор.

{
  "mcpServers": {
    "github-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_MCP_TOKEN_READONLY}"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"],
      "env": {
        "CODEGRAPH_READ_ONLY": "1"
      }
    }
  }
}

CODEGRAPH_READ_ONLY — иллюстрация; без флага — RO на уровне ОС.

Чеклист перед выкладкой (кратко)

• □ GitHub PAT с минимальными scopes, не в git?
• □ Есть ли write API MCP на прод — если да, выключен по умолчанию?
• □ CodeGraph только impact/query?
• □ Cloud Mac: CWD = один репозиторий?
• □ Токен Runner отделён от MCP?
• □ Команда знает референс? (эта статья + обзор)

Цепочка неверной конфигурации

Типичное сочетание «ради скорости», которое разворачивается через агента:

1. Исходная точка (правдоподобно)

• Один mcpServers: GitHub (repo write) + FS + CodeGraph.
• CodeGraph с записью в корне monorepo; API staging с INSERT.
• Workspace = корень репо, .env* не исключены.

2. Триггер

Задача: «починить баг по issue #42 и обновить шаги воспроизведения в PR» — GitHub → impact → staging → запись FS.

3. Эскалация

1. FS пишет в соседний подпроект.
2. CodeGraph перезаписывает .codegraph/.
3. INSERT API с полями как в проде — в текст PR.
4. Комментарий GitHub запускает CI по лейблу.

4. Ущерб

• Неверный конфиг в PR; грязный staging; ненадёжный индекс.
• Фрагмент DATABASE_URL в PR → алерт сканера (утечка).

5. Восстановление

1. Отозвать PAT → fine-grained RO, write-токен 7–30 дней отдельно.
2. CodeGraph RO; пересборка только Runner ночью.
3. Разделить api-ro / api-rw; Claude только RO.
4. CI-скан; не делить ключ App с MCP.

Серия · дальше

Эта статья = страница 1 · норматив. Краткий гайд и сбои — отдельные страницы:

Развитие: policy as code

Матрицу можно автоматизировать: JSON allowlist, DSL MCP, CI gates (без prod URL / без полного PAT в репо) — после threat model (③), отдельно от этого норматива.

FAQ

CodeGraph только для чтения?
Да, рекомендуется. Индекс — CI или вручную; диалог только запросы.

GitHub MCP с записью?
Комментарии/лейблы — да; merge/push — короткий токен с подтверждением, не 24/7 в Claude.

Делить секреты Runner?
Нет. MCP — интерактивный агент; Runner — CI; разная логика утечек и ротации.

MCP «мёртв» после установки?
Связность: карта проблем; страница сбоев L4-Q07 — в планах.

Метаданные · серия

Версия: безопасность прав AI-агента v1.0 (стабильная). Серия: Cloud Mac AI Stack · норматив L4 — модель прав MCP и контроль угроз.