MCP 서버 연결해서 AI 에이전트 실전 활용하는 법: 클로드 데스크톱·코드 설정 가이드 (2026)

챗GPT나 클로드에게 “내 컴퓨터 이 폴더 안 파일 좀 찾아서 요약해줘”라고 말해봤자 안 되는 이유는 간단합니다. AI 모델 자체에는 원래 여러분의 파일, 깃허브 저장소, 노션 문서에 접근할 방법이 없기 때문입니다. 결론부터 말씀드리면 이 문제를 표준 규격으로 풀어주는 게 MCP(Model Context Protocol)이고, 클로드 데스크톱은 설정 파일 편집 한 번, 클로드 코드는 터미널 명령 한 줄로 이런 외부 도구를 AI 에이전트에 “연결”할 수 있습니다.

지난번 MCP 2026-07-28 업데이트: 프로토콜이 세션을 버리고 stateless로 바뀐 이유에서 이 프로토콜 자체의 스펙 변화를 다뤘다면, 이번 글은 “그래서 지금 내 컴퓨터에서 어떻게 연결하고 어디에 쓰면 되는가”에 초점을 맞춘 실전 가이드입니다. 이번 스펙 변경의 세부 항목은 MCP 공식 체인지로그에서 직접 확인할 수 있습니다.

글쓰기 과정에서 아래 설치·연결 절차를 실제로 윈도우 PC에서 그대로 따라 해봤고, 중간에 실제로 마주친 연결 실패와 그 원인·해결 과정까지 뒤쪽 “직접 연결해보고 만난 에러” 항목에 그대로 남겼습니다. 준비물부터 설치, 실제 활용 아이디어까지 순서대로 정리했습니다.

MCP 서버 연결 전 준비물

연결 자체는 어렵지 않지만, 아래 세 가지가 미리 준비되어 있지 않으면 중간에 막힐 수 있습니다.

• 클로드 데스크톱 또는 클로드 코드 최신 버전: 오래된 버전은 MCP 설정 메뉴 자체가 없거나 위치가 다를 수 있습니다. 클로드 코드는 터미널에 claude --version을 입력하면 바로 확인됩니다(이 글 작성에 쓰인 환경에서는 2.1.220 (Claude Code)로 확인됨).
• Node.js(npx 포함): 파일시스템 MCP처럼 많이 쓰이는 서버 상당수가 `npx -y 패키지명` 형태로 실행되므로, Node.js가 설치되어 있어야 합니다. 터미널에 `node -v`를 입력해 버전이 뜨는지 먼저 확인하세요.
• 연결하려는 서비스의 인증 정보: 깃허브 MCP처럼 원격 서버는 개인 액세스 토큰(PAT) 같은 인증 값이 필요합니다. 토큰은 필요한 최소 권한(read-only 등)으로 발급하는 것이 안전합니다.

클로드 데스크톱·클로드 코드에 MCP 서버 연결하는 법

같은 MCP 서버라도 클라이언트(호스트 앱)에 따라 연결 방식이 다릅니다. 두 가지를 순서대로 살펴보겠습니다.

1) 클로드 데스크톱 — 설정 파일 편집 방식

클로드 데스크톱은 GUI 메뉴에서 설정 파일을 열어 직접 JSON을 작성하는 방식입니다.

1. 클로드 메뉴 → 설정(Settings) → Developer → Edit Config를 클릭하면 `claude_desktop_config.json` 파일이 자동으로 열립니다(윈도우 기준 경로는 `%APPDATA%\Claude\claude_desktop_config.json`).
2. 아래처럼 `mcpServers` 항목 안에 서버를 추가합니다(내 컴퓨터의 문서 폴더를 연결하는 파일시스템 MCP 예시).

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\사용자명\\Documents"
      ]
    }
  }
}

3. 파일을 저장하고 클로드 데스크톱 앱을 완전히 종료했다가 다시 실행합니다.
4. 재실행 후 입력창 하단(또는 도구 아이콘)에 연결된 MCP 서버 목록이 뜨면 정상 연결된 것입니다.

2) 클로드 코드 — 터미널 명령 한 줄 방식

클로드 코드는 파일을 직접 편집할 필요 없이 CLI 명령으로 등록합니다.

• 로컬(stdio) 서버: claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "C:\Users\사용자명\Documents"
• 원격(HTTP) 서버: claude mcp add --transport http github https://api.githubcopilot.com/mcp/ (인증 헤더가 필요하면 claude mcp add-json 명령으로 JSON 형태에 `headers` 필드를 함께 넣습니다. 자세한 설치 옵션은 깃허브 공식 MCP 서버 저장소에서 확인할 수 있습니다.)

등록 범위는 옵션으로 조절할 수 있습니다. 기본값은 지금 작업 중인 프로젝트에만 적용되는 local 범위이고, --scope user를 붙이면 모든 프로젝트에서, --scope project를 붙이면 같은 저장소를 쓰는 팀원과 설정을 공유할 수 있습니다. 연결 상태는 claude mcp list 명령이나 세션 중 /mcp 명령으로 바로 확인 가능합니다. 옵션별 세부 동작은 클로드 코드 공식 문서(MCP Quickstart)에 정리되어 있습니다.

3) 직접 연결해보고 만난 에러 — 실제 트러블슈팅 기록

파일시스템 MCP 서버를 실제로 하나 추가해봤습니다.

$ claude mcp add my-filesystem -- npx -y @modelcontextprotocol/server-filesystem "C:\Users\사용자명\Documents"
Added stdio MCP server my-filesystem with command: npx -y @modelcontextprotocol/server-filesystem C:\Users\사용자명\Documents to local config

등록은 정상적으로 됐지만, 바로 이어서 claude mcp list로 상태를 확인해보니 연결에 실패했습니다.

