2dayapp
분류
Engineering
작성일
읽는 시간
3분

MCP는 연결됐는데 도구가 안 보일 때

Claude Code의 /mcp에는 Connected로 나오지만 도구를 사용할 수 없을 때, 도구 수와 디버그 로그로 연결 문제와 노출 문제를 구분합니다.

English version available

Claude Code에서 claude mcp list를 실행하면 서버가 Connected로 나오는데, 대화에서는 도구를 찾지 못할 때가 있습니다. Connected는 서버 연결 단계를 통과했다는 뜻입니다. 도구 목록까지 정상적으로 받았다는 보장은 없습니다.

먼저 어떤 증상인지 나눠야 합니다.

  1. /mcp에서 도구가 0개로 나옵니다.
  2. /mcp에는 도구가 있지만 Claude가 사용하지 않습니다.
  3. Claude가 도구를 찾았지만 호출 승인이 나지 않습니다.

첫 번째는 서버나 도구 목록의 문제이고, 두 번째는 Tool Search 또는 실행 환경의 문제일 수 있습니다. 세 번째는 도구 노출이 아니라 권한 문제입니다.

/mcp에서 도구 수를 확인한다

Claude Code 안에서 다음 명령을 실행합니다.

/mcp

2026년 7월 Claude Code 문서 기준으로 /mcp 패널은 연결된 서버 옆에 도구 수를 표시합니다. 서버가 도구 기능을 알렸지만 실제 도구를 하나도 노출하지 않으면 경고도 표시합니다.

/mcp 상태 의미 다음 확인
연결 실패 서버 프로세스나 네트워크 단계의 문제 실행 명령, URL, 인증, 로그
Connected, 도구 0개 연결은 됐지만 도구 목록을 받지 못함 재연결 후 디버그 로그
Connected, 도구 1개 이상 도구 목록은 받음 Tool Search와 실행 환경
Pending 연결 또는 재연결 중 잠시 기다린 뒤 상태 재확인

도구가 0개라면 프롬프트를 바꿔도 해결되지 않습니다. Claude에게 노출되지 않은 도구는 호출할 수 없습니다.

도구가 0개면 서버 쪽 응답을 본다

Claude Code의 설정 디버깅 문서는 Connected 상태에서 도구가 0개라면 /mcp에서 Reconnect를 실행하도록 안내합니다. 다시 연결해도 0개라면 디버그 로그를 확인합니다.

claude --debug mcp

로그에서는 다음 문제를 찾습니다.

MCP의 stdio 전송 규격에 따르면 서버는 JSON-RPC 메시지를 표준 출력으로 보내야 하며, 그 밖의 내용을 표준 출력에 쓰면 안 됩니다. 일반 로그는 표준 오류에 기록할 수 있습니다. 서버가 console.log 같은 출력을 프로토콜 메시지와 섞으면 연결이나 도구 목록 처리가 깨질 수 있습니다.

프로젝트 MCP가 승인됐는지 확인한다

프로젝트의 .mcp.json에 정의된 서버는 처음 사용할 때 승인이 필요합니다. 승인 창을 닫았다면 설정 파일이 있어도 서버가 비활성 상태로 남을 수 있습니다.

/mcp에서 해당 서버를 선택해 승인 상태를 확인합니다. 팀 저장소에서 .mcp.json을 받아왔더라도 승인은 사용자 환경마다 별도로 처리됩니다.

서버가 어느 범위에 등록됐는지는 다음 명령으로 확인할 수 있습니다.

claude mcp list
claude mcp get <server-name>

상대 경로와 실행 환경을 확인한다

Claude Code 공식 문서는 .mcp.json의 command와 args에 사용한 상대 경로를 흔한 실패 원인으로 설명합니다. 상대 경로는 설정 파일의 위치가 아니라 Claude Code를 실행한 디렉터리를 기준으로 해석될 수 있습니다.

프로젝트 안의 실행 파일을 가리킨다면 ${CLAUDE_PROJECT_DIR}를 사용할 수 있습니다.

{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/tools/mcp-server.js"]
    }
  }
}

실행 파일을 찾지 못하면 spawn ... ENOENT 오류가 나타날 수 있습니다. 터미널에서 직접 실행할 때만 동작한다면 Claude Code 프로세스의 PATH와 서버에 전달되는 환경 변수도 확인해야 합니다.

도구가 있는데 Claude가 사용하지 않는 경우

/mcp에 도구가 1개 이상 표시된다면 서버에서 도구 목록은 받은 상태입니다. 이후에는 “도구가 보이지 않는다”기보다 Claude가 현재 요청에서 도구를 찾거나 선택하지 않는 문제에 가깝습니다.

현재 Claude Code는 기본적으로 MCP Tool Search를 사용합니다. 세션 시작 시 모든 도구의 전체 스키마를 컨텍스트에 넣지 않고, 도구 이름만 불러온 뒤 필요한 도구를 검색합니다. MCP가 많을 때 컨텍스트 사용량을 줄이기 위한 동작입니다.

도구가 해결할 작업과 사용할 서버를 구체적으로 적어 다시 확인할 수 있습니다.

GitHub MCP를 사용해서 이 저장소의 열린 이슈를 조회해줘.
필요한 MCP 도구를 먼저 찾아서 사용해줘.

Claude Code의 MCP 문서에 따르면 Tool Search는 Sonnet 4 이상과 Opus 4 이상에서 지원되며 Haiku는 지원하지 않습니다. Vertex AI, 비공식 API 프록시, ENABLE_TOOL_SEARCH 설정에 따라 동작이 달라질 수도 있습니다.

플러그인을 켜거나 끈 직후부터 MCP 도구가 사라졌다면 /reload-plugins로 현재 세션의 플러그인을 다시 불러올 수 있습니다.

도구를 찾았지만 호출할 수 없는 경우

Claude가 MCP 도구 이름을 제시하거나 호출 승인을 요청한다면 도구 목록 문제는 아닙니다. 이때는 권한 설정이나 사용자의 승인 여부를 확인해야 합니다.

도구의 일반적인 이름은 다음과 같습니다.

mcp__<server-name>__<tool-name>

권한 규칙에서 서버 이름이나 도구 이름을 잘못 적으면 호출이 거부될 수 있습니다. 연결 설정을 다시 만드는 대신 표시된 도구 이름과 권한 규칙이 일치하는지 확인합니다.

결론

Connected만으로 MCP 도구가 정상이라고 판단할 수는 없습니다. /mcp에서 도구 수를 확인하면 연결 문제와 도구 노출 문제를 먼저 나눌 수 있습니다.

도구가 0개라면 Reconnect와 claude --debug mcp로 서버 응답을 확인합니다. 도구가 있다면 Tool Search와 실행 환경을 확인하고, 도구를 찾았지만 호출하지 못한다면 권한 설정을 확인합니다.

참고 자료