본문 바로가기
M MCP모아
튜토리얼 · 2026.11.17 업데이트

VS Code에 MCP 서버 추가하기 — Copilot 에이전트 연결부터 오류 해결까지

VS Code GitHub Copilot 에이전트 모드에 MCP 서버를 추가하는 전 과정을 단계별로 정리합니다. .vscode/mcp.json 작성, inputs로 안전한 API 키 관리, ENOENT·권한 오류 등 디버그까지 한 번에 해결하세요.

VS Code 에디터에 MCP 서버를 추가하고 GitHub Copilot 채팅창에서 툴을 실행하는 화면 구성도

VS Code 1.99부터 GitHub Copilot 에이전트 모드에서 MCP(Model Context Protocol) 서버를 직접 연결할 수 있습니다. 설정 파일에 서버 정보를 몇 줄 추가하면 Copilot 채팅창에서 외부 툴을 바로 호출할 수 있습니다. 이 글에서는 설정 파일 작성부터 서버 활성화, 안전한 API 키 관리, 툴 테스트, 흔한 오류 디버그까지 한 번에 다룹니다.

MCP 서버를 VS Code에 연결하면 무엇이 달라지나요?

MCP는 AI 에이전트가 외부 도구와 데이터 소스를 표준 방식으로 호출할 수 있게 해주는 오픈 프로토콜입니다. Claude Desktop이나 Cursor에서 이미 MCP를 써 봤다면 개념은 같습니다. VS Code에서는 GitHub Copilot 에이전트 모드가 MCP 클라이언트 역할을 합니다.

아래 흐름처럼 에디터 안에서 코드와 외부 서비스를 넘나드는 작업이 가능해집니다.

[VS Code 에디터]
    └─ GitHub Copilot 채팅 (에이전트 모드)
           │  MCP 툴 호출 (stdio / SSE)
           ▼
    [MCP 서버 프로세스]   (npx / node / uvx 등으로 실행)
           │  외부 API·파일 시스템·데이터베이스
           ▼
    [결과 → Copilot 응답으로 반환]

예를 들어 한글 문서를 열어 둔 채 Copilot에게 “이 HWP 파일의 3절을 요약해줘”라고 말하면, HWP-MCP 서버가 파일을 파싱해 텍스트를 돌려주고 Copilot이 그 내용으로 응답합니다. 이 모든 과정이 에디터 밖으로 나가지 않고 완결됩니다. 코드 리뷰 중 관련 문서를 실시간으로 참조하거나, 계약서 같은 공문서를 Markdown으로 변환하는 작업도 별도 탭을 열지 않고 채팅창 안에서 끝낼 수 있습니다.

준비물

항목요구 사항
VS Code1.99 이상 (2025년 4월 릴리스 기준, 안정 채널 또는 Insiders)
GitHub Copilot 확장1.300 이상 (GitHub Copilot Chat 포함, 에이전트 모드 활성화)
GitHub Copilot 구독Individual / Business / Enterprise
Node.jsnpx 방식 서버 사용 시 18 이상 권장
uv (uvx)uvx 방식 서버(Python MCP) 사용 시 필요

유의: MCP 도구를 포함한 Copilot 에이전트 모드는 GitHub Copilot 구독(Individual·Business·Enterprise)이 필요합니다. 무료 플랜(Copilot Free)의 에이전트 모드 지원 여부는 GitHub 공식 문서에서 확인하세요.

Copilot Chat 확장이 없다면 VS Code 마켓플레이스에서 GitHub Copilot Chat을 검색해 설치·업데이트하세요.

단계별 설정 방법

1단계 — VS Code 버전 및 에이전트 모드 확인

VS Code 상단 메뉴 도움말 → 정보에서 버전을 확인합니다. 터미널을 쓴다면 다음 명령으로도 확인할 수 있습니다.

code --version

출력된 버전이 1.99 미만이면 VS Code 공식 사이트(code.visualstudio.com)에서 최신 버전으로 업데이트하세요. 이어서 확장 패널(Ctrl+Shift+X / Cmd+Shift+X)에서 GitHub Copilot Chat을 검색해 최신 버전으로 업데이트합니다.

Copilot 채팅창을 열고(단축키 Ctrl+Alt+I / Cmd+Alt+I) 입력창 왼쪽의 드롭다운을 클릭해 에이전트(Agent) 모드를 선택합니다. Ask나 Edit가 아니라 반드시 Agent여야 MCP 도구가 노출됩니다. 에이전트 모드가 보이지 않으면 settings.json에서 아래 옵션을 활성화한 뒤 재시작합니다.

{
  "chat.agent.enabled": true
}

2단계 — MCP 설정 파일 위치 결정

