AI Sparkup

최신 AI 쉽게 깊게 따라잡기⚡

MCP 튜토리얼 – Claude Desktop과 Claude Code에 MCP 서버 연결하기

목차

MCP 서버를 Claude에 연결하면 채팅창 안의 모델이 파일, GitHub, 검색, 데이터베이스 같은 외부 시스템을 표준 프로토콜로 사용할 수 있다. Claude Desktop은 앱 설정 파일이나 Desktop Extensions로, Claude Code는 claude mcp add CLI로 연결하는 흐름이 가장 일반적이다.

핵심 구조

MCP는 세 부분으로 나뉜다.

구성요소역할예시
Host사용자가 대화하는 AI 앱Claude Desktop, Claude Code, Cursor
ClientHost 안에서 서버와 통신Claude 내장 MCP 클라이언트
Server도구·리소스·프롬프트를 노출하는 외부 프로세스GitHub MCP, Filesystem MCP

사용자가 “내 PR을 확인해줘”라고 요청하면 Claude가 GitHub 도구 필요성을 판단하고, MCP 클라이언트가 서버에 JSON-RPC 요청을 보내며, 서버가 GitHub API 결과를 구조화해 반환한다.

Claude Desktop 연결

Claude Desktop은 두 경로를 쓴다.

  1. Desktop Extensions: .mcpb 번들을 설치하는 방식이다. 지원 서버라면 JSON을 직접 편집하지 않아도 된다.
  2. JSON config: claude_desktop_config.json에 서버별 command, args, env를 직접 적는다.

macOS 기본 경로는 다음과 같다.

~/Library/Application Support/Claude/claude_desktop_config.json

Windows는 설치 방식에 따라 %APPDATA%\Claude\claude_desktop_config.json 또는 Microsoft Store/MSIX 패키지 경로를 쓴다. 실제 경로가 헷갈리면 Claude Desktop의 Settings -> Developer -> Edit Config에서 파일을 열어 생성하는 편이 안전하다.

Claude Code 연결

Claude Code에서는 CLI 명령으로 서버를 추가한다.

claude mcp add github npx -y @modelcontextprotocol/server-github

토큰이 필요한 서버는 환경 변수로 넣는다. GitHub 서버라면 fine-grained personal access token을 만들고 필요한 저장소와 권한만 부여한다. MCP 설정은 편의 기능이 아니라 권한 경계이므로, “모든 저장소·무기한 토큰”을 기본값으로 두면 안 된다.

설치할 때 볼 점

  • 파일 시스템 서버는 허용 디렉터리를 좁게 잡는다.
  • GitHub 토큰은 필요한 repo와 Contents/Issues/Pull requests 권한만 선택한다.
  • 원격 서버는 가능하면 Streamable HTTP 기반인지 확인한다.
  • 서버 이름은 모델이 이해하기 쉬운 업무명으로 둔다.
  • 여러 서버를 한꺼번에 붙이기보다 자주 쓰는 2~3개부터 검증한다.

흔한 문제

증상원인대응
서버가 보이지 않음설정 파일 경로가 다름앱에서 Edit Config로 실제 파일 열기
JSON 파싱 실패Windows 경로의 백슬래시 이스케이프 누락C:\\Users\\...처럼 이중 백슬래시 사용
도구 호출 실패토큰 권한 부족서버 로그와 provider API 권한 확인
Claude가 도구를 과하게 씀서버 설명·도구 이름이 모호함서버 이름과 tool description을 구체화

관련 문서

참고 자료

AI Sparkup 구독하기

최신 게시물 요약과 더 심층적인 정보를 이메일로 받아 보세요! (무료)