$ claude mcp list
Checking MCP server health…
my-filesystem: npx -y @modelcontextprotocol/server-filesystem C:\Users\사용자명\Documents - ✘ Failed to connect — MCP server "my-filesystem" connection timed out after 30000ms

원인을 찾으려고 같은 명령을 npx로 직접 실행해보니, 실제 에러 메시지가 나왔습니다.

$ npx -y @modelcontextprotocol/server-filesystem "C:\Users\사용자명\Documents"
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'zod' imported from
...\npm-cache\_npx\<hash>\node_modules\@modelcontextprotocol\server-filesystem\dist\index.js

원인은 npx 캐시 손상이었습니다. 이전에 이미 한 번 내려받았던 패키지 캐시가 최신 버전의 의존성(zod)과 어긋나면서, 정작 서버 프로세스는 30초 넘게 응답 없이 멈춰 있다가 타임아웃으로 실패한 것으로 확인됐습니다. 해결은 문제가 된 캐시 폴더 하나만 지우고 다시 실행하는 것으로 끝났습니다.

$ rm -rf "%LOCALAPPDATA%\npm-cache\_npx\<hash>"
$ claude mcp list
Checking MCP server health…
my-filesystem: npx -y @modelcontextprotocol/server-filesystem C:\Users\사용자명\Documents - ✔ Connected

정리하면, `claude mcp list`에서 “Failed to connect”만 보고 포기하지 말고 `claude mcp get 서버이름`으로 정확한 오류 문구를 먼저 확인하는 것이 핵심입니다. 오류가 `ERR_MODULE_NOT_FOUND`처럼 모듈을 못 찾는 내용이라면 이번 사례처럼 npx 캐시 손상 가능성을 의심해볼 만합니다(테스트에 쓴 서버는 확인 후 claude mcp remove my-filesystem -s local로 정리했습니다).

연결 후 실전 활용법

서버를 연결한 다음부터는 평소 클로드와 대화하듯 자연어로 요청하면 됩니다.

• 파일시스템 MCP 연결 시: “Documents 폴더에서 지난달 작성한 견적서 파일 찾아서 항목별로 표로 정리해줘”
• 깃허브 MCP 연결 시: “이번 주에 새로 열린 이슈 중 라벨이 bug인 것만 요약해서 우선순위대로 정리해줘”

바이브 코딩처럼 클로드 코드를 코딩 작업에 쓰고 있다면 깃허브 MCP 연결이 특히 체감 효과가 큽니다. 클로드 코드 자체의 활용법은 바이브 코딩 도구 비교 글에서 다른 도구들과 함께 정리했습니다.

회사 내부 시스템이나 유료 SaaS가 제공하는 원격 MCP 서버를 쓰는 경우라면 2026-07-28 스펙 변화의 체감 효과가 더 큽니다. 예전에는 서버가 재시작되거나 트래픽이 몰려 다른 인스턴스로 요청이 넘어가면 세션 정보가 끊겨 재연결이 필요했는데, 세션 자체가 사라진 지금은 그런 구조적 원인의 연결 끊김이 줄어듭니다. 클로드 등 주요 클라이언트는 구버전 서버를 만나면 기존 방식(handshake)으로 자동 전환하므로, 서버 쪽이 아직 업데이트 전이어도 당장 문제가 생기지는 않습니다.

실전 활용 아이디어 — 부업·자동화에 적용하기

MCP는 개발자 전용 기능이 아닙니다. 아래처럼 부업·생산성 업무에도 바로 응용할 수 있습니다.

• 프리랜서 서류 정리: 파일시스템 MCP로 견적서·인보이스가 쌓인 폴더를 연결해두면, 매번 폴더를 뒤지는 대신 “이번 달 발행한 인보이스 총액 합산해줘”처럼 바로 물어볼 수 있습니다.
• 콘텐츠·블로그 부업: 원고 초안 폴더를 파일시스템 MCP로 연결해 “최근 초안 중 아직 발행 안 한 것만 목록으로 뽑아줘” 같은 관리 업무를 줄일 수 있습니다.
• 자동화 워크플로우와 결합: MCP로 정리·검색한 데이터를 n8n 같은 자동화 도구의 트리거 입력으로 넘기면, 사람이 매번 개입하지 않아도 되는 파이프라인을 만들 수 있습니다. n8n 자체의 노드 연결 구조가 궁금하다면 n8n 워크플로우 예제 5가지를 참고하세요.

클로드의 다른 확장 기능인 Agent Skills와 MCP는 역할이 다릅니다. MCP가 “외부 데이터·도구에 연결하는 통로”라면, Skills는 “반복 작업 절차를 재사용 가능한 지침으로 저장”하는 기능에 가깝습니다. 두 기능을 같이 쓰는 방법은 클로드(Claude) Agent Skills 활용법에서 다뤘습니다.

자주 묻는 질문

핵심 요약

• MCP 서버 연결은 클로드 데스크톱에서는 `claude_desktop_config.json` 편집, 클로드 코드에서는 `claude mcp add` 명령으로 진행하며, 로컬(stdio)과 원격(HTTP) 서버는 등록 방식이 다릅니다.
• 위 트러블슈팅 기록처럼 실제 연결 시도의 첫 시도는 npx 캐시 손상으로 타임아웃 실패했고, `claude mcp get`으로 정확한 오류를 확인해 해당 캐시 폴더만 지우자 정상 연결됐습니다 — 같은 오류를 만나면 이 순서를 그대로 따라 해보세요.
• 파일 정리, 코드/이슈 관리, 자동화 파이프라인 연동처럼 부업·생산성 업무에 바로 적용할 수 있고, 필요한 서버만 최소 권한으로 연결해두는 것이 실전 활용의 핵심입니다.

---