Claude Code에서 MCP vs Skills vs CLI - 무엇을 선택해야 할까?

들어가며

Claude Code에서 GitHub와 연동하려고 할 때, 선택지가 여러 개다:

• GitHub MCP 서버
• Skills (SKILL.md)
• gh CLI + CLAUDE.md

처음엔 당연히 MCP가 "올바른" 방법이라 생각했다. 공식적이고, 구조화되어 있고, 뭔가 있어 보이니까. 하지만 실제로 팀 프로젝트에 적용하려다 보니 예상치 못한 문제를 만났다.

문제의 시작: 팀 프로젝트에서 토큰 공유

프로젝트 레벨의 MCP 설정(.mcp.json)을 git으로 공유하려 했다. 그런데 GitHub MCP는 인증 토큰이 필요하다.

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx..."  // 이걸 커밋한다고?
    }
  }
}

개인 토큰을 git에 커밋할 수는 없다. ${GITHUB_PAT} 같은 환경 변수 interpolation을 시도해봤지만, stdio 타입의 env 섹션에서만 제한적으로 지원되고 HTTP headers에서는 동작하지 않았다.

GitHub Issue에서도 같은 고민을 하는 개발자들이 많았다:

"I am preparing a shared .mcp.json file that I want to commit to our repository, but facing an issue in how to authenticate..."

Anthropic은 뭐라고 할까?

놀랍게도 Anthropic 공식 best practices 문서에서는 이렇게 말한다:

"Claude knows how to use the gh CLI to interact with GitHub for creating issues, opening pull requests, reading comments, and more."

심지어 공식 슬래시 커맨드 예제에서도:

Remember to use the GitHub CLI ('gh') for all GitHub-related tasks.

MCP 대신 gh CLI를 쓰라고 가이드하고 있다.

MCP의 숨겨진 비용: 컨텍스트 윈도우

MCP를 깊이 살펴보니 더 근본적인 문제가 있었다. MCP는 모든 tool definitions을 미리 로드한다.

/context 명령어로 확인해보면:

System prompt: xxxxx tokens
MCP tools: 8,000+ tokens  ← GitHub MCP 하나만으로
Messages: xxxxx tokens
Free space: ...

Armin Ronacher(Flask 창시자)도 비슷한 경험을 공유했다:

"The Sentry MCP is probably one of the better designed MCPs out there, but I don't use it anymore. When I load it into the context right away I lose around 8k tokens out of the box."

8,000 토큰이면 꽤 긴 대화를 할 수 있는 양이다. MCP 서버 하나 연결했다고 그만큼 날리는 건 비효율적이다.

Skills: 더 똑똑한 대안

Skills는 완전히 다른 접근을 한다. Progressive Disclosure - 필요할 때만 로드한다.

세션 시작 시:
- Skill 이름과 설명만 로드 (~수십 토큰)
- 전체 instructions는 아직 로드 안 함

관련 작업 요청 시:
- 그제서야 full SKILL.md 로드
- 스크립트 실행 결과만 컨텍스트에 추가 (스크립트 코드 자체는 0 토큰)

이걸 "매트릭스 방식"이라고 부르는 사람도 있다:

"Skills load on-demand, just like Neo in The Matrix (1999). 'I know Kung Fu'"

Skills vs MCP: 핵심 차이

관점MCPSkills

로딩 방식	Upfront (미리 전부)	On-demand (필요할 때)
컨텍스트 비용	도구당 100~300 토큰 (항상)	설명만 수십 토큰 (평소)
역할	Connectivity (연결)	Expertise (전문성)
유지보수	서버 관리 필요	마크다운 편집
범용성	MCP 클라이언트 필요	파일시스템 접근만 있으면 됨

Simon Willison은 이렇게 평가했다:

"Skills are (maybe) a bigger deal than MCP."

언제 뭘 써야 할까?

Anthropic의 공식 가이드를 보면 명확하다:

• MCP: Claude가 접근할 수 없는 외부 시스템 연결 (데이터베이스, 사내 API 등)
• Skills: Claude가 그 연결을 어떻게 활용할지 가르치기

"MCP handles connectivity. Skills handle expertise."

즉, MCP는 "문을 열어주는 것"이고, Skills는 "문 안에서 뭘 할지 가르치는 것"이다.

그런데 gh CLI는? 이미 설치되어 있고, Claude가 잘 알고 있다. 새로운 "문"을 열 필요가 없다.

실용적인 결론: GitHub 연동은 CLAUDE.md로

GitHub처럼 잘 알려진 도구는 굳이 MCP를 쓸 필요가 없다:

# CLAUDE.md

## GitHub 사용

이 프로젝트는 gh CLI를 사용합니다.
각 개발자는 `gh auth login` 완료 상태여야 합니다.

### PR 워크플로우
- PR 생성: `gh pr create --title "..." --body "..."`
- PR 리뷰 요청: `gh pr edit --add-reviewer @username`
- PR 머지: `gh pr merge --squash`

### 브랜치 컨벤션
- feature/xxx, fix/xxx, refactor/xxx 형태로 생성
- main 브랜치 직접 push 금지

### 커밋 메시지
- feat: 새로운 기능
- fix: 버그 수정
- refactor: 리팩토링

이 방식의 장점:

1. 토큰 공유 문제 없음 - 각자 gh auth login만 하면 됨
2. 컨텍스트 효율적 - 필요할 때 참조
3. 프로젝트 컨벤션 포함 - 단순 도구 연결 이상의 가치
4. git으로 바로 공유 - 추가 설정 불필요
5. 커스터마이징 자유로움 - 팀 워크플로우에 맞게 조정 가능

그래서 MCP는 언제 쓰나?

MCP가 빛을 발하는 경우:

• 사내 전용 시스템 - Claude가 전혀 모르는 API
• 데이터베이스 직접 연결 - PostgreSQL, MongoDB 등
• SaaS 통합 - Notion, Slack, Jira 등의 실시간 데이터
• 파일시스템 없는 환경 - Claude.ai 웹에서 외부 연결 필요 시

반면 이런 경우는 MCP 대신 다른 방법을:

• gh, git, docker 같은 표준 CLI → CLAUDE.md
• 복잡한 워크플로우 가이드 → Skills
• 자주 안 쓰는 도구 → Skills (on-demand 로딩)

마치며

처음엔 "MCP가 더 있어 보이니까"라는 이유로 선택하려 했다. 하지만 실제로 부딪혀보니:

1. 팀 프로젝트에서 토큰 공유 문제
2. 컨텍스트 윈도우를 상시 점유하는 비효율
3. Anthropic조차 gh CLI를 권장하는 현실

결국 도구 선택은 "있어 보이는 것"이 아니라 "실제로 효율적인 것"을 기준으로 해야 한다.

• 새로운 외부 시스템 연결? → MCP
• 복잡한 도메인 전문성? → Skills
• 잘 알려진 CLI 도구? → CLAUDE.md

세 가지는 경쟁 관계가 아니라 상호 보완 관계다. 상황에 맞게 조합해서 쓰면 된다.