Claude Code MCP: 연결은 되었으나 작동하지 않을 때? 이 세 가지 게이트를 확인하세요

MCP 서버는 claude mcp list에 나타나도 첫 실제 요청에서 실패할 수 있습니다. 대부분의 경우 연결 자체는 문제가 없으며, 세 개의 독립적인 게이트 중 하나가 닫혀 있는 것입니다. 순서대로 확인하면 많은 설정 변경 작업을 줄일 수 있습니다.

세 가지 게이트

Claude Code의 모든 MCP 요청은 세 가지 독립적인 검사를 통과해야 합니다:

증상을 읽고, 게이트를 선택하세요

한 가지 세부 사항이 많은 사람들을 게이트 2에서 걸리게 합니다. 권한 규칙은 전체 서버 또는 단일 도구를 대상으로 할 수 있으며, 서버가 도구 이름을 설정합니다. 규칙을 작성하기 전에 실제 이름을 검사하세요. 본인의 서버 레이블에서 추측한 이름은 일치하지 않을 수 있습니다.

무언가를 공유하기 전에 범위를 선택하세요

Claude Code는 세 가지 범위(scope) 중 하나에 MCP 연결을 저장합니다:

• Local (기본값): 현재 프로젝트의 사용자.
• Project: 프로젝트의 .mcp.json을 받는 모든 사람.
• User: 사용자의 모든 프로젝트 전반.

프로젝트 범위(Project-scope) 정의를 공유하는 것은 연결 자체를 공유하는 것이지, 접근 권한을 공유하는 것이 아닙니다. 각 팀원은 여전히 자신의 자격 증명(credential)을 제공해야 하며, 이는 일반적으로 .mcp.json에 참조된 환경 변수를 통해 이루어지므로 비밀 정보가 리포지토리에 남지 않습니다.

접근 제한은 두 번 하세요

이슈를 요약하는 것과 같은 읽기 전용 작업의 경우, 두 계층 모두 제한하세요:

1. 읽기 전용 엔드포인트 또는 도구 세트를 사용합니다. 이렇게 하면 서버가 읽기 전용 도구만 제공하도록 합니다.
2. 읽기 전용 자격 증명(credential)을 사용하여, 나중에 누군가가 엔드포인트를 교체하더라도 해당 신원(identity)이 쓸 수 없도록 합니다.

엔드포인트는 연결이 노출하는 것을 제한합니다. 반면, 자격 증명은 해당 신원이 할 수 있는 것을 제한합니다. 둘 다 필요합니다. 왜냐하면 어느 한쪽이라도 다른 쪽 없이 변경될 수 있기 때문입니다.

빠른 검증 습관

더 큰 작업에 새로운 연결을 맡기기 전에, 손으로 확인할 수 있는 하나의 레코드(record)를 요청하세요: 제목(title), 상태(state), 소유자(owner), 그리고 URL. 해당 URL을 열고 모든 필드를 비교합니다. 만약 어떤 필드가 누락되었다면, 지어내기보다는 그 사실을 알려주어야 합니다. 무엇을 확인했고 언제 확인했는지 기록해 두세요. 이 하나의 확인된 조회(lookup)가 나중에 무언가 고장 났을 때의 기준선이 됩니다.

더 깊이 들어가기

• 읽기 전용 GitHub 토큰, .mcp.json 항목 및 문제 해결표를 포함한 전체 워크스루는 Timo Labs에서 확인할 수 있습니다: Claude MCP 서버 통합 가이드.
• 아키텍트 시험에서는 이와 동일한 결정들을 테스트합니다. CCAR-F 학습 가이드의 task statement 2.4: MCP 서버 통합을 참고하세요.
• 시험 유형 시나리오로 스스로 점검하려면, 무료 Claude Certified Architect 모의 시험을 시도해 보세요.