VS Code는 두 곳에서 MCP 설정을 읽습니다.

범위파일 위치언제 쓰나
프로젝트 전용.vscode/mcp.json (servers 키)팀 공유, git에 커밋 가능
사용자 전역settings.json (mcp.servers 키)개인 도구, 모든 프로젝트에 적용

팀과 공유하는 프로젝트 전용 서버라면 .vscode/mcp.json을 사용하는 것이 좋습니다. 저장소에 커밋해 두면 팀원이 코드를 내려받는 순간부터 동일한 MCP 환경을 사용할 수 있습니다. 개인 API 키처럼 민감한 정보가 포함된 서버는 사용자 전역 settings.json에 넣거나 뒤에 설명할 inputs 기능으로 분리하세요.

3단계 — .vscode/mcp.json 파일 생성과 기본 구조

프로젝트 루트에 .vscode 폴더가 없으면 만들고 그 안에 mcp.json을 생성합니다.

mkdir -p .vscode
touch .vscode/mcp.json

.vscode/mcp.json의 최상위 키는 servers입니다. 각 서버에 고유한 이름을 키로 쓰고 type, command, args를 지정합니다.

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "패키지명"]
    }
  }
}

핵심 필드 설명:

  • servers: 서버 이름을 키로 쓰는 객체. 이름은 자유롭게 지정합니다.
  • type: 로컬 프로세스 방식인 "stdio"와 HTTP 서버 방식인 "sse"를 지원합니다. 대부분의 npx/uvx 기반 서버는 "stdio"를 씁니다.
  • command: 실행할 명령어(npx, node, python 등).
  • args: 명령어에 전달할 인수 배열. -y 플래그는 패키지 설치 확인 프롬프트를 건너뛰므로 자동화 환경에서 필수입니다.
  • env: 선택 사항. API 키 등 환경 변수를 객체로 전달합니다.

4단계 — 실제 서버 등록 예시

아래는 한국 공문서를 다루는 MCP 서버 세 개를 한 번에 등록하는 예시입니다. 필요한 서버만 골라 넣어도 됩니다.

{
  "servers": {
    "kordoc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    },
    "hwp-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    },
    "hwpforge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

전역(모든 프로젝트) 적용이 필요한 경우

모든 프로젝트에서 동일한 서버를 쓰려면 사용자 settings.json에 추가합니다. 명령 팔레트(Ctrl+Shift+P / Cmd+Shift+P)에서 **Preferences: Open User Settings (JSON)**을 열고 mcp.servers 아래에 작성합니다.

{
  "mcp": {
    "servers": {
      "kordoc": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "kordoc", "mcp"]
      }
    }
  }
}

5단계 — API 키가 필요한 서버 안전하게 처리하기

일부 서버는 API 키나 토큰을 환경 변수로 받습니다. 가장 간단한 방법은 env에 값을 직접 넣는 것이지만, 키를 git에 노출할 위험이 있습니다.

{
  "servers": {
    "my-api-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "API_KEY": "여기에-실제-키-입력"
      }
    }
  }
}

더 안전한 방법은 VS Code의 inputs 기능으로 키를 분리하는 것입니다. inputs를 쓰면 VS Code가 서버를 처음 시작할 때 팝업으로 값을 요청하고, 파일에는 키가 남지 않습니다.

{
  "servers": {
    "my-api-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "API_KEY": "${input:apiKey}"
      }
    }
  },
  "inputs": [
    {
      "id": "apiKey",
      "type": "promptString",
      "description": "서버 API 키를 입력하세요",
      "password": true
    }
  ]
}

password: true로 설정하면 입력값이 화면에 마스킹됩니다. 이 방식을 쓰면 .gitignore에 별도 항목을 추가하지 않고도 .vscode/mcp.json을 안전하게 공유할 수 있습니다. 키를 env에 직접 적은 경우에는 반드시 .gitignore에 .vscode/mcp.json(또는 settings.json)을 추가해 공개 저장소에 올라가지 않도록 하세요.

6단계 — 서버 활성화 및 연결 확인

설정을 저장한 뒤 VS Code를 완전히 종료(Quit)했다가 다시 실행합니다. 단순히 창만 닫고 새 창을 여는 것으로는 부족하며, 이 단계를 건너뛰면 서버가 인식되지 않습니다. 에이전트 모드로 전환되면 VS Code가 .vscode/mcp.json을 자동으로 읽어 등록된 서버를 시작합니다.

연결을 확인하는 방법은 두 가지입니다.

  • Copilot 채팅 입력창 옆의 도구(Tools) 아이콘을 클릭하면 연결된 MCP 서버와 노출된 도구 목록이 표시됩니다. 서버 이름이 보이면 정상입니다. 여기서 각 도구를 켜고 끌 수도 있습니다.
  • 명령 팔레트에서 **“MCP: List Servers”**를 실행하면 서버 상태를 확인할 수 있습니다. running 상태이면 정상입니다.
