Claude Code MCP 권한 모델: GitHub / CodeGraph / API 최소 노출 가이드

선행: MCP 트리플 연결 개요(연결 후 권한). 설치는 설치 가이드(준비 중). 5분 요약은 아래 「자주 묻는 주제」로, 감사·리뷰용 전문은 본문 전체—MCP 권한 규범 v1.0이며 연결 튜토리얼이 아닙니다.

읽는 순서(약 15분 · 규범 전문): 자주 묻는 주제 → 한 줄 모델 → 시스템 모델 → 신뢰 경계·데이터 흐름 → 정책 표·제어 평면 → 설정 조각 → 공격 체인. 팀 SOP·보안 검토 부록으로 인용 가능합니다.

위치: 감사 가능한 규범

「자주 묻는 주제」가 검색 의도를 절과 연결합니다. 여기서부터 보안 아키텍처 규범입니다. 연결 검증은 mcp__github__* 등록; 권한 검증은 호출 시 도달 범위: 경로, API, GitHub 리소스, 토큰 scope.

Claude Code, CodeGraph, GitHub Runner를 같은 Mac에 둘 때 MCP 토큰과 Runner 비밀은 분리합니다. GitHub App 개인 키 공유, 프로덕션 DATABASE_URL을 Agent 워크스페이스에 두는 것은 금지(원격 Mac은 Cloud Mac vs 로컬 Mac).

1층 · 시스템 모델

트리플 MCP는 역할별로 세 층이며, 각각 읽기·쓰기 위험 경계가 다릅니다(MCP 개요):

Claude Code 세션
    │
    ├─ GitHub MCP     →  intent   (요구: issue / PR / 댓글)
    ├─ CodeGraph MCP  →  context  (변경 위치: impact / 심볼)
    └─ API MCP        →  truth    (검증: 스테이징 데이터 / 계약)

위험: intent 오쓰기는 협업면, context는 인덱스 오염, truth는 프로덕션·스테이징 혼동.

배포: CodeGraph 5분은 「그래프 사용 가능」; 본문은 「Agent 앞에서 그래프·API 기본 읽기 전용」. ① 아키텍처, ③ 예정 위협 모델.

신뢰 경계

┌─────────────────────────────────────────────────────────┐
│  영역 A · Claude Code(사용자 / Agent)                     │
│   ┌──────────── MCP 계층 ────────────┐                   │
│   │ GitHub(intent) → 협업 시스템        │                   │
│   │ CodeGraph(context) → 로컬 인덱스    │                   │
│   │ API(truth) → 스테이징 DB            │                   │
│   └──────────────────────────────────┘                   │
└─────────────────────────────────────────────────────────┘

기본 금지:
  ✗ 프로덕션 DB / API URL
  ✗ 저장소 전체에 쓰기 가능한 MCP
  ✗ Runner·CI 토큰을 mcpServers에
  ✗ .env.production · 인접 프로젝트 비밀

데이터 흐름

프롬프트 → Claude Code → MCP 호출 → 외부 응답 → Agent 해석 → 부작용

제어점: 호출 전 RO·최소 scope / 응답 전 PII 마스킹 / 부작용 전 쓰기 서비스 비활성 시 실패

흔한 권한 사고

• GitHub MCP로 댓글·라벨 변경 → 댓글 연동 bot·자동 머지가 사람 확인 없이 pipeline 진행.
• CodeGraph·FS MCP가 repo에 쓰기 → .codegraph/ 오염, codegraph_impact 불신.
• API MCP가 스테이징에 쓰기 → 프로덕션 mock과 동명 필드가 PR에 섞임.
• 워크스페이스 루트 전체 읽기 → .env.production·monorepo 인접 비밀 유출.

2층 · 기본 정책

1. 세션에는 읽기 전용 MCP만(*-ro); 쓰기는 단기 토큰 + 별도 서비스.
2. CI·Runner는 MCP로 노출하지 않음.
3. 프로덕션은 Agent에 보이지 않음.

정책 표(권장 기본)

제어 평면

강제 지점:
  1. ~/.claude.json
  2. OS·FS(RO 마운트)
  3. GitHub PAT/App
  4. CI(프로덕션 URL 게이트)
  5. Runner 금고(MCP env 분리)

GitHub MCP · PAT

• 일상: repo(private 읽기), issues.
• 자동화 쓰기: 단일 repo fine-grained PAT, 7–30일 만료.

저장은 환경 변수 우선. Cloud Mac은 인스턴스 secret, 로컬은 Keychain.

CodeGraph · 읽기 전용

1. .codegraph/는 빌드 산출물 취급.
2. MCP는 소스 읽기 전용; 재인덱스는 CI·수동.
3. codegraph_impact가 비면 권한보다 인덱스·cwd를 먼저 확인.

CodeGraph와 AI Coding Agent 참고. 정책은 동일—그래프 RO.

API MCP · 스테이징 읽기

• 베이스 URL은 스테이징만.
• DB는 SELECT; 쓰기는 api-staging-rw 등 별도 이름, Claude에서는 기본 off.
• PII는 MCP에서 마스킹.

~/.claude.json 최소 예

{
  "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" }
    }
  }
}

배포 전 체크(요약)

• □ PAT 최소 scope·git 미포함
• □ 프로덕션 쓰기 API MCP 없음/기본 off
• □ CodeGraph는 impact/query만
• □ Cloud Mac cwd 단일 repo
• □ Runner·MCP 토큰 분리

오설정 공격 체인

효율을 위해 그럴듯한 설정이 Agent 연쇄 호출 후 권한을 넘습니다.

1. PAT 재발급(RO + 기한 있는 쓰기).
2. CodeGraph RO; 재인덱스는 Runner만.
3. api-ro / api-rw 분리.

시리즈 관련 글

Policy as Code

표의 행을 JSON 허용 목록·CI 게이트로 옮기는 단계입니다. 위협 모델 확정 후 실행 매뉴얼을 분리합니다.

FAQ

CodeGraph 읽기 전용?
권장. 인덱스는 CI·수동만.

GitHub 쓰기?
댓글 정도는 가능. merge/push는 단기 토큰+사람 확인.

Runner 비밀 공유?
불가.

MCP 안 됨?
문제 대조표.

문서 정보

버전: AI Agent 권한 규범 v1.0. 시리즈: Cloud Mac AI Stack · L4.