[Claude Code] 클로드코드 MCP 사용법 (+ MCP 사용 예제 - Context7)

Claude Code나 Cursor 같은 AI 도구를 쓰다 보면 "MCP"라는 단어를 자주 보게 됩니다. 이번 포스팅에서는 MCP가 무엇인지부터 시작해 Claude Code에 MCP 서버를 설치하고 권한을 설정하는 과정까지, Context7을 예제로 정리해 보았습니다.

 

MCP란 무엇인가

MCP는 AI와 외부 프로그램을 잇는 다리입니다

MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)는 Claude 같은 AI 모델이 외부 프로그램과 소통할 수 있도록 정해 둔 표준 규칙입니다. 쉽게 말해 AI와 외부 서비스 사이를 이어 주는 다리 역할을 합니다.

 

예를 들어 Notion 워크스페이스에 읽어야 할 논문을 여러 편 모아 두었다고 가정해 보겠습니다. Claude에게 "내 노션에 있는 논문 좀 분석해 줘"라고 요청해도 결과는 기대와 다릅니다. LLM은 기본적으로 내 워크스페이스에 접근할 방법이 없기 때문입니다.

 

여기에 Notion MCP 서버를 연결하면 이야기가 달라집니다. Claude가 워크스페이스에 들어가 논문을 직접 읽고 분석할 수 있고, 새 페이지를 작성하거나 기존 글을 수정하는 일까지 해낼 수 있습니다.

 

MCP가 필수가 된 이유

MCP는 Claude를 만든 Anthropic이 공개한 프로토콜입니다. 처음에는 그다지 주목받지 못했지만, Claude Desktop과 Cursor AI 같은 인기 개발 도구가 MCP를 지원하기 시작하면서 분위기가 완전히 바뀌었습니다.

 

이제는 AI 도구를 실무에서 제대로 활용하려면 MCP가 사실상 필수입니다. 규칙이 표준으로 정해져 있다 보니 누구나 MCP 서버를 만들어 공개할 수 있고, 덕분에 다양한 MCP 서버가 빠르게 늘어나면서 개발 생산성도 크게 올라가고 있습니다.

 

MCP와 MCP 서버의 차이

두 용어가 비슷해서 같은 것으로 착각하기 쉽지만, 사실은 역할이 다릅니다.

• MCP: AI가 다른 프로그램과 "어떤 형식으로, 어떻게 주고받을지"를 정의한 규칙(프로토콜)입니다.
• MCP 서버: 그 규칙을 따라 특정 프로그램과 실제로 통신하도록 구현한 프로그램입니다.

백엔드 개발자에게 익숙한 개념으로 비유하면, MCP는 HTTP 같은 통신 규약이고 MCP 서버는 그 규약을 따르는 각각의 API 서버에 해당합니다.

 

이렇게 특정 작업을 하려면 그에 맞는 MCP 서버를 써야합니다. 결국 MCP는 AI와 대화만 주고받는 수준을 넘어, AI가 다른 프로그램을 직접 다룰 수 있게 해 주는 통로라고 이해하시면 되겠습니다.

 

---

코드 할루시네이션 - AI가 코드를 "지어내는" 문제

AI로 개발하다 보면 그럴듯해 보이지만 실제로는 틀린 코드를 받는 일이 꽤 많습니다. 흔히 겪는 사례는 이런 것들입니다.

• 최신 Next.js로 만들어 달라고 했는데, 공식 문서가 권장하는 App Router가 아니라 예전 방식인 Pages Router로 코드를 짜 줍니다.
• 존재하지도 않는 옵션이나 API를 실제로 있는 것처럼 제안합니다.
• 프로젝트는 React 최신 버전으로 세팅했는데, 구현 코드는 예전 버전 문법으로 작성합니다.

이렇게 AI가 최신 정보를 헷갈리거나 없는 내용을 사실처럼 만들어 내는 현상을 코드 할루시네이션(환각)이라고 부릅니다. 프롬프트를 꼼꼼하게 작성하는 것도 도움이 되지만, 더 확실한 방법은 AI에게 정확한 맥락(컨텍스트)을 직접 넣어 주는 것입니다.

 

Context7이란

Context7은 AI 코딩 어시스턴트가 항상 최신 라이브러리 문서를 참고할 수 있게 해 주는 문서 플랫폼입니다. Cursor AI나 Claude Code에 Context7 MCP 서버를 연결해 두면, AI가 오래된 학습 데이터에 기대지 않고 최신 공식 문서를 찾아 답변에 반영합니다. Context7 사이트에는 Next.js, React를 비롯해 많이 쓰이는 라이브러리가 대부분 등록되어 있습니다.

 

