핵심 요약
- 서버 추가는 명령어 하나면 끝이에요. 로컬 서버는 claude mcp add name -- npx -y @scope/package, 원격 서버는 claude mcp add --transport http name url.
- 전송 방식은 세 가지예요. stdio는 내 머신에서 명령어를 실행하고, SSE는 구식 원격 방식, streamable HTTP가 요즘의 원격 표준이에요.
- 스코프 세 가지가 서버를 누가 쓸 수 있는지 정해요. local(나만), project(.mcp.json으로 공유), user(내 모든 프로젝트).
- 세션 안에서 /mcp를 실행하면 상태와 도구 목록이 보여요. 첫 도구 호출 때 권한을 물어보고, 한 번만 허용하거나 항상 허용할 수도 있어요.
Claude Code Tutorial #7 - MCP Servers
채널: The Net Ninja14:16
Claude Code MCP: How to Add MCP Servers (Complete Guide)
채널: Leon van Zyl17:58
Model Context Protocol (MCP) — official Claude Code docs
문서: code.claude.com/docs
스크린샷은 The Net Ninja의 챕터 — 깔끔한 전체 화면 녹화 — 에서 가져왔어요. 명령어 해부, 스코프, Windows 수정은 Leon van Zyl의 더 자세한 워크스루와 공식 문서를 따랐어요.
프레임 권리는 각 제작자에게 있으며, 해당 장면으로 바로 가는 딥 링크와 함께 출처를 표기했어요. 글은 저희가 썼어요.
0부터 작동하는 MCP 서버 2개까지
파트 1 · MCP 서버로 뭐가 달라지나
- 1
MCP가 Claude Code에 주는 것들
Claude Code에는 파일과 셸 도구가 기본으로 들어 있지만, 코드베이스 밖에는 손이 안 닿아요. MCP(Model Context Protocol)는 Anthropic 표준의 확장 도구 방식으로, 서버가 기능을 노출하면 Claude Code가 내장 도구처럼 호출해요.
MCP를 한 줄로 정의한 강의 슬라이드.0:52에 시청 - 2
할 일에 맞는 서버 고르기
서버마다 전용 도구가 달려 있어요. Supabase 서버는 테이블 조회, 엣지 함수 배포, SQL 실행을 하고, Playwright는 진짜 브라우저를 움직이고, Context7은 최신 프레임워크 문서를 줘요. 반복 노동을 없애 주는 것부터 시작하세요.
Supabase 예시: 도구 3개로 외부 서비스 하나를 다룬다.1:24에 시청 - 3
서버 README에서 설치 명령어 찾기
서버 제작자가 README에 Claude Code용 명령어를 올려두는 경우가 많아요 — Context7이나 Playwright도 마찬가지예요. 뭐가 있는지 둘러보려면 PulseMCP 같은 디렉터리가 편해요.
Playwright MCP README에 기능과 요구 사항이 정리되어 있어요.2:02에 시청 - 4
세 가지 전송 방식 이해하기
공식 문서는 설치를 로컬과 원격으로 나눠요. stdio 서버는 내 머신에서 명령어를 실행하는 기본 방식이고, SSE와 HTTP 서버는 연결하는 원격 엔드포인트예요. SSE는 구식이고 대체재가 streamable HTTP죠. claude mcp add 문법은 방식마다 조금씩 달라요.
로컬 stdio와 원격 SSE·HTTP를 비교한 공식 문서.3:02에 시청
파트 2 · 첫 서버 추가하기
- 5
project 스코프로 Context7 추가
터미널에서 claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp 을 실행해요. 이름은 마음대로 정하고, 대시 두 개 뒤가 실행 명령어이며, --scope project를 붙이면 개인 설정 대신 프로젝트 공유 설정에 기록돼요.
Context7 문서 서버를 추가하는 명령어.5:22에 시청 - 6
생성된 .mcp.json 읽어보기
project 스코프 서버는 저장소 루트의 .mcp.json, mcpServers 키 아래에 기록돼요. 각 항목에는 타입(여기선 stdio)과 명령어, 인수가 담기고, Cursor나 Claude Desktop과 같은 구조예요.
.mcp.json 내부: stdio 서버의 type, command, args.6:42에 시청 - 7
Windows는 cmd /c 접두사 주의
WSL 없는 네이티브 Windows에서는 npx 앞에 cmd /c를 붙여야 서버가 끝난 뒤 셸이 깔끔히 닫혀요. 공식 문서가 경고 박스로 짚어 주고, 영상에서도 수정할 위치를 그대로 보여 줘요.
Windows stdio 서버에 대한 공식 경고 박스.3:24에 시청 - 8
파일이 저장소에 생겼는지 확인
project 스코프로 추가하면 .mcp.json이 추적되지 않는 새 파일로 탐색기에 나타나요. 커밋하면 팀원들도 같은 서버를 쓸 수 있어요. local 스코프는 이 파일을 건드리지 않아요.
프로젝트 루트에 새로 생긴, 커밋 전의 .mcp.json.8:32에 시청 - 9
원격이 편하면 HTTP 전송으로
stdio가 말썽일 때 빠른 탈출구가 원격 엔드포인트예요: claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. 로컬 프로세스도 npm도 필요 없고, Claude Code가 URL에 바로 붙어요.
Context7 엔드포인트에 대한 HTTP 버전 추가 명령어.8:36에 시청 - 10
/mcp에서 연결 확인
Claude Code를 시작하고 /mcp를 실행해요. 서버별 상태와 도구 목록이 보여요. 실패는 내장 재연결로 대개 해결되고, 그래도 안 되면 아래 문제 해결 섹션에 흔한 원인들이 정리되어 있어요.
/mcp 패널에 연결된 context7과 도구 2개.9:22에 시청
파트 3 · 실전에서 서버 써보기
- 11
실제 프롬프트로 서버 불러오기
내장 도구로는 안 되는 일을 시키면서 서버 이름을 대놓으세요: “내 전역 CSS 파일과 비교해서 최신 Tailwind 문서 확인해 줘 — context7 써”. @ 멘션으로 파일을 붙이면 답이 내 코드에 딱 맞아떨어져요.
context7으로 최신 Tailwind 문서를 요청하는 프롬프트.9:38에 시청 - 12
도구 호출 승인하기
서버 도구가 처음 실행될 때 Claude Code가 권한을 물어봐요. 한 번만 승인하거나, 신뢰하는 서버라면 “항상 허용”을 골라서 이후 호출은 확인 없이 넘어가게 하세요.
Context7의 resolve-library-id 도구 권한 카드.10:00에 시청 - 13
근거 있는 답 읽기
도구가 관련 문서 — 여기선 Tailwind v4 테마 변수 가이드 — 를 토큰 비용과 함께 돌려주고, Claude Code가 내 파일에 반영해요. 이게 핵심이에요: 학습 데이터 추측이 아니라 최신 문서에 기반한 답이에요.
테마 설정을 확인하는 get-library-docs 응답.10:15에 시청 - 14
CLAUDE.md에 습관 남기기
해시(#) 기호를 입력하면 프로젝트 메모리를 추가할 수 있어요. 예: “새 라이브러리나 프레임워크를 구현할 땐 최신 문서를 Context7으로 확인”. 이 한 줄이 CLAUDE.md에 기록되고, 이후 모든 세션이 물려받아요.
Context7을 기본으로 만드는 한 줄짜리 CLAUDE.md 메모리.10:42에 시청 - 15
두 번째 서버: Playwright
브라우저 자동화도 같은 패턴이에요: claude mcp add playwright --scope project -- cmd /c npx @playwright/mcp@latest — macOS나 Linux에선 cmd /c 부분을 빼면 돼요. 저장소 하나, 서버 여러 개, 설정 파일은 하나.
project 스코프로 Playwright MCP 서버 추가.11:22에 시청 - 16
브라우저 굴리는 장면 보기
Claude Code에게 페이지 열고 요약하라고 시켜 보세요 — Playwright가 이동하고, 클릭하고, 읽고 결과를 보고해요. Context7의 문서와 Playwright의 브라우저만 있으면 대부분의 외부 잡일이 프롬프트 한 번으로 끝나요.
요약을 위해 사이트로 이동하는 Playwright MCP.12:42에 시청
환경 변수, 헤더, API 키
원격 서버와 인증이 필요한 API엔 자격 증명이 필요해요. Claude Code는 stdio 서버엔 환경 변수를, 원격 서버엔 헤더를 써요. 설정 파일을 직접 고칠 필요는 없어요.
- 1stdio 서버: claude mcp add myserver -e API_KEY=your-key -e ZONE=your-zone -- npx -y @some/mcp-server — 변수마다 -e를 반복하고, 서버 이름 바로 뒤에 둬요.
- 2원격 HTTP 서버: claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer your-key" — 이 헤더는 도구 호출 때마다 전송돼요.
- 3스코프 복습: local은 이 프로젝트에서 나만, project는 .mcp.json으로 공유, user는 내 모든 프로젝트에 설치. 추가할 때 -s 또는 --scope로 지정해요.
- 4서버 삭제: claude mcp remove name — project 스코프라면 .mcp.json 변경도 커밋해서 팀원 쪽에서도 빠지게 하세요.
-e로 넣은 값은 설정 파일에 평문으로 저장돼요. API가 허용하면 권한을 좁힌 키를 쓰고, 진짜 자격 증명을 project 스코프 .mcp.json에 커밋하지 마세요.
/mcp가 failed로 나올 때
Claude Code의 MCP 실패는 대부분 몇 가지 원인으로 수렴해요. 지웠다 다시 설치하기 전에 이 목록부터 훑어 보세요.
- 1Windows의 Unknown option -y: 터미널에 따라 npm의 이 플래그를 못 받아요. PowerShell이나 명령 프롬프트에서 추가 명령어를 실행하거나, -y를 빼고 추가한 뒤 .mcp.json의 args 배열에 손으로 다시 넣으세요.
- 2네이티브 Windows stdio 실패: 명령어 앞에 cmd /c — 예: cmd /c npx -y @some/package@latest. WSL 없이는 필수고, @latest 태그가 오래된 캐시 빌드도 피해 줘요.
- 3상태가 failed: /mcp를 열어 재연결 — 일시적 실패는 두 번째 시도에서 보통 풀려요. 안 풀리면 패널이 서버 로그 위치를 보여 주니 진짜 에러를 확인하세요.
- 4다른 프로젝트엔 서버가 없음: 스코프가 제대로 도는 거예요. project 스코프 서버는 그 저장소의 .mcp.json에만 살아요. 머신 전체에 깔려면 user 스코프로.
- 5연결됐는데 안 쓰임: 프롬프트에 이름을 대놓으세요 — “context7으로 문서 확인해 줘” — 하거나 CLAUDE.md 메모리를 추가하세요. 말해 주지 않으면 모델은 익숙한 내장 도구부터 집어요.
그래도 안 되면: claude mcp remove name으로 지우고, 터미널을 재시작하고, 확실히 되는 전송 방식 — 원격 HTTP가 가장 무난 — 으로 다시 추가하세요.