Quick Reference

MCP(Model Context Protocol)는 Claude Code가 외부 도구와 데이터를 호출하는 연결 방식입니다. 먼저 필요한 서버 하나만 연결하고, 이 설정을 나만 쓸지 팀과 공유할지 정한 뒤, 실제 연결·인증·권한을 모두 확인합니다. 서버를 추가했다는 메시지는 설정 파일에 기록됐다는 뜻일 뿐, 인증이나 연결 성공을 보장하지 않습니다.

# 현재 프로젝트에 개인적으로 추가한다.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 설정 기록이 아니라 실제 상태를 확인한다.
claude mcp list
claude mcp get sentry

# OAuth 서버라면 인증한다.
claude mcp login sentry

범위를 고르는 법

한 번만 시험하거나 개인 개발 도구라면 기본 local 범위가 맞습니다. 팀이 같은 서버를 재현해야 할 때만 project 범위를 골라 .mcp.json을 검토하고 커밋합니다. 개인이 모든 저장소에서 쓰는 도구는 user로 둘 수 있지만, 다른 프로젝트에도 자동으로 나타나는 범위를 감수해야 합니다.

project 설정은 편의 파일이 아니라 실행 가능한 외부 연결 목록입니다. 대화형 Claude Code는 처음 사용할 때 이를 승인하도록 묻지만, 비대화형 claude -p, Agent SDK, cloud session은 그 창을 띄울 수 없어 서버를 승인 없이 불러옵니다. 자동화나 코드 검토에서 .mcp.json 변경을 일반 설정 변경처럼 넘기면, 이후 실행 환경이 예상하지 못한 서버에 연결할 수 있습니다.

같은 서버 이름이 여러 범위에 있으면 항목을 섞어 합치지 않고 우선순위가 가장 높은 정의 하나만 사용합니다. 순서는 local > project > user > plugin 제공 서버 > claude.ai connector입니다. 팀 설정이 있는데 내 로컬 정의가 다르게 동작한다면 이 우선순위를 먼저 확인합니다.

# 팀이 검토한 서버만 저장소에 공유한다.
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# 대화형 세션에서 project 서버의 승인 선택을 다시 묻도록 한다.
claude mcp reset-project-choices

연결과 인증 확인

claude mcp add는 서버 설정을 추가합니다. 이어서 claude mcp list에서 Connected, Needs authentication, Failed to connect, Pending approval 같은 상태를 보고, 상세 값은 claude mcp get <이름>으로 확인합니다. 세션 안에서는 /mcp로 상태와 OAuth 흐름을 확인할 수 있습니다.

HTTP 서버가 OAuth를 쓴다면 claude mcp login <이름>으로 셸에서 인증할 수 있고, 나중에 claude mcp logout <이름>으로 저장된 인증을 해제합니다. 화면이 없는 SSH 환경에서는 --no-browser를 써서 표시된 URL을 다른 브라우저에서 열고, 완료 URL을 대화형 터미널에 붙여 넣습니다.

추가 직후의 판단
- Connected: 의도한 계정과 도구 목록을 다시 확인한 뒤 사용한다.
- Needs authentication: OAuth 또는 서비스 인증을 마친다.
- Failed to connect: URL, 네트워크, 서비스 쪽 권한과 토큰을 순서대로 확인한다.
- Pending approval: 대화형 Claude Code에서 .mcp.json의 서버와 작업 범위를 검토한다.

MCP 연결 권한과 원격 서비스의 권한은 별개입니다. Claude Code의 승인 정책은 도구 호출을 제어하지만, 서버가 받은 API 토큰의 권한을 줄이지는 않습니다. 따라서 서버가 읽기만 필요하다면 원격 서비스에서도 읽기 전용·최소 저장소·최소 기간 권한의 토큰을 발급해야 합니다.

명령과 prompt

서버는 도구 외에 prompt를 제공할 수 있습니다. 연결된 서버가 공개한 prompt는 / 목록에서 /mcp__서버이름__prompt이름 형식으로 동적으로 나타나며, 매개변수가 있으면 명령 뒤에 전달합니다. prompt가 보인다고 해서 무조건 안전하거나 팀 표준이라는 뜻은 아니므로, 제공 서버와 입력 값, 수행할 외부 작업을 먼저 확인합니다.

/mcp__github__list_prs
/mcp__jira__create_issue "로그인 오류" high

도구와 prompt가 많아질수록 모델이 고를 후보와 사람이 검토할 권한 표면도 늘어납니다. 매일 쓰는 한두 개의 자료원부터 연결하고, 더 이상 사용하지 않는 서버는 claude mcp remove <이름>으로 제거합니다.

자주 틀리는 부분

잘못된 흐름
1. 예제 .mcp.json을 그대로 커밋한다.
2. 인증 토큰을 headers에 직접 넣는다.
3. "Added" 출력만 보고 자동화에서 사용한다.

권장 흐름
1. 서버 URL, 제공 도구, 원격 서비스 권한을 검토한다.
2. 비밀값은 환경 변수·OAuth·자격 증명 저장소로 분리한다.
3. claude mcp list / get과 /mcp에서 실제 상태를 확인한다.
4. project 범위라면 비대화형 실행에서도 허용할 서버인지 다시 검토한다.