---

Claude Code에 MCP 서버 설치하기

Claude Code에 MCP 서버를 추가하는 방법은 간단합니다. claude mcp add 명령어 하나면 됩니다. 대부분의 MCP 서버는 GitHub 저장소나 공식 문서에 도구별 설치 방법을 안내하고 있어서, Claude Code 항목을 찾아 claude mcp add로 시작하는 명령어를 그대로 복사해 쓰면 됩니다.

 

설치 범위(scope) 이해하기

MCP 서버를 설치할 때는 어디까지 적용할지 범위를 정할 수 있습니다. 범위는 --scope 옵션으로 지정하며, 모두 세 가지가 있습니다.

CLAUDE.md나 settings.json이 사용자 단위와 프로젝트 단위로 나뉘는 것과 같은 구조라고 보시면 이해하기 쉽습니다.

 

팀으로 개발하고 있다면 project 스코프를 추천합니다. .mcp.json을 Git으로 관리하면 팀원 모두가 같은 MCP 환경을 쓸 수 있습니다.

 

Context7 설치 실습

이제 Context7 MCP 서버를 project 스코프로 직접 설치해 보겠습니다. Context7 GitHub 저장소에서 Claude Code용 설치 명령어를 복사한 뒤, 프로젝트 디렉터리에서 실행하면 됩니다.

 

원격 서버(HTTP) 방식

claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp

실행이 끝나면 프로젝트 루트에 .mcp.json 파일이 생기고, 그 안에 방금 등록한 Context7 서버 정보가 담깁니다.

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

 

API 키는 선택 사항입니다

공식 문서의 설치 명령어에는 API 키를 넣는 부분이 포함되어 있지만, Context7은 API 키 없이도 충분히 쓸 수 있습니다. 그 부분은 지우고 설치해도 괜찮습니다. 다만 사용량이 많을 예정이라면 API 키를 발급받아 설정해 두는 편이 좋습니다.

1. Context7 대시보드에 접속해 회원가입을 합니다.
2. API 키 생성 버튼을 눌러 새 키를 발급받습니다.
3. 발급받은 키를 설치 명령어나 .mcp.json의 API 키 항목에 넣습니다.

# API 키를 함께 설정하는 경우
claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: 발급받은_API_키"

API 키는 외부에 노출되면 안 되는 값입니다. .mcp.json을 Git에 올릴 계획이라면 키를 파일에 직접 적지 말고 환경 변수로 분리해 두는 것이 안전합니다. 무료 여부 같은 정책은 바뀔 수 있으니 설치 전에 공식 문서도 한 번 확인해 보시기 바랍니다.

 

보안 승인과 연결 확인

설치를 마치고 claude로 Claude Code를 실행하면, 새 MCP 서버를 발견했다며 사용을 승인할지 묻는 화면이 뜹니다. 앞으로 .mcp.json에 추가될 서버까지 모두 허용하려면 1번, 이번 서버만 허용하려면 2번을 고르면 됩니다. 보통은 1번을 선택합니다.

연결이 잘 되었는지는 Claude Code 안에서 /mcp 명령어로 확인합니다. 정상이라면 체크 표시와 함께 connected라고 나옵니다.

 

연결에 실패했을 때: 로컬 방식으로 재설치

그런데 /mcp로 확인해 보면 failed로 표시될 때가 있습니다. 원인은 Claude Code에게 물어봐도 되지만, 경험상 원격 서버(HTTP) 방식은 환경에 따라 연결이 안 되는 경우가 종종 있습니다. 이럴 때는 내 컴퓨터에서 서버를 직접 실행하는 로컬 방식(npx)으로 다시 설치하면 대부분 해결됩니다.

1. 기존에 등록한 서버를 제거합니다.
2. npx로 실행하는 로컬 방식 명령어로 다시 설치합니다.
3. Claude Code를 재실행한 뒤 /mcp로 연결 상태를 확인합니다.

# 1. 기존 서버 제거
claude mcp remove context7

# 2. 로컬(npx) 방식으로 재설치
claude mcp add --scope project context7 -- npx -y @upstash/context7-mcp --api-key 발급받은_API_키

한 가지 주의할 점이 있습니다. npx처럼 -- 뒤에 실행 명령어가 오는 형태에서는 --scope 같은 옵션을 반드시 -- 앞에 적어야 합니다. -- 뒤에 오는 값은 전부 MCP 서버의 실행 인자로 넘어가기 때문입니다.

