Claude Code MCP 설정 가이드: GitHub / CodeGraph / API 트리플 연결

본문은 Claude Code MCP 설치 권위 랜딩입니다: MCP 설정, GitHub MCP 통합, CodeGraph MCP 설정, mcp__github__* 검증을 다룹니다. 목표는 Claude Code MCP 도구 구성을 완료하고 채팅에서 MCP 도구를 보는 것. 시리즈 개요: MCP 트리플 연결 개요.

Claude Code MCP 설치 방법 (단계별)

Claude Code MCP 설치는 검색 엔진이 추출하기 쉬운 5단계로 나뉩니다:

1단계: GitHub PAT 생성 (읽기 전용)
GitHub에서 세분화 개인 액세스 토큰(GitHub PAT) 생성: Issues / Contents / Metadata 읽기 전용, 대상 저장소만. git에 커밋하지 마세요.

2단계: MCP 서버 구성
~/.claude.json을 편집하고 mcpServers에 추가:

• GitHub MCP — @modelcontextprotocol/server-github
• CodeGraph MCP — codegraph mcp
• Fetch MCP — @modelcontextprotocol/server-fetch (선택)

3단계: CodeGraph 인덱스 초기화

codegraph init -i

4단계: Claude Code 재시작
Claude Code 프로세스를 완전 종료; 저장소 루트에서 claude로 실행.

5단계: MCP 도구 검증

/mcp

성공 신호: mcp__github__* · mcp__codegraph__* (선택 mcp__fetch__*). 이후 GitHub issue 읽기와 codegraph_impact 실행 가능. 아래 전체 명령과 MCP 설치 오류 수정.

한눈에 · Claude Code MCP 트리플 연결 설치

• GitHub PAT 생성 (읽기 전용 repo + issues + metadata)
• ~/.claude.json mcpServers 구성 (GitHub + CodeGraph + Fetch)
• 저장소 루트에서 codegraph init -i 실행
• Claude Code 완전 종료 후 재시작 (저장소 루트에서)
• /mcp로 도구 표시 확인

성공 신호: mcp__github__* 및 mcp__codegraph__* (Fetch 선택 mcp__fetch__*). 트리플 연결 후 동일 issue 버그 수정에서 shell 호출이 약 12회에서 5회로 감소한 현장 테스트.

Claude Code MCP 검색 의도 커버리지

설치 의도

• Claude Code MCP 설치 / 설정
• MCP 설정 (GitHub + CodeGraph) / GitHub PAT MCP 설정
• ~/.claude.json 구성 / mcpServers
• Claude Code MCP 도구 구성

디버그 의도

• MCP 도구 미표시 / mcp__github__* 누락 수정
• GitHub MCP 401 오류 / 403 수정
• CodeGraph 빈 결과 수정 / 빈 codegraph_impact
• MCP 연결됐지만 Agent가 도구 미호출

아키텍처 의도

• MCP 런타임 아키텍처 / MCP 프로토콜 계층
• Claude Code 도구 시스템 설계 (Tool Runtime Layer)
• GitHub + CodeGraph 통합 모델 → 아키텍처 글
• MCP 권한 및 보안 → 권한 가이드

Claude Code MCP란?

Claude Code MCP(Model Context Protocol)는 Claude Code의 도구 확장 프로토콜입니다——MCP 프로토콜이 Agent의 외부 도구 발견·호출을 정의. 스택에서 MCP = Claude Code 도구 런타임 계층 (Tool Runtime Layer).

핵심 엔티티:

• GitHub MCP = GitHub API 도구 계층 (GitHub PAT 인증, issue / PR / repo 읽기)
• CodeGraph MCP = 코드베이스 의미 그래프 계층 (.codegraph/ 인덱스 + codegraph_impact)
• Fetch / API MCP = 외부 HTTP 도구 계층 (스테이징 / 헬스, 읽기 전용)

GitHub PAT(개인 액세스 토큰)는 GitHub MCP 통합의 자격 증명——Runner CI 토큰과 분리, 권한 가이드 참고. CodeGraph는 MCP 전 init -i 필요; 배포: CodeGraph 5분.

