Claude Code에 MCP 서버를 붙였는데 이상한 상황이 생겼다.
claude mcp list
→ ✔ Connected분명 연결돼 있다고 나온다.
그런데 현재 세션에서는 그 MCP의 tool이 하나도 보이지 않는다.
처음에는 보통 이렇게 생각한다.
등록이 잘못됐나?
서버가 안 뜬 건가?
다시 설치해야 하나?
하지만 이런 식으로 접근하면 재설치와 설정 초기화를 반복하게 된다. 문제를 더 정확하게 보면 “서버 연결”과 “현재 세션의 도구 노출”은 다른 계층이다.
이 글은 이 둘을 분리해서 진단하는 방법을 정리한 것이다.
문제의 핵심: Connected ≠ Exposed
AI 개발도구에서는 다음 세 상태를 구분해야 한다.
Installed
↓
Connected
↓
Exposed to current sessionInstalled는 프로그램이 존재한다는 뜻이다.
Connected는 MCP 서버 프로세스와 Claude Code가 연결됐다는 뜻이다.
Exposed to current session은 현재 대화 세션이 그 서버의 tool schema를 실제로 사용할 수 있다는 뜻이다.
셋은 비슷해 보이지만 전혀 다르다.
1. 먼저 서버 연결부터 확인한다
가장 먼저 확인할 명령은 단순하다.
claude mcp list여기서 해당 서버가 Connected라면 최소한 다음 가설은 우선순위가 내려간다.
- MCP 등록 자체 실패
- 서버 실행 경로 오타
- 프로세스 시작 실패
- 기본 연결 실패
즉 “아무것도 연결되지 않았다”는 상태는 아니다.
2. 세션 안에서 /mcp 를 연다
여기서 가장 흔한 실수는 도구 목록이 비어 보인다는 것만으로 “서버에 없다”로 건너뛰는 것이다. 도구 목록은 현재 세션이 알고 있는 것을 보여줄 뿐, 서버가 무엇을 제공하는지와는 별개다.
둘을 한 화면에서 비교할 수 있다. 세션 안에서 /mcp 를 치면 서버마다 이렇게 나온다.
서버 상태 ✔ Connected / ! Needs authentication / ✘ Failed to connect
tool 개수 연결된 서버가 몇 개를 제공하는지여기서 갈린다.
- tool 개수가 0이 아닌데 세션에서 안 보인다 → 노출 문제다. 3절로 간다
! Needs authentication→ 서버가 아니라 인증이 끊긴 것이다. 그 자리에서 로그인하면 끝난다✘ Failed to connect→claude mcp list가Connected로 나왔더라도 지금 이 세션은 붙지 못한 것이다
/mcp 화면에는 Reconnect 도 있다. 세션을 버리기 전에 눌러 볼 것이 하나 있다는 뜻이다.
3. 서버를 직접 띄워 본다
/mcp 에서도 서버 쪽이 의심스러우면 서버 실행 명령을 직접 돌려 본다.
<server-command> <server-args>여기서 확인할 것은 기동 여부지 도구 목록이 아니다.
- 프로세스가 정상 시작되는가
- 프로젝트를 정상 감지하는가
- backend가 초기화되는가
- startup 중 예외가 없는가
stdio 서버는 맨손으로 띄우면 표준 입력을 기다리며 멈춰 있을 뿐 도구 목록을 찍지 않는다. 목록 자체를 보려면 MCP inspector 같은 클라이언트가 필요하다. 이 단계에서 예외 없이 올라온다면 서버 자체는 살아 있다.
4. 서버는 정상인데 세션에서만 안 보인다면?
이제 상태는 다음처럼 좁혀진다.
Server: 정상
MCP connection: 정상
Current session tool exposure: 비정상이 경우에는 문제를 이렇게 표현하는 편이 정확하다.
MCP는 연결돼 있지만 현재 세션에 tool이 노출되지 않았다.
이 문장이 중요한 이유는 문제 해결 방향이 완전히 달라지기 때문이다.
“서버가 없다”고 생각하면 재설치를 하게 된다.
“세션에 노출되지 않았다”고 보면 세션 lifecycle과 registry 갱신 문제를 본다.
5. 왜 세션 문제일 수 있나
MCP나 plugin을 현재 세션이 시작된 뒤 추가하면 기존 세션이 새로운 tool registry를 반영하지 못할 수 있다.
이 경우 서버는 정상이어도 기존 세션은 계속 과거 상태를 유지할 수 있다.
그러면 다음과 같은 모순이 생긴다.
터미널에서는 서버 정상
claude mcp list에서도 Connected
하지만 대화 세션에는 tool 없음이 조합은 충분히 가능하다.
6. 새 세션으로 넘어가기 전에 할 일
장시간 작업 중인 세션이라면 MCP 하나 때문에 바로 끊을 필요는 없다. 세션을 버리는 것은 가장 비싼 처방이고, 그 앞에 두 단계가 있다.
/mcp 에서 Reconnect
↓
(안 되면) 현재 작업 마무리
↓
checkpoint / handoff
↓
새 세션 시작
↓
MCP tool 노출 확인
↓
read-only 호출앞의 두 단계로 끝나는 경우가 꽤 있다. 핸드오프 문서를 쓰는 비용은 그 뒤에 치른다.
handoff에는 최소한 다음을 남긴다.
- 현재 작업 상태
- 완료 항목
- 미완료 항목
- 테스트 상태
- 주요 가설
- 다음 세션 첫 검증 항목
7. 새 세션에서의 검증 기준
새 세션에서는 복잡하게 볼 필요가 없다.
다음 세 가지만 확인하면 된다.
1. /mcp 에서 tool 개수가 0이 아닌가
2. read-only tool을 실제 호출할 수 있는가
3. 결과가 정상 반환되는가세 개가 모두 성공하면 그때 AVAILABLE로 판단한다.
단순히 Connected라고 나오는 것만으로는 부족하다.
8. 이 문제에서 가장 위험한 추론
가장 위험한 패턴은 이것이다.
현재 세션에서 안 보임
→ 서버에 없음이 둘은 같지 않다.
더 정확하게는 이렇게 구분해야 한다.
Not observed in current session
≠
Not available on server이 구분은 MCP뿐 아니라 plugin, runtime capability, agent tool registry 문제를 볼 때도 그대로 적용된다.
재발 시 체크리스트
비슷한 문제가 생기면 아래 순서로 확인하면 된다.
[ ] 설치 여부 확인
[ ] claude mcp list ← 서버가 붙기는 하는가
[ ] /mcp ← 이 세션이 보는 상태와 tool 개수
[ ] /mcp 에서 인증 상태 확인
[ ] /mcp 에서 Reconnect
[ ] 서버 직접 기동 (기동 예외만 확인)
[ ] 세션 시작 이후 MCP 추가 여부 확인
[ ] 새 세션 재검증위에서 아래로 갈수록 비싸다. 위에서 끝나면 아래는 안 해도 된다.
결론
MCP 문제를 해결할 때 가장 중요한 것은 “없다”라고 너무 빨리 결론내리지 않는 것이다.
AI 개발환경에서는:
설치
연결
현재 세션 노출이 세 계층이 분리돼 있다.
이 차이를 이해하면 “재설치해도 해결되지 않는 문제”를 훨씬 빠르게 진단할 수 있다.
공식 문서 참고
- Claude Code MCP: https://code.claude.com/docs/en/mcp —
/mcp화면이 보여주는 상태값과 Reconnect 동작은 여기에 있다.