오늘만 무료

MCP 인증 완전 가이드

GitHub PAT·OAuth 설정과 API 키 안전 관리

by AI개발자

8시간전 brunch_membership's

MCP 서버로의 인증 설정을 이해하고, API 키와 OAuth 양쪽 방식으로 안전하게 접속할 수 있게 됩니다. 인증 정보 관리의 베스트 프랙티스를 습득합니다.

배경 지식

왜 인증이 필요한가

MCP 서버가 외부 서비스(GitHub, 데이터베이스, 클라우드 API 등)와 연계하는 경우, 액세스 권한의 확인이 필요해집니다. 인증 없이는 다음과 같은 리스크가 있습니다.

불법 액세스에 의한 데이터 유출

의도하지 않은 조작의 실행

API 이용 제한의 관리 불가

� 한국 개발 환경에서의 인증 리스크
GitHub PAT 유출은 소스 코드 유출·CI/CD 파이프라인 탈취로 이어질 수 있습니다. 특히 GitHub Actions와 연동하는 PAT나 AWS 액세스 키는 즉각적인 피해로 이어지므로, 스코프와 관리 방법에 각별한 주의가 필요합니다.

인증 방식의 종류

MCP에서는 서버마다 적절한 인증 방식을 설정합니다.

API 키 인증

API 키(Personal Access Token 포함)는 서비스가 발행하는 문자열을 요청에 포함하여 송신하는 방식입니다.

심플하지만, 키의 유출 리스크를 관리할 필요가 있습니다.

OAuth 인증

OAuth는 사용자를 대신하여 애플리케이션이 리소스에 액세스하기 위한 인가 프레임워크입니다. 토큰의 자동 갱신이나 스코프의 세밀한 제어가 가능합니다.

Claude Code에서는 OAuth 계열 연계가 가능하며, 대응하는 MCP 서버가 OAuth 인증 플로우를 처리합니다.

따라하기

1단계: 인증 불필요 MCP 서버를 확인한다

먼저, 인증이 불필요한 filesystem MCP 서버가 정상적으로 동작하고 있는지 확인합니다.

cd ~/mcp-workspace
claude mcp get filesystem

filesystem MCP 서버는 로컬 파일에 액세스하기만 하므로 외부 서비스로의 인증은 불필요합니다. 이것이 가장 심플한 케이스입니다.

2단계: GitHub Personal Access Token(PAT) 작성

GitHub MCP 서버의 인증에는 Personal Access Token(PAT)을 사용합니다.

방법 A: GitHub 웹사이트에서 작성 (Classic 토큰)

1. GitHub에 로그인

2. Settings > Developer settings > Personal access tokens > Tokens (classic)

3. "Generate new token (classic)"을 클릭

4. 다음 스코프를 선택:

repo (리포지토리로의 풀 액세스)

read:org (조직 정보의 읽기)

5. 토큰을 생성하고, 안전한 장소에 복사

방법 B: Fine-grained tokens (권장 - 최소 권한 원칙)

1. Settings > Developer settings > Personal access tokens > Fine-grained tokens

2. "Generate new token"을 클릭

3. 접근을 허용하는 리포지토리를 지정 (전체 대신 특정 리포지토리만)

4. 필요한 권한만 선택 (Contents: Read, Metadata: Read 등)

� Fine-grained tokens를 권장하는 이유
Classic 토큰은 스코프 범위가 넓어 한 번 유출되면 피해가 큽니다. Fine-grained tokens는 특정 리포지토리·특정 권한만 허용할 수 있어 최소 권한 원칙을 준수할 수 있습니다.

방법 C: GitHub CLI를 사용

# GitHub CLI로 인증 완료된 경우, 현재 토큰을 확인할 수 있다
gh auth token

3단계: 환경 변수로 인증 정보를 전달한다

MCP 서버에 API 키를 전달하려면 환경 변수를 사용합니다. 방법은 주로 3가지이며, 각각 편의성과 보안의 균형이 다릅니다. 어떤 방법이든 인증 정보를 포함하는 파일은 .gitignore에 추가하여 Git에 커밋하지 않도록 해주세요.

