Context7 MCP로 시작하는 첫 MCP 서버

「MCP와 확장」 코스의 마지막 글입니다. 앞에서 MCP의 구조와 claude mcp add 문법, 스코프, 인증을 익혔으니 이제 실제로 서버 하나를 붙여 봅니다. 첫 서버로 Context7을 고른 이유는 계정 없이 시작할 수 있고, 붙이자마자 "모델이 오래된 API를 지어내는" 문제가 눈에 띄게 줄어 효과를 바로 확인할 수 있기 때문입니다. 추가, 확인, 사용, 문제 해결까지 한 번에 따라 하면 다른 어떤 MCP 서버도 같은 순서로 붙일 수 있습니다.

핵심 요약

• Context7은 라이브러리의 버전별 공식 문서와 코드 예제를 가져와 프롬프트에 넣어 주는 MCP 서버입니다(MIT 라이선스, @upstash/context7-mcp).
• 로컬(stdio)은 claude mcp add context7 -- npx -y @upstash/context7-mcp, 리모트(HTTP)는 https://mcp.context7.com/mcp에 붙입니다.
• API 키는 선택이지만 권장입니다. context7.com/dashboard에서 무료로 발급하며 요청 한도가 올라갑니다.
• 프롬프트 끝에 use context7을 붙이면 호출되고, 처음에는 도구 사용 승인을 묻습니다.
• 잘 안 되면 claude mcp list의 상태 표시를 보고, npx -y @upstash/context7-mcp를 터미널에서 직접 실행해 원인을 가릅니다.

왜 첫 MCP 서버로 Context7인가

우리 6주차 교재의 10항 체크리스트로 판단해 보면 답이 나옵니다. GitHub 저장소가 있고(1), 라이선스가 MIT이며(2), README에 "API Key Recommended"라고 적혀 있지만 키는 무료 발급이고 없어도 동작합니다(3, 4, 5). npx로 로컬 실행이 되고(6), 리모트 엔드포인트도 함께 제공하며(7), 최근 업데이트가 이어집니다(8). 즉 서버 코드 비용도 0, 연결 서비스 비용도 0이라 "무료 + 내 업무에 필요" 조건을 통과합니다.

효과가 즉시 보이는 것도 이유입니다. 모델의 학습 데이터는 특정 시점에서 멈춰 있어, Next.js나 Supabase처럼 자주 바뀌는 라이브러리의 최신 API를 물으면 예전 문법을 자신 있게 답하곤 합니다. Context7은 질문할 때마다 해당 라이브러리의 현재 문서를 가져와 답변 근거로 넣습니다. 우리 관점으로 말하면 "추측 금지, 근거 기반"을 도구 수준에서 강제하는 셈입니다.

Context7 MCP 추가하기

터미널(claude 세션 밖)에서 실행합니다. 두 방식 중 하나를 고릅니다.

로컬(stdio) 방식. Node.js가 설치되어 있어야 하며, Context7 README는 18 이상, 트러블슈팅 문서는 20 이상을 권장합니다.

# API 키 없이 시작
claude mcp add context7 -- npx -y @upstash/context7-mcp

# API 키를 넣어 시작 (권장, 모든 프로젝트에서 쓰려면 --scope user)
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

리모트(HTTP) 방식. 설치할 것이 없고 서버 업데이트를 제공자가 관리합니다. Context7 문서는 API 키를 Authorization: Bearer 헤더로 넘기는 형태를 안내합니다.

claude mcp add --scope user --transport http context7 https://mcp.context7.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

팀과 공유하려면 --scope project로 추가해 .mcp.json을 커밋하되, 키는 ${CONTEXT7_API_KEY} 같은 환경 변수 참조로 적습니다. 실제 값은 각자의 셸에만 둡니다. API 키는 context7.com/dashboard에서 발급하며 ctx7sk로 시작합니다.

Windows에서는 위 명령이 PowerShell과 명령 프롬프트에서 동일하게 동작합니다. Context7 트러블슈팅 문서는 Windows에서 요청 시간 초과가 반복되면 Node.js 전체 경로를 쓰거나 cmd /c npx 형태로 실행하라고 안내합니다.

추가됐는지 확인하기

claude mcp list

context7: ... ✓ Connected가 보이면 준비된 것입니다. 로컬 방식의 첫 확인은 npx가 패키지를 내려받는 동안 ✗ Failed to connect로 나올 수 있으니 잠시 뒤 다시 실행합니다. 상세는 claude mcp get context7로 보며, 어느 스코프에 저장됐는지도 여기서 확인합니다. 세션 안에서는 /mcp를 입력해 같은 목록을 보고, 서버를 선택하면 제공하는 도구 두 개가 나열됩니다.

• resolve-library-id: 라이브러리 이름을 Context7 식별자(예: /vercel/next.js)로 바꿉니다.
• query-docs: 그 식별자로 질문에 맞는 문서 조각을 가져옵니다.

실제로 써 보기

claude를 시작하고 프롬프트 끝에 use context7을 붙입니다.

Next.js 14 미들웨어에서 로그인 안 된 사용자를 /login으로 보내는 코드를 써 줘. use context7