kordoc   — running
hwp-mcp  — running

별도 명령으로 서버를 띄우고 싶다면 명령 팔레트에서 **“MCP: Start Server”**를 실행해 추가한 서버를 선택하면 됩니다.

7단계 — Copilot 채팅에서 MCP 툴 테스트

에이전트 모드 채팅창에 등록한 서버의 기능을 호출하는 질문을 입력합니다.

보고서.hwp 파일을 읽고 주요 내용을 요약해줘

Copilot이 HWP-MCP 도구를 자동으로 선택해 파일을 읽고 결과를 반환합니다. 파일 경로는 프로젝트 루트 기준 상대 경로와 절대 경로 모두 쓸 수 있습니다. 코르독 서버는 다음처럼 변환을 요청해 볼 수 있습니다.

계약서.docx 파일을 Markdown으로 변환해줘

Copilot이 MCP 툴 실행 허가를 요청하면 **허용(Allow)**을 클릭합니다. 처음 실행 시 한 번만 확인 절차가 있으며, 이후에는 자동으로 툴을 호출합니다.

한국 개발자에게 유용한 MCP 서버 예시

개발 도구 카테고리에는 VS Code와 잘 어울리는 서버가 많습니다. 아래 세 서버는 모두 API 키 없이 바로 사용할 수 있어 설정이 간단합니다.

서버기능설치 명령
코르독 (KorDoc)HWP·HWPX·PDF·XLSX·DOCX를 Markdown으로 변환npx -y kordoc setup
HWP-MCPAI가 한글(.hwp/.hwpx) 문서를 읽고 편집·생성npx -y hwp-mcp
한포지 (HwpForge)HWPX 문서를 AI 에이전트가 읽고 쓰고 변환 (KS X 6101 지원)npx -y @hwpforge/mcp

흔한 오류와 해결 방법

설정 후 서버가 보이지 않거나 연결 오류가 나면, 먼저 아래 표에서 증상을 찾아 대응하세요.

증상원인해결 방법
Copilot Chat에 MCP 도구가 표시되지 않음에이전트 모드 미선택 또는 mcp.json 문법 오류Agent 모드 전환 확인, JSON 문법 검사 후 VS Code 완전 재시작
spawn npx ENOENTnpx/node 경로 미인식 또는 미설치npx/node 설치 확인, command에 절대 경로 지정
JSON.parse / 파싱 오류mcp.json 문법 오류 (특히 trailing comma)편집기의 빨간 밑줄 또는 JSON 검증기로 점검
EACCES: permission deniednpx 캐시·설치 경로 쓰기 권한 없음npm cache clean --force 후 재시도, 권한 수정
도구 호출 후 응답 없음 / 파일 못 찾음서버 프로세스 오류 또는 상대 경로 불일치출력 패널 로그 확인, 파일 경로를 절대 경로로 재입력

오류: “spawn npx ENOENT”

VS Code가 npx 경로를 인식하지 못하는 경우입니다. VS Code는 시스템 셸의 PATH를 그대로 상속하지 않을 수 있습니다.

해결: 터미널에서 which npx(Windows는 where npx)로 전체 경로를 확인한 뒤 command에 입력합니다.

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "/usr/local/bin/npx",
      "args": ["-y", "패키지명"]
    }
  }
}

Windows에서 spawn npx ENOENT가 난다면 command를 npx.cmd로 지정해야 하는 경우가 있습니다.