주의: 3장에서 이미 github라는 이름으로 MCP 서버를 등록한 경우는, 먼저 claude mcp remove github로 삭제하고 나서 실행하세요.

방법 A: export 커맨드로 직접 전달 (가장 심플)

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
claude mcp add --transport stdio --scope project github -- npx -y @modelcontextprotocol/server-github

export로 설정한 환경 변수는 같은 셸 세션 내에서 claude를 기동한 경우에만 MCP 서버의 프로세스에 인계됩니다. 터미널을 닫으면 사라지므로 매번 직접 입력이 필요합니다. 또한 셸의 이력에 토큰이 남을 가능성이 있습니다.

방법 B: JSON 설정 파일의 env 필드에 쓴다

cat > ~/mcp-workspace/config/mcp-auth.json << 'EOF'
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
EOF

# 인증 정보를 포함하므로 .gitignore에 반드시 추가
echo "config/mcp-auth.json" >> ~/mcp-workspace/.gitignore

셸 이력에 토큰이 남지 않는 점에서는 방법 A보다 개선되지만, 파일에 토큰이 평문으로 저장됩니다.

방법 C: .env 파일 + 기동 스크립트 (자동화)

방법 A의 "매번 직접 입력"을 자동화하는 방법입니다. 토큰을 .env 파일에 보존하고, 기동 스크립트가 자동으로 읽어 들인 후 Claude Code를 기동합니다.

# .env 파일을 작성
cat > ~/mcp-workspace/.env << 'EOF'
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
EOF

# .gitignore에 추가
echo ".env" >> ~/mcp-workspace/.gitignore

# 기동 스크립트를 작성
cat > ~/mcp-workspace/start-claude.sh << 'SCRIPT'
#!/bin/bash
# .env 파일에서 환경 변수를 읽어 들인다
set -a
source "$(dirname "$0")/.env"
set +a

# MCP 설정으로 기동
claude --mcp-config "$(dirname "$0")/config/mcp-auth.json"
SCRIPT

# 스크립트에 실행 권한 부여
chmod +x ~/mcp-workspace/start-claude.sh

이후부터는 ~/mcp-workspace/start-claude.sh를 실행하는 것만으로 토큰의 설정과 Claude Code의 기동이 함께 이루어집니다.

3가지 방법의 비교:

어느 방법이든 토큰이 평문으로 다루어지므로 완전한 안전성은 보장되지 않습니다. 더 높은 보안이 필요한 경우는 OS의 키체인(macOS Keychain, Linux의 secret-tool 등)을 활용하는 방법이 있습니다(8장에서 소개).

4단계: GitHub MCP 서버의 동작 확인

인증 설정이 완료되면, 대화 모드에서 동작을 확인합니다.

cd ~/mcp-workspace
claude --mcp-config ~/mcp-workspace/config/mcp-auth.json

방법 C(.env + 기동 스크립트)를 선택한 경우는 다음 커맨드로 기동합니다.

cd ~/mcp-workspace
./start-claude.sh

대화 모드 내에서 다음을 시험합니다.

> /mcp

GitHub MCP 서버가 접속 완료(connected)가 되어 있는지 확인합니다.

> 내 GitHub 리포지토리 목록을 표시해주세요

인증이 올바르게 설정되어 있다면 리포지토리 목록이 표시됩니다.

> 최근 오픈한 Pull Request 목록을 표시해주세요

� GitHub MCP 서버로 할 수 있는 것들
리포지토리 목록 조회 외에도 Issue 생성, PR 리뷰, 브랜치 조작 등이 가능합니다. 1장에서 배운 Skill과 조합하면 "PR 리뷰 Skill + GitHub MCP"로 실제 PR 내용을 자동으로 분석하는 워크플로우를 구축할 수 있습니다.

5단계: 인증 에러의 트러블슈팅

자주 있는 에러 1: 토큰이 유효하지 않다

Error: Bad credentials

대처: 토큰이 올바르게 복사되어 있는지, 유효 기간이 만료되지 않았는지 확인합니다.

# 토큰 검증 (GitHub API를 직접 호출)
curl -H "Authorization: token ghp_xxxxxxxxxxxxxxxxxxxx" https://api.github.com/user

