VSCode GitHub Copilot MCP 오류 해결: mcp.json, OAuth, PAT 설정 점검 순서

VSCode에서 GitHub Copilot MCP 서버가 연결되지 않을 때 확인할 핵심 지점을 정리한 이미지입니다.

VSCode에서 GitHub Copilot MCP 서버가 연결되지 않을 때는 먼저 Copilot Chat의 Agent Mode, MCP 서버 등록 위치, OAuth 또는 PAT 인증 방식, 조직 정책 차단 여부를 순서대로 확인해야 합니다. 단순히 VSCode를 재설치하기보다 mcp.json 설정과 인증 권한을 먼저 점검하는 편이 안전합니다.

특히 MCP server failed to start, Authentication failed, OAuth authorization failed, No tools available 같은 문구는 한 가지 원인만으로 발생하지 않을 수 있습니다. VSCode 확장 상태, GitHub 계정 권한, 조직 정책, Windows·Mac·WSL 환경 차이를 나누어 확인하면 같은 오류를 반복해서 만지는 일을 줄일 수 있습니다.

📑목차[보기]

• 1) VSCode GitHub Copilot MCP 오류가 나는 대표 상황
• 2) 먼저 확인할 빠른 점검 순서
• 3) GitHub Copilot Agent Mode가 보이지 않을 때
• 4) mcp.json 설정 위치와 기본 구조
• 5) OAuth 인증이 안 될 때 확인할 것
• 6) PAT 방식으로 연결할 때 필요한 권한
• 7) 조직 계정에서 MCP 서버가 차단되는 경우
• 8) VSCode에서 MCP 서버 로그 확인하는 방법
• 9) Windows, Mac, WSL 설정 차이
• 10) Claude MCP 오류와 GitHub Copilot MCP 오류의 차이
• 11) 공식 자료로 더 확인하기
• 12) 함께 보면 좋은 글
• 13) FAQ

VSCode GitHub Copilot MCP 오류가 나는 대표 상황

GitHub Copilot MCP 오류는 대부분 “서버 실행 실패”, “인증 실패”, “도구 목록이 비어 있음”, “조직 정책 차단” 중 하나로 나타납니다. 화면에 보이는 문구가 짧아도 실제 원인은 VSCode 설정 파일, Copilot 확장, GitHub 로그인 계정, 토큰 권한, 조직 보안 정책 중 여러 곳에 있을 수 있습니다.

아래 문구는 실제 사용자들이 검색하는 대표 오류 형태입니다. 단, VSCode와 GitHub Copilot 확장 버전, GitHub 계정 종류, 조직 정책에 따라 문구는 조금씩 다르게 보일 수 있습니다.

MCP server failed to start
command not found
permission denied
Authentication failed
OAuth authorization failed
No tools available
Agent mode is not available
This MCP server is disabled by organization policy

오류 상황	먼저 확인할 것	다음 조치
Agent Mode가 안 보임	Copilot Chat 버전·로그인 상태	VSCode와 확장 업데이트
MCP 서버가 안 보임	mcp.json 위치	MCP 서버 목록 새로고침
OAuth 실패	브라우저 로그인·계정 선택	GitHub 계정 재인증
PAT 권한 오류	토큰 스코프	필요한 권한만 다시 발급
조직 차단	회사 정책	관리자에게 MCP 허용 여부 확인

먼저 확인할 빠른 점검 순서

오류가 보이면 아래 순서대로 확인하는 것이 좋습니다. 인증을 먼저 바꾸거나 토큰을 계속 새로 만들기보다, Agent Mode와 MCP 서버 등록 상태를 먼저 확인하면 불필요한 권한 변경을 줄일 수 있습니다.

1. VSCode와 GitHub Copilot, GitHub Copilot Chat 확장을 최신 상태로 업데이트합니다.
2. GitHub 계정이 VSCode에 정상 로그인되어 있는지 확인합니다.
3. Copilot Chat에서 Agent Mode를 선택할 수 있는지 확인합니다.
4. MCP: List Servers 명령으로 GitHub MCP 서버가 보이는지 확인합니다.
5. mcp.json 파일 위치와 JSON 문법 오류를 확인합니다.
6. OAuth 방식인지 PAT 방식인지 인증 방식을 하나로 정리합니다.
7. 회사·조직 계정이라면 MCP 서버 허용 정책이 있는지 확인합니다.
8. Output, Developer Tools, MCP 관련 로그에서 실제 실패 지점을 확인합니다.

GitHub Copilot Agent Mode가 보이지 않을 때

GitHub MCP 서버는 Copilot Chat에서 외부 도구를 호출하는 흐름과 연결됩니다. 따라서 Agent Mode가 보이지 않는 상태라면 MCP 서버 설정만 수정해도 문제가 해결되지 않을 수 있습니다.