Claude가 먼저 resolve-library-id로 라이브러리를 찾고, query-docs로 관련 문서를 가져온 뒤, 그 내용을 근거로 답합니다. 출력에서 도구 호출이 context7 서버 이름으로 표시되므로 답이 모델 기억이 아니라 문서에서 왔는지 확인할 수 있습니다.

라이브러리를 이미 알면 식별자를 직접 적어 탐색 단계를 건너뜁니다.

Supabase 기본 인증을 구현해 줘. use library /supabase/supabase for API and docs.

버전을 문장에 넣으면("Next.js 14") 그 버전 문서를 맞춰 가져옵니다. 매번 use context7을 붙이기 번거로우면 프로젝트 CLAUDE.md에 규칙 한 줄을 둡니다. 우리 레포들에서는 "SDK나 프레임워크를 다룰 때는 공식 문서를 먼저 확인한다"는 원칙이 이미 CLAUDE.md에 있으므로, 거기에 "라이브러리 문서가 필요하면 Context7을 사용한다"를 덧붙이는 식입니다.

처음엔 도구 승인을 요구받습니다

Claude가 새 서버의 도구를 처음 호출하면 권한 프롬프트가 뜹니다. 어떤 도구를 어떤 인수로 부르는지 보여 주므로 확인하고 승인합니다. 이 프롬프트는 방어선입니다. 6주차 실습을 "승인제로 1개만 연결"로 잡은 것과 같은 이유로, 처음 몇 번은 무엇이 호출되는지 눈으로 보고 넘어가는 편이 낫습니다. 매번 묻는 것이 번거로워지면 설정의 permissions.allow에 mcp__context7__resolve-library-id와 mcp__context7__query-docs처럼 도구 이름을 등록합니다. 읽기 전용 도구이므로 허용해도 위험이 낮습니다.

잘 안 될 때 확인할 것

/mcp에서 disconnected로 표시된다

순서대로 가립니다.

1. claude mcp list로 상태를 봅니다. ✗ Failed to connect나 ✗ Connection error면 서버가 뜨지 않은 것입니다.
2. 로컬 방식이면 터미널에서 서버를 직접 실행합니다.

   npx -y @upstash/context7-mcp
   

   실행되어 입력을 기다리면 서버 자체는 정상입니다. 그러면 claude mcp get context7에 표시된 명령이 방금 실행한 것과 같은지 봅니다. 다르면 추가할 때 --를 빠뜨렸을 가능성이 높으니 claude mcp remove context7 후 다시 추가합니다.
3. 리모트 방식이면 엔드포인트가 열려 있는지 확인합니다. Context7 문서가 안내하는 확인 주소는 https://mcp.context7.com/ping입니다(PowerShell에서는 curl 대신 curl.exe).
4. 401이 돌아오면 API 키가 잘못된 것이고, 요청 한도 초과면 키를 추가하거나 잠시 기다립니다.
5. 첫 실행이 느려 시작 시간 제한(기본 30초)을 넘겼다면 MCP_TIMEOUT=60000 claude(PowerShell은 $env:MCP_TIMEOUT = "60000"; claude)로 늘려 봅니다.

npx를 찾을 수 없다

Node.js가 없거나 PATH에 없는 경우입니다. node -v와 npx -v가 버전을 출력해야 합니다. macOS는 nodejs.org 설치본이나 버전 관리자(nvm, mise)로, Windows는 nodejs.org 설치본으로 넣은 뒤 터미널을 새로 엽니다. 버전 관리자를 쓰는 macOS에서 Claude Code가 띄운 서버만 npx를 못 찾는다면, 셸 초기화 파일에서만 PATH가 잡히는 경우이므로 which npx로 확인한 전체 경로를 command에 적습니다. Context7 트러블슈팅 문서는 npx 대신 bunx, 또는 deno run --allow-net npm:@upstash/context7-mcp도 대안으로 제시합니다.

일단 재시작

.mcp.json은 세션 시작 시 읽히므로 파일을 고쳤다면 세션을 끝내고 다시 시작합니다. 프로젝트 스코프 서버를 한 번 거부했다면 claude mcp reset-project-choices로 승인 선택을 초기화한 뒤 다시 시작합니다. 세션 안에서 다시 연결만 시도하려면 /mcp에서 서버를 고르고 재연결을 선택합니다. 그래도 같은 증상이면 claude mcp remove context7로 지우고 처음부터 추가하는 것이 가장 빠릅니다.

정리

• Context7은 무료로 시작할 수 있고 효과가 바로 보이는 첫 MCP 서버입니다.
• 로컬은 claude mcp add context7 -- npx -y @upstash/context7-mcp, 리모트는 https://mcp.context7.com/mcp입니다.
• claude mcp list에서 ✓ Connected를 확인한 뒤 프롬프트에 use context7을 붙입니다.
• 문제는 상태 표시 → 서버 직접 실행 → -- 확인 → 재시작 순서로 가립니다.
• 첫 도구 승인은 방어선이니 무엇이 호출되는지 보고 넘어갑니다.

자주 묻는 질문