GitHub MCP 연결 전 확인할 것: Codex·Claude Code 설정과 계정 권한

MCP 연결·활용 / 계정 권한 설계

GitHub MCP는 AI가 저장소의 파일, 이슈, Pull Request를 읽고 일부 작업을 수행하게 합니다. 편리한 만큼 계정 권한을 연결하므로, 설치 명령보다 어떤 저장소와 작업을 허용할지 먼저 정해야 합니다.

이럴 때 쓸 만하다

예를 들어 “현재 저장소의 열린 버그 이슈 중 로그인과 관련된 것을 찾아 요약해줘”처럼 GitHub에 있는 정보를 대화 안에서 확인할 때 도움이 됩니다. 공식 GitHub MCP 서버는 저장소·코드 조회, 이슈·PR 관리, 워크플로 상태 확인 등의 도구를 제공합니다. “PR 작성까지 한 번에 처리한다”는 식의 소개는 권한과 사용자 검토 단계를 생략하므로 정확하지 않습니다. 연결한 계정과 도구 설정에 따라 가능한 일이 달라집니다.

Codex에 원격 서버를 등록하는 방법

GitHub의 Codex 설치 안내는 원격 주소와 PAT 환경변수를 다음처럼 설정합니다. GITHUB_PAT_TOKEN은 변수 이름이며, 실제 토큰 문자열을 명령어나 공개 문서에 넣지 않습니다.

codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
codex mcp list

이 명령으로 등록했다고 인증이 끝난 것은 아닙니다. 권한을 제한한 GitHub Personal Access Token을 안전한 환경변수로 제공하고, Codex에서 도구가 보이는지 확인해야 합니다. 그다음 첫 요청은 “내 저장소 목록을 보여줘” 같은 읽기 작업으로 시작하세요. 401 Unauthorized라면 토큰 만료·철회 또는 설정 오류를 확인하고, 도구가 일부만 보이면 권한 범위를 점검합니다.

Claude Code는 설정법이 다르다

Claude Code CLI의 현재 절차는 GitHub 공식 Claude 설치 문서를 따르세요. 해당 문서는 Claude Code 버전에 따른 add-json과 이전 방식, Windows 명령 차이도 설명합니다. Claude 데스크톱 앱의 커넥터 화면을 Claude Code CLI와 같은 방식으로 다루면 연결 오류가 날 수 있습니다.

첫 실습은 읽기 작업으로 제한하기

이 저장소의 열린 이슈 중 문서 오류와 관련된 항목 3개를 찾아줘.
제목, 번호, 원문 링크만 알려줘. 이슈나 댓글은 수정하지 마.

반환된 링크를 직접 열어 맞는 이슈인지 확인하세요. 다음에 PR 작성이나 댓글 생성으로 범위를 넓힐 때는 대상 저장소와 변경 내용을 사람이 먼저 검토하는 절차를 넣는 편이 좋습니다. GitHub MCP에는 도구 묶음을 제한하는 설정과 읽기 전용 모드가 있습니다. 로컬 서버의 --read-only 옵션은 쓰기 도구를 빼는 기능으로 공식 문서에 나옵니다. 원격 서버의 세부 옵션은 GitHub의 현재 설정 문서를 확인하세요.

공개 저장소로 해보는 읽기 실습

실습 대상은 GitHub 공식 MCP 프로젝트의 공개 저장소 github/github-mcp-server입니다. 새 개인 저장소나 비공개 자료 없이 검색과 원문 확인의 흐름을 따라 할 수 있습니다. 이슈를 만들거나 댓글을 달 필요는 없습니다.

읽기 실습 설정 예제·검색 결과·원문 대조 코드 ZIP 받기. ZIP에는 실제 토큰이 없습니다. Codex와 Claude Code의 설정 예제를 분리했고, 토큰 없이도 공개 원문만 대조할 수 있는 Python 코드를 넣었습니다.

설정과 인증을 구분해서 준비하기

공식 서버는 공개 저장소를 읽을 때도 인증을 요구합니다. 이 검증 환경에서 토큰 없이 공식 호스티드 주소에 초기화 요청을 보내자 HTTP 401이 반환됐습니다. GitHub 웹에서 공개 페이지가 보인다고 MCP도 인증 없이 연결되는 것은 아닙니다.

본인 토큰을 준비할 때는 GitHub 공식 설치 안내에 따라 공개 자료 조회에 필요한 권한부터 확인하세요. 읽기 전용 서버 설정은 쓰기 도구를 제외하는 기능이며, 토큰 자체의 권한을 축소하지는 않습니다. 토큰 종류와 조직 정책에 따라 접근 조건도 달라집니다.