먼저 VSCode의 명령 팔레트에서 Copilot Chat이 정상적으로 열리는지 확인합니다. GitHub 계정 로그인이 풀려 있거나, Copilot 사용 권한이 없는 계정으로 로그인되어 있거나, 확장 업데이트가 오래된 경우 Agent Mode가 보이지 않을 수 있습니다.

GitHub Copilot: Open Chat
MCP: List Servers
MCP: Add Server
Developer: Toggle Developer Tools

개인 GitHub 계정과 회사 GitHub 계정을 함께 사용하는 경우에는 VSCode에 로그인된 계정과 브라우저에서 OAuth를 승인한 계정이 같은지 확인해야 합니다. 서로 다른 계정으로 인증하면 MCP 서버는 등록되어도 사용할 수 있는 저장소나 도구가 비어 보일 수 있습니다.

mcp.json 설정 위치와 기본 구조

VSCode의 MCP 서버 설정은 워크스페이스 단위 또는 사용자 프로필 단위로 둘 수 있습니다. 특정 프로젝트에서만 GitHub MCP 서버를 쓰려면 프로젝트의 .vscode/mcp.json을 사용하고, 여러 프로젝트에서 공통으로 쓰려면 VSCode 사용자 설정의 MCP 구성을 확인하는 편이 좋습니다.

위치	용도	주의점
.vscode/mcp.json	현재 프로젝트 전용 설정	팀 공유 시 토큰이 들어가지 않게 주의
User Configuration	사용자 전체 워크스페이스 공통 설정	프로필별로 설정이 달라질 수 있음
WSL 내부 경로	Linux 환경에서 실행되는 프로젝트 설정	Windows 경로와 혼동하지 않기

아래는 GitHub MCP 서버를 HTTP 방식으로 등록하는 기본 예시입니다. 실제 환경에서는 VSCode 버전, Copilot 설정 방식, OAuth 또는 PAT 사용 여부에 맞춰 값이 달라질 수 있습니다.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

OAuth 인증이 안 될 때 확인할 것

OAuth 방식은 토큰을 직접 복사해 넣지 않아도 되는 장점이 있습니다. 대신 브라우저 로그인 상태, GitHub 계정 선택, 조직 승인 정책, 팝업 차단 때문에 인증 창이 뜨지 않거나 다른 계정으로 승인되는 문제가 생길 수 있습니다.

• 기본 브라우저에서 GitHub에 로그인된 계정이 VSCode 계정과 같은지 확인합니다.
• 개인 계정과 회사 계정을 함께 사용한다면 인증 화면에서 계정 선택을 다시 확인합니다.
• 브라우저 팝업 차단, 보안 확장, 회사 프록시가 OAuth 리다이렉트를 막는지 확인합니다.
• 인증 후에도 No tools available이 보이면 조직 정책이나 저장소 접근 권한을 확인합니다.

OAuth 실패가 반복되면 VSCode에서 GitHub 로그아웃 후 다시 로그인하고, 브라우저에서도 사용하지 않는 GitHub 계정을 로그아웃한 뒤 재시도하는 방법이 도움이 될 수 있습니다. 회사 장비에서는 보안 프로그램이나 프록시 정책 때문에 OAuth 창이 정상적으로 열리지 않을 수 있으므로 내부 정책도 함께 확인해야 합니다.

PAT 방식으로 연결할 때 필요한 권한

PAT 방식은 토큰 권한을 세밀하게 지정할 수 있지만, 토큰 노출 위험이 있습니다. 토큰을 코드블록, 블로그 글, GitHub 저장소, 메신저에 실제 값으로 남기면 안 됩니다. 아래 예시는 형식 설명용 더미 값입니다.

방식	장점	주의점
OAuth	토큰을 직접 관리하지 않아도 됨	브라우저 인증·계정 선택 문제 발생 가능
PAT	권한을 세밀하게 지정 가능	토큰 노출 위험, 스코프 관리 필요

Mac이나 Linux, WSL에서는 환경변수로 토큰을 전달할 수 있습니다. 실제 사용 시에는 더미 값이 아니라 본인 계정에서 발급한 토큰을 넣되, 터미널 기록이나 저장소에 남지 않도록 주의해야 합니다.

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

Windows PowerShell에서는 아래처럼 현재 세션 환경변수로 지정할 수 있습니다.

$env:GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

PAT 권한 오류가 계속되면 토큰 스코프가 부족하거나, 조직에서 PAT 사용을 제한했거나, SSO 승인이 필요한 저장소일 수 있습니다. 필요한 권한보다 넓은 토큰을 만드는 대신, 공식 문서에서 요구하는 범위를 확인하고 최소 권한으로 다시 발급하는 편이 안전합니다.

조직 계정에서 MCP 서버가 차단되는 경우