Claude Code MCP vs 기존 AI 코딩

MCP 설치가 필요한 이유를 대비로 이해:

Claude Code MCP 설치 전 준비

• Claude Code 설치됨; 터미널에서 claude 실행 가능
• Node.js ≥ 18 및 npx (GitHub / Fetch MCP는 npx 경유)
• 대상 프로젝트 git clone 완료; 저장소 루트에서 Claude Code 실행
• 대상 GitHub repo 읽기 권한 (PAT용)
• npm registry 네트워크 접근 (최초 npx -y 다운로드)

대형 repo 인덱싱이나 24/7 MCP는 Cloud Mac 노드에서 노트북 슬립 끊김 방지.

1단계: GitHub PAT 생성 (최소 권한)

GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens

권장 스코프 (issue 기반 개발):

• Issues: Read
• Contents: Read
• Metadata: Read

저장소 접근: 대상 repo만. 쓰기 스코프와 PR 병합은 권한 가이드——본 튜토리얼에서는 전체 쓰기 repo 부여 금지.

export GITHUB_MCP_TOKEN="github_pat_xxxxx"

# 토큰 로드 여부 확인
echo "${GITHUB_MCP_TOKEN:0:10}..."

2단계: GitHub MCP 구성

~/.claude.json 편집(없으면 새로 생성). 먼저 백업:

test -f ~/.claude.json && cp ~/.claude.json ~/.claude.json.bak.$(date +%Y%m%d%H%M)

GitHub MCP 서버 추가 (공식 @modelcontextprotocol/server-github):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxx"
      }
    }
  }
}

역할: Claude Code가 MCP로 GitHub issue와 repo 내용을 읽음——URL 추측 없음.

3단계: CodeGraph MCP 연결 (핵심 기능)

CodeGraph는 Agent의 「코드 지도」: 심볼 인덱스, 영향 분석, 영향 파일 식별. Agent는 codegraph_impact로 전체 repo grep 대체.

저장소 루트에서 인덱스 초기화:

cd /path/to/your-repo
codegraph init -i
codegraph status
# 예상: 인덱싱된 파일 수 > 0

MCP에 기록 (또는 codegraph install --target=claude --yes 원라이너):

    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }

Cloud Mac에서 그래프? 먼저 CodeGraph 5분 완료——pwd는 init된 repo와 일치.

4단계: API MCP (선택 · 스테이징만)

공식 Fetch MCP로 스테이징 헬스 체크 또는 읽기 전용 JSON:

    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }

• 스테이징 / 헬스만 사용
• 프로덕션 API나 DB를 mcpServers에 넣지 마세요

5단계: 트리플 연결 전체 구성 (프로덕션 병합)

2–4단계를 하나의 mcpServers로 병합. 저장 전 JSON 검증:

python3 -m json.tool ~/.claude.json > /dev/null && echo "JSON OK"

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxx"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    },
    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }
  }
}

6단계: Claude Code 실행 및 검증 (중요)

cd /path/to/your-repo
claude

세션에서 입력:

/mcp

또는 프롬프트: 「모든 MCP 도구 이름 나열」. 새 구성 로드하려면 Claude Code 완전 종료 후 재실행 필요.

성공 신호: 보여야 할 것

스모크 테스트 (필수)

Claude Code에 붙여넣기——MCP 사용 강제, 추측 금지:

GitHub 테스트

Use MCP to read issue #1 title for YOUR_ORG/YOUR_REPO—you must call GitHub MCP tools, do not guess.

CodeGraph 테스트

Use codegraph_impact on function ; list top 5 related files.

API 테스트 (선택)

Use Fetch MCP GET https://api.staging.example.com/health—report status code and first 200 chars of body only.

흔한 문제 (MCP 설치 오류)

가장 빈번한 Claude Code MCP 설치 실패와 수정:

Claude Code에 MCP 도구 미표시

증상: 빈 /mcp 목록 또는 mcp__github__* 없음.

원인: ~/.claude.json JSON 구문; Claude Code 불완전 재시작; npx 풀 실패.