정상적이면 사용자 정보 JSON이 반환됩니다. {"message":"Bad credentials",...}가 반환되면 토큰이 무효입니다.

자주 있는 에러 2: 스코프 부족

Error: Resource not accessible by personal access token

대처: 토큰에 필요한 스코프(repo, read:org 등)가 부여되어 있는지 확인합니다.

# 토큰에 부여된 스코프를 확인 (X-OAuth-Scopes 헤더)
curl -sI -H "Authorization: token ghp_xxxxxxxxxxxxxxxxxxxx" https://api.github.com/user | grep x-oauth-scopes

자주 있는 에러 3: 환경 변수가 전달되지 않았다

Error: GITHUB_PERSONAL_ACCESS_TOKEN is not set

대처: JSON 설정 파일의 env 필드를 확인하거나, 셸의 환경 변수를 확인합니다.

echo $GITHUB_PERSONAL_ACCESS_TOKEN

에러 트러블슈팅 플로우차트:

인증 에러 발생

│

├── "Bad credentials" → 토큰 유효성 확인 (curl로 API 직접 호출)

│

├── "not accessible" → 토큰 스코프 확인

│

├── "is not set" → 환경 변수 설정 확인 (echo $VAR_NAME)

│

└── 접속 실패(failed) → claude mcp get <n> 으로 설정 확인

6단계: OAuth 연계의 개요

Claude Code에서는 OAuth 계열 연계가 가능합니다. OAuth 대응 MCP 서버는 최초 접속 시에 브라우저에서의 인가 플로우를 시작하는 경우가 있습니다.

OAuth 연계의 일반적인 흐름:

1. MCP 서버가 인가 URL을 제시

2. 사용자가 브라우저에서 인가를 승인

3. 인가 코드가 MCP 서버에 전달됨

4. MCP 서버가 액세스 토큰을 취득·보유

5. 이후의 요청은 액세스 토큰으로 인증

OAuth 대응 MCP 서버를 이용하는 경우는 해당 서버의 문서에 따라 셋업합니다.

� API 키 vs OAuth의 선택 기준 (한국 팀 개발 환경)

7단계: 인증 정보 관리의 철칙

철칙:

인증 정보를 포함하는 파일은 반드시 .gitignore에 추가한다

인증 정보를 커밋에 포함시켜버린 경우는, 즉시 토큰을 무효화한다

토큰의 스코프는 필요 최소한으로 한다

정기적으로 토큰을 교체한다 (90일마다 교체를 권장)

⚠️ 중요 경고: .gitignore로 인증 정보 파일을 제외하거나, CLAUDE.md에서 .env 파일을 읽어 들이지 않도록 지시해도, Claude Code가 인증 정보를 읽어버리는 사례가 보고되고 있습니다. 완전한 보안 대책은 존재하지 않으므로, 토큰의 스코프를 필요 최소한으로 하고, 불필요한 인증 정보는 프로젝트 내에 두지 않도록 합시다.

인증 정보 유출 시의 대응 체크리스트:

## 토큰 유출 시 즉시 대응

- [ ] GitHub Settings > Developer settings에서 해당 PAT를 즉시 무효화
- [ ] GitHub의 Security alerts 확인 (불심 액세스가 없었는지)
- [ ] 해당 PAT로 접근 가능했던 리포지토리의 커밋 이력 확인
- [ ] 새로운 PAT 발행 (Fine-grained 토큰으로 교체 권장)
- [ ] .gitignore 설정 재검토
- [ ] 팀 멤버에게 유출 사실 공유 및 영향 범위 확인

더 나아가기

.gitignore 설정 확인

현재 프로젝트의 .gitignore 설정이 올바른지 확인합니다.

cat ~/mcp-workspace/.gitignore

다음 패턴이 포함되어 있는지 확인하세요.

.env
.env.*
config/mcp-auth.json
config/mcp-all.json
*.secret

Git 이력에 인증 정보가 없는지 확인

실수로 커밋한 인증 정보가 없는지 확인합니다.

# 토큰 패턴을 git 이력에서 검색
git log --all --full-history --oneline -- "*.json" | head -20
git grep -i "ghp_\|token\|password\|secret" $(git rev-list --all) 2>/dev/null | head -10