회사 GitHub 계정이나 Enterprise 환경에서는 개인 계정과 다르게 MCP 서버 접근이 제한될 수 있습니다. 관리자가 MCP registry URL, allowlist 정책, Copilot 사용 범위, 외부 도구 연결 권한을 통제하면 사용자는 설정을 맞게 입력해도 MCP 서버를 사용할 수 없습니다.

이 경우에는 This MCP server is disabled by organization policy와 비슷한 문구가 보이거나, 서버가 등록되어도 도구 목록이 비어 보일 수 있습니다. 개인 저장소에서는 정상 작동하지만 회사 저장소에서만 실패한다면 조직 정책 가능성을 먼저 확인해야 합니다.

• 조직에서 GitHub Copilot 사용이 허용되어 있는지 확인합니다.
• 조직 관리자에게 GitHub MCP 서버가 allowlist에 포함되어 있는지 확인합니다.
• 회사 계정의 SSO, IP 제한, 프록시 정책이 OAuth 또는 PAT 인증을 막는지 확인합니다.
• 개인 계정으로 테스트할 때와 회사 계정으로 테스트할 때 결과가 다른지 비교합니다.

VSCode에서 MCP 서버 로그 확인하는 방법

화면의 짧은 오류 문구만 보고 원인을 판단하기 어렵다면 VSCode 로그를 확인해야 합니다. MCP 서버가 시작되지 않았는지, 인증 단계에서 실패했는지, 서버는 시작됐지만 도구 목록을 가져오지 못했는지 로그에서 구분할 수 있습니다.

MCP: List Servers
MCP: Add Server
Developer: Toggle Developer Tools
GitHub Copilot: Open Chat

명령 팔레트에서 MCP 서버 목록을 열었을 때 GitHub 서버가 보이지 않으면 설정 파일 위치나 JSON 문법을 먼저 확인합니다. 서버는 보이지만 실행 실패가 뜬다면 네트워크, 인증, 조직 정책, 확장 로그를 함께 확인해야 합니다.

Windows, Mac, WSL 설정 차이

Windows, Mac, WSL을 함께 쓰는 개발자는 mcp.json 위치와 실행 환경을 혼동하기 쉽습니다. VSCode를 Windows에서 열었는지, WSL 원격 환경으로 열었는지에 따라 설정 파일과 환경변수 적용 위치가 달라질 수 있습니다.

환경	확인할 위치	자주 생기는 문제
Windows	PowerShell 환경변수, VSCode 사용자 설정	토큰 세션 만료, 경로 구분자 혼동
Mac	zsh 환경변수, VSCode 프로필 설정	터미널과 VSCode 실행 환경 차이
WSL	Linux 내부 프로젝트 경로와 환경변수	Windows 설정을 WSL 설정으로 착각

WSL에서 프로젝트를 열었다면 Windows PowerShell에 지정한 환경변수가 WSL 내부 프로세스에 그대로 전달되지 않을 수 있습니다. 반대로 Windows VSCode에서 열린 프로젝트라면 WSL의 ~/.bashrc나 ~/.zshrc에 넣은 값이 적용되지 않을 수 있습니다.

Claude MCP 오류와 GitHub Copilot MCP 오류의 차이

Claude MCP 오류와 GitHub Copilot MCP 오류는 모두 MCP 서버 연결 문제처럼 보이지만 확인 순서가 다릅니다. Claude Desktop은 로컬 MCP 서버 실행 명령, 패키지 설치, PATH, 파일 권한 문제가 자주 나오고, GitHub Copilot MCP는 VSCode Agent Mode, GitHub 계정 인증, Copilot 권한, 조직 정책 확인이 더 중요합니다.

예를 들어 server failed to start 문구가 같아도 Claude 쪽에서는 실행 명령이 틀렸거나 패키지가 설치되지 않은 경우가 많고, GitHub Copilot 쪽에서는 MCP 서버 등록 위치나 OAuth·PAT 인증 문제일 수 있습니다. 같은 오류 문구라도 사용하는 클라이언트와 인증 구조를 나누어 봐야 합니다.

공식 자료로 더 확인하기

GitHub Copilot MCP 설정은 VSCode와 GitHub Copilot 기능 변화에 따라 화면과 메뉴명이 달라질 수 있습니다. 실제 적용 전에는 VS Code 공식 문서와 GitHub Docs에서 MCP 서버 추가 방식, 설정 파일 형식, GitHub MCP 서버 인증 방식, 조직 정책 기준을 함께 확인하는 것이 좋습니다.

함께 보면 좋은 글

FAQ

VSCode GitHub Copilot MCP 오류는 재설치보다 Agent Mode, mcp.json 위치, OAuth·PAT 인증, 조직 정책, 로그를 순서대로 확인하는 것이 핵심입니다.