03-실전

03 — 실전: Claude Code에 MCP 서버 붙이기

5분 시나리오

목표: Claude Code에 Notion MCP 서버를 붙여서 “오늘 회의 노트 가져와”가 동작하게.

1) 명령어 한 줄

Claude Code는 claude mcp add 서브커맨드로 서버를 등록한다 — mcp.md.

# 원격(remote) Streamable HTTP 서버
claude mcp add --transport http notion https://mcp.notion.com/mcp

stdio(로컬) 서버라면:

claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

핵심 규칙: 모든 옵션은 서버 이름 앞에, -- 다음이 실제로 실행될 명령이다.

2) 스코프(Scope) 선택 — 셋 중 어디에 저장할까

스코프	저장 위치	용도
local (기본)	~/.claude.json (홈 디렉터리, 프로젝트별)	개인용·민감 자격 증명
project	<repo>/.mcp.json (Git에 커밋)	팀 공유
user	사용자 전역	모든 프로젝트에서 쓰는 개인 도구

# 팀 전체에 공유 — .mcp.json이 만들어지고 커밋된다
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

⚠️ project 스코프 서버는 Claude Code가 첫 사용 시 사용자 승인을 요구한다. 결정을 초기화하려면 claude mcp reset-project-choices.

3) 동작 확인

claude mcp list           # 등록된 서버 목록
claude mcp get notion     # 단일 서버 상세
claude /mcp               # 세션 안에서 연결 상태와 도구 목록 확인

Claude Code에서 /mcp를 치면 서버별 연결 상태, 노출된 도구·리소스 수가 보인다. 빨간색이면 stderr 로그를 확인하라.

디버깅: MCP Inspector

공식 도구 mcp-inspector는 서버를 GUI로 두드려보는 디버거다 — mcp-inspector.

npx @modelcontextprotocol/inspector npx -y airtable-mcp-server

브라우저가 뜨고 도구·리소스·프롬프트를 직접 호출할 수 있다. 서버를 만드는 동안 가장 많이 쓰는 도구다.

흔한 첫 실패

증상	원인	해결
서버가 즉시 죽음	stdout에 print/console.log 출력	모든 로그를 stderr로
도구가 안 보임	capability 협상 실패	Inspector로 initialize 응답 확인
Claude Desktop에서만 안 됨	상대 경로 사용	절대 경로로 바꿀 것
원격 서버 401	OAuth 토큰 만료	--header "Authorization: Bearer ..." 재설정

다음에 읽을 챕터

• 02-주요-MCP-서버-카탈로그 — 무엇이 이미 있나
• 03-MCP-서버-자체-제작 — 직접 만들기
• 04-MCP-보안 — 운영 전에 반드시