Claude Code 상세 사용법 49: MCP 서버 붙이고 디버깅하기 | DAKER 커뮤니티

Claude Code 상세 사용법 49: MCP 서버 붙이고 디버깅하기

MCP는 Claude Code가 기본 파일/쉘 도구 밖의 시스템을 쓰게 만드는 연결 방식입니다. 이슈 트래커 검색, 문서 검색, 브라우저 제어, DB 조회 같은 작업을 “프롬프트로 흉내 내기”가 아니라 tool call로 다루게 합니다. 공식 quickstart는 서버를 추가하고, 연결 상태를 보고, 세션에서 실제 tool call 라벨을 확인하는 순서를 권장합니다.

가장 작은 성공 사례부터

처음에는 인증이 필요 없는 서버로 흐름을 확인하세요. 공식 예시는 Claude Code docs MCP 서버입니다. 이 명령은 Claude Code 세션 안이 아니라 일반 터미널에서 실행합니다.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list

상태가 connected로 나오면 새 세션을 열고 서버 이름을 명시해 테스트합니다.

Use the claude-code-docs server to look up what MCP_TIMEOUT does.

답이 맞는지만 보지 말고 출력에 서버 이름이 붙은 tool call이 있는지 확인하세요. 그래야 Claude의 기억이나 WebFetch가 아니라 실제 MCP 경로를 탔다는 증거가 됩니다.

local stdio 서버는 명령을 그대로 검증한다

브라우저나 로컬 리소스가 필요하면 stdio 서버를 씁니다. 예를 들어 Playwright MCP는 npx로 실행되는 로컬 서버입니다.

claude mcp add playwright -- npx -y @playwright/mcp@latest
claude mcp list

처음에는 패키지를 내려받느라 failed처럼 보일 수 있습니다. 잠시 후 다시 claude mcp list를 실행하세요. 계속 실패하면 Claude Code 밖에서 아래 명령을 직접 실행해 Node, 브라우저, 네트워크 문제인지 분리합니다.

npx -y @playwright/mcp@latest

팀 공유는 project scope로

개인용 서버는 기본 local scope나 --scope user가 편합니다. 팀이 같은 MCP 구성을 써야 하면 project scope로 추가해 .mcp.json을 커밋합니다.

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

직접 쓰는 .mcp.json은 이런 모양입니다.

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

프로젝트 MCP는 clone한 사람이 처음 실행할 때 승인해야 합니다. 저장소가 마음대로 로컬 프로세스를 띄우지 못하게 하는 안전장치입니다.

상태 메시지로 다음 행동을 정한다

Needs authentication이면 /mcp에서 Authenticate를 고르거나 token header를 설정합니다. Failed to connect면 HTTP 서버는 curl -I, stdio 서버는 해당 command 직접 실행으로 나눠 봅니다. Pending approval이면 project .mcp.json 승인이 남은 상태입니다. .mcp.json 수정 후 적용이 안 되면 세션을 재시작하세요. 공식 문서는 Claude Code가 이 파일을 세션 시작 시 읽는다고 설명합니다.

선임 엔지니어 takeaways

MCP는 Claude Code를 만능으로 만드는 장식이 아닙니다. 권한 있는 외부 시스템을 LLM 개발 워크플로우에 붙이는 계약입니다. 그래서 이름, scope, 인증, 실패 상태, tool call 증거를 모두 운영 기록으로 남겨야 합니다. 이렇게 하면 클로드 코드 기반 AI 코딩, CLI 자동화, 테스트 자동화가 “브라우저에서 알아서 해줘”보다 훨씬 재현 가능한 agentic coding 흐름이 됩니다.

참고: Claude Code 공식 MCP, MCP quickstart, debug configuration 문서를 기준으로 작성했습니다.