Codex에서는 ZIP의 codex-config-example.toml 섹션을 기존 사용자 설정에 병합합니다. Claude Code에서는 claude-mcp-example.json을 프로젝트의 .mcp.json에 병합합니다. 기존 설정 전체를 덮어쓰지 마세요. 두 예제 모두 https://api.githubcopilot.com/mcp/x/issues/readonly로 이슈의 읽기 도구만 사용하도록 범위를 정했습니다. 공식 읽기 모드 문서에 나온 주소입니다.

$secret = Read-Host '본인 GitHub 토큰' -AsSecureString
$env:GITHUB_PAT_TOKEN = [System.Net.NetworkCredential]::new('', $secret).Password
# 이 PowerShell에서 사용하는 호스트를 시작하세요.
codex mcp list
# Claude Code를 쓰면 claude mcp list로 확인합니다.

환경 변수는 이미 열려 있던 다른 앱에 자동으로 전달되지 않습니다. 같은 셸에서 호스트를 시작하고, 등록 목록 다음에 실제 도구 목록까지 확인하세요. 토큰은 채팅·캡처·설정 예제에 붙여 넣지 않습니다. 종료할 때는 호스트를 닫고 Remove-Item Env:GITHUB_PAT_TOKEN으로 현재 셸의 값을 제거합니다.

그대로 요청하고 원문을 확인하기

github/github-mcp-server에서 열린 이슈 중 제목에 docs가 있는 것을
최근 수정 순으로 최대 3개 찾아줘. PR은 제외하고 번호·제목·원문 링크만 적어줘.
3개보다 적으면 있는 개수만 알려줘. 이슈나 댓글은 수정하지 마.
실제 검색 도구를 호출하지 못하면 추측하지 말고 실패를 알려줘.

검색식은 repo:github/github-mcp-server is:issue is:open docs in:title입니다. 반환된 링크를 열어 저장소·번호·제목이 맞는지 확인합니다. 검색식에 is:issue를 넣는 것은 PR까지 섞이는 일을 피하기 위한 조건입니다.

실제로 확인한 결과는 3개가 아니라 2개

추가 검증에서는 기존 GitHub 연결 도구로 검색하고 두 이슈의 상세 내용을 조회했습니다. 이후 GitHub 공식 REST API로 번호·제목·링크·열림 상태를 대조했고 일치했습니다. 이것은 연결 도구의 읽기 작업 결과이며, 공식 호스티드 MCP 서버의 인증 성공 시험과는 구분됩니다. 공식 MCP에 본인 토큰으로 연결하는 단계는 이 환경에서 수행하지 않았습니다.

“최대 3개”를 요청했지만 검색 결과는 2개였습니다. 부족한 한 개를 만들어 넣거나 PR을 대신 넣으면 조건에 어긋납니다. 또 이슈의 제안이 현재 공식 설치 방법으로 채택됐다는 뜻은 아니므로, 이슈 본문을 설치 지침처럼 그대로 적용해서는 안 됩니다. 이후 제목·상태·검색 결과는 바뀔 수 있습니다.

원문만 독립적으로 대조하려면 ZIP을 풀고 py verify_public.py를 실행하세요. Python 3.11 이상과 인터넷이 필요합니다. 이 코드는 인증 없는 공개 REST 조회이며 MCP 연결을 대신하지 않습니다. 최신 검색 결과와 저장된 두 제목의 변경 여부를 출력합니다.

성공 기준과 실패했을 때의 확인 순서

• 성공: 실제 조회 도구 호출이 있고, 반환된 번호·제목·링크가 원문과 일치합니다. 단순히 AI가 “찾았다”고 답하는 것으로 판단하지 않습니다.
• 401: 토큰 변수 누락·만료·철회와 호스트를 시작한 셸을 확인합니다.
• 403: 권한·조직 정책·API 한도를 구분해서 확인합니다. 무조건 권한을 넓히지 않습니다.
• 0개: 저장소 이름과 검색식, 열린 이슈의 상태 변경을 확인합니다.
• 도구가 없음: 등록 자체와 서버 연결 성공을 구분하고 호스트의 MCP 상태를 확인합니다.

선택 기준

GitHub 이슈·PR을 자주 다루는 팀이라면 연결 가치가 큽니다. 파일 몇 개만 편집하는 개인 프로젝트라면 Codex의 기본 Git 작업으로 충분할 수도 있습니다. 계정 연결 전에 토큰 범위, 조직 정책, 쓰기 도구 노출 여부를 확인하세요. 토큰을 채팅이나 스크린샷에 올리지 마세요.

근거: GitHub MCP 공식 저장소, Codex 안내, Claude 안내. 계정 인증 후의 실사용은 이 글의 검증 범위에 포함되지 않습니다.