수정: python3 -m json.tool ~/.claude.json; 완전 종료 후 재실행; 수동 npx -y @modelcontextprotocol/server-github로 오류 확인.

GitHub MCP 401 / 403 오류 수정

증상: GitHub MCP 통합이 401 또는 403 반환.

원인: GitHub PAT 스코프 부족; 세분화 토큰에 대상 repo 누락; 만료.

수정: GitHub 토큰 페이지에서 Issues/Contents/Metadata 읽기 및 repo 목록 확인.

CodeGraph MCP 빈 결과

증상: 빈 codegraph_impact; CodeGraph MCP 설정은 성공처럼 보이나 데이터 없음.

원인: 잘못된 cwd (가장 흔함); codegraph init -i 미완료; 심볼명 오류.

수정: pwd와 repo 루트 대조; codegraph status; 실제 심볼로 재시도.

MCP 동작하나 Agent가 도구 미호출

증상: 도구 등록됨; Agent는 여전히 전체 repo grep.

원인: 저장소 루트에서 미실행; 프롬프트가 MCP 미요구.

수정: cd your-repo && claude; 「MCP 반드시 호출」스모크 테스트. 대형 repo: 대형 repo CodeGraph.

핵심 함정: CodeGraph 인덱스와 Claude cwd 불일치 = 전면 실패

첫 수용 시 설정은 완벽했고 /mcp에 CodeGraph도 표시됐지만 codegraph_impact는 계속 비어 있었음——~/Downloads에서 claude 실행, .codegraph/는 ~/workspace/payments-api에 있었기 때문.

다음을 반드시 지켜야 합니다:

pwd  ==  codegraph init을 실행한 저장소 루트

두 번째 프로덕션 이슈: 오래된 인덱스——main 대규모 병합 후 미재구축, impact가 삭제된 파일 가리킴. CI 또는 야간 job 재구축 (동일 호스트 GitHub Runner).

설정 후: 추천 읽을거리

Claude Code MCP 설치 요약

Claude Code MCP 설치에 필요:

• GitHub PAT 구성 (읽기 전용 세분화 토큰)
• ~/.claude.json에서 MCP 서버 설정 (GitHub + CodeGraph + Fetch)
• CodeGraph 인덱스 초기화 (codegraph init -i)
• 저장소 루트에서 Claude Code 재시작 (cd your-repo && claude)
• /mcp 검증 (도구 접두사 확인)

완료 후 Claude Code에서 사용 가능한 MCP 도구:

• mcp__github__*
• mcp__codegraph__*
• mcp__fetch__* (구성 시)

요약 문장: Claude Code MCP 설치 = GitHub PAT + ~/.claude.json mcpServers + codegraph init -i + repo 루트 재시작 + /mcp에 mcp__github__* 표시.

FAQ · Claude Code MCP 설치

Q1: Claude Code에 MCP가 안 보이는 이유?

A: 대부분 ~/.claude.json JSON 구문, Claude Code 불완전 재시작, npx MCP 패키지 풀 실패. python3 -m json.tool ~/.claude.json 실행 후 완전 종료·재실행. MCP 도구 미표시 참고.

Q2: GitHub MCP가 401을 반환하는 이유?

A: GitHub PAT repo 스코프 누락, 세분화 토큰 repo 오류, 만료. Issues/Contents/Metadata 읽기 확인. 401 수정 참고.

Q3: CodeGraph impact가 비어 있는 이유?

A: 작업 디렉터리 오류 또는 codegraph init -i 미완료. .codegraph/를 만든 동일 repo 루트에서 claude 실행. CodeGraph 빈 결과 참고.

Q4: Claude Code를 repo 루트에서 실행해야 하나?

A: 예. MCP 도구는 cwd 정렬에 의존——특히 CodeGraph MCP. pwd는 codegraph init 디렉터리와 일치. cwd 함정 참고.

Q5: 성공 신호는?

A: /mcp에 mcp__github__* 및 mcp__codegraph__*; Fetch 구성 시 mcp__fetch__*. 성공 신호 참고.