{
  "servers": {
    "hwp-mcp": {
      "type": "stdio",
      "command": "npx.cmd",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

오류: 권한 오류 (macOS/Linux)

Error: EACCES: permission denied

npx 캐시 디렉토리나 설치 대상 경로에 쓰기 권한이 없을 때 발생합니다. 터미널에서 npm cache clean --force 후 다시 시도하거나 npm 글로벌 디렉토리 권한을 수정하세요. 상세 내용은 npm 공식 문서를 참고하세요.

서버가 running인데 도구가 0개이거나 보이지 않는 경우

서버 자체는 실행됐지만 도구를 노출하지 않거나, Copilot이 캐시한 목록을 아직 갱신하지 않은 경우입니다.

해결: Copilot Chat의 Tools 패널에서 해당 도구가 꺼져 있는지 확인하고 토글을 켭니다. 그래도 보이지 않으면 Copilot Chat 창을 닫았다 다시 열거나, 명령 팔레트에서 **“GitHub Copilot: Refresh MCP Servers”**를 실행합니다.

출력 패널에서 로그 확인하기

오류 원인을 파악할 때는 출력 패널이 가장 빠릅니다.

  1. Ctrl+Shift+U로 출력(Output) 패널을 엽니다(메뉴는 보기 → 출력).
  2. 드롭다운에서 GitHub Copilot 채널을 선택합니다.
  3. MCP 서버 기동 시도와 오류 메시지, 스택 트레이스를 확인합니다.

VS Code mcp.json vs Claude Desktop config 비교

같은 MCP 서버라도 Claude Desktop과 VS Code는 설정 파일 형식이 다릅니다. Claude Desktop 설정을 그대로 복사하면 동작하지 않으니 키 이름과 구조를 변환해야 합니다.

항목VS CodeClaude Desktop
파일명.vscode/mcp.json (프로젝트) / settings.json (전역)claude_desktop_config.json
최상위 키servers (전역은 mcp.servers)mcpServers
서버 타입 키"type": "stdio" 명시없음 (stdio 기본)
전역 파일 위치VS Code settings.json~/Library/Application Support/Claude/... (macOS 기준)
구독 필요 여부GitHub Copilot 구독 필요Claude 계정(무료 포함)
에이전트 모드 전환Chat 패널에서 Agent 선택항상 MCP 활성화 상태

두 환경에 같은 서버를 동시에 등록해도 됩니다. 코딩 작업은 VS Code에서, 일반 문서 작업은 Claude Desktop에서 나눠 쓰는 방식이 효율적입니다.

자주 묻는 질문

VS Code에서 MCP 서버를 사용하려면 어떤 버전이 필요한가요?

VS Code 1.99 이상, GitHub Copilot 확장 1.300 이상이 필요합니다. MCP 지원은 2025년 초 Copilot 에이전트 모드와 함께 정식 도입되었습니다. Insiders 채널을 쓰면 새 기능을 더 빨리 경험할 수 있습니다.

VS Code에서 MCP를 쓰려면 GitHub Copilot 유료 플랜이 필요한가요?

네, MCP 도구를 포함한 에이전트 모드는 GitHub Copilot 구독(Individual·Business·Enterprise 모두 가능)이 필요합니다. 무료 플랜(Copilot Free)의 에이전트 모드 지원 여부는 GitHub 공식 문서에서 확인하세요.

MCP 설정을 프로젝트별로 할지 사용자 전역으로 할지 어떻게 결정하나요?

팀과 공유하는 프로젝트 전용 서버는 .vscode/mcp.json에 넣고 git에 커밋하세요. 개인 도구나 모든 프로젝트에 공통 적용할 서버는 사용자 settings.json의 mcp.servers 키를 사용합니다.

.vscode/mcp.json을 Git에 커밋해도 안전한가요?

API 키나 비밀 값이 직접 들어 있으면 .gitignore에 추가해 커밋을 막아야 합니다. 민감 정보는 파일에 직접 적지 말고 inputs 입력 프롬프트 기능으로 분리하거나 별도 환경 변수로 관리하면 안전하게 공유할 수 있습니다.

Copilot Chat에서 MCP 툴이 보이지 않으면 어떻게 하나요?

먼저 채팅이 에이전트(Agent) 모드인지 확인하세요. VS Code를 완전히 재시작하고, mcp.json의 JSON 문법(쉼표, 따옴표)을 점검합니다. 명령 팔레트에서 **“MCP: List Servers”**로 상태를 확인하고, stopped라면 **“MCP: Start Server”**로 시작하세요. 그래도 안 되면 출력 패널의 GitHub Copilot 채널 로그를 확인합니다.

npx로 MCP 서버를 실행하면 ENOENT 오류가 납니다.

npx가 PATH에 있는지 npx --version(또는 which npx)으로 확인한 뒤, command에 npx 전체 절대 경로를 넣으면 해결되는 경우가 많습니다. Node.js가 없다면 nodejs.org에서 18 이상을 설치하세요.

npx 방식과 uvx 방식 중 어느 것을 써야 하나요?

서버가 Node.js 패키지로 배포된 경우 npx를, Python 패키지는 uvx(uv 도구 필요)를 씁니다. 서버의 README에서 설치 유형을 확인하세요.

Claude Desktop에서 쓰던 설정을 VS Code에 그대로 복사해도 되나요?

형식이 다릅니다. Claude Desktop은 claude_desktop_config.json에서 mcpServers 키를 쓰고, VS Code는 .vscode/mcp.json에서 servers 키와 "type": "stdio"를 씁니다. 키 이름과 구조를 맞게 변환해야 합니다.

다음 단계

VS Code에 MCP 서버를 성공적으로 추가했다면, 이제 더 많은 서버를 탐색해 볼 차례입니다.

이 글과 관련된 MCP 서버