다시 설치하고 나면 .mcp.json은 아래처럼 바뀝니다.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "발급받은_API_키"]
    }
  }
}

설치가 실패했다고 당황할 필요는 없습니다. 공식 문서에는 원격 방식과 로컬 방식 등 여러 설치 방법이 나와 있으니, 하나씩 시도해 보면 됩니다.

 

Context7 사용해 보기

Context7은 기술 관련 질문이나 분석을 요청하면 Claude가 필요하다고 판단할 때 알아서 호출합니다. 확실하게 쓰게 하고 싶다면 프롬프트 끝에 use context7을 붙여 주면 됩니다.

Next.js 기반 최신 웹 개발 기술 스택을 추천해 줘. use context7

요청을 보내면 다음 순서로 진행됩니다.

1. Claude가 Context7을 쓰겠다고 판단하고, 라이브러리 검색 도구(resolve-library-id)를 사용해도 되는지 승인을 요청합니다.
2. 승인하면 프롬프트 속 Next.js를 찾아 해당 라이브러리 ID를 확인합니다.
3. 이어서 문서를 가져오는 도구(get-library-docs)의 실행 승인을 요청합니다.
4. 승인하면 최신 공식 문서를 바탕으로 답변을 만들어 줍니다.

실제 결과를 보면 Next.js 15, React 19처럼 최신 버전을 기준으로 기술 스택을 추천해 줍니다. Claude Code로 개발하면서 "분명 최신 버전으로 해 달라고 했는데 예전 코드가 나오는" 경험을 해 보셨다면, Context7이 꽤 괜찮은 해결책이 될 것입니다.

 

MCP 서버 설치 = Claude Code에 도구 추가

Claude Code는 기본적으로 Bash 명령어 실행, 파일 편집 같은 도구를 갖고 있습니다. MCP 서버를 설치한다는 것은 여기에 그 서버가 제공하는 도구를 새로 추가하는 것과 같습니다. 그리고 Claude Code는 새로운 도구를 쓰기 전에 항상 사용자에게 승인을 받습니다.

한 번 승인한 도구는 설정 파일(.claude/settings.local.json 등)의 permissions.allow 목록에 자동으로 기록됩니다.

 

MCP 도구 권한 한 번에 승인하기

Context7은 resolve-library-id, get-library-docs 두 개의 도구만 갖고 있지만, MCP 서버에 따라서는 도구가 수십 개에 이르기도 합니다. 이걸 매번 하나씩 승인하려면 꽤 번거롭습니다.

이럴 때는 권한 설정에 mcp__서버이름(언더바 두 개) 형식으로 적어 주면 해당 서버의 모든 도구를 한 번에 허용할 수 있습니다.

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "mcp__context7"
    ]
  }
}

이렇게 해 두면 해당 프로젝트에서 Claude Code가 Context7의 모든 도구를 따로 묻지 않고 사용합니다. 권한 설정에서 특정 Bash 명령어를 허용하는 것과 같은 원리입니다.

일괄 승인은 편리하지만, 데이터를 수정하거나 삭제할 수 있는 MCP 서버(DB, Notion 쓰기 등)라면 신중하게 판단하는 것이 좋습니다. Context7처럼 문서를 읽기만 하는 서버라면 일괄 승인해도 부담이 적습니다.

 

정리

• MCP는 AI 모델이 외부 프로그램과 소통하기 위한 표준 규칙으로, Anthropic이 공개했습니다.
• MCP 서버는 그 규칙에 따라 Notion, YouTube, DB 같은 특정 프로그램과 연결되도록 구현한 것입니다.
• Claude Code에서는 claude mcp add로 설치하고, 범위는 local(기본값) / project / user 중에서 고릅니다.
• project 스코프로 설치하면 .mcp.json이 생성되어 Git으로 팀과 공유할 수 있습니다.
• 원격 방식으로 연결이 안 되면 npx 로컬 방식으로 다시 설치해 봅니다.
• Context7은 최신 라이브러리 문서를 제공해 코드 할루시네이션을 줄여 주며, 프롬프트에 use context7을 붙이면 확실하게 호출할 수 있습니다.
• 권한 설정에 mcp__서버이름을 추가하면 해당 서버의 도구를 한 번에 승인할 수 있습니다.

MCP 서버를 하나씩 연결할수록 Claude Code가 할 수 있는 일도 점점 넓어집니다. 다음 글에서는 실무에서 유용한 다른 MCP 서버들을 설치하고 활용하는 방법을 정리해 보겠습니다.