본문으로 건너뛰기

문제 해결

MCP 서버 연결 또는 사용 중 문제가 발생하면 아래 항목을 확인하세요.

"WHATAP_API_TOKEN environment variable is required"​

API 토큰이 설정되지 않았거나 MCP 서버에 전달되지 않습니다.

각 클라이언트의 설정 파일에서 다음 항목을 확인하세요.

  • Claude Desktop: "env" 블록에 "WHATAP_API_TOKEN" 키가 있는지 확인 ("WHATAP_TOKEN" 아님)
  • Codex CLI: [mcp_servers.whatap.env] 섹션이 TOML 파일에 있는지 확인
  • Gemini CLI: "env" 블록이 settings.json에 있는지 확인
  • Claude Code: claude mcp add 명령에 -env 플래그가 포함되어 있는지 확인

"No API token found for project XXXXX"​

계정 토큰은 유효하지만, 해당 프로젝트 코드가 존재하지 않거나 접근 권한이 없습니다.

AI 어시스턴트에 "내 프로젝트 목록 보여줘"라고 입력하여 정확한 프로젝트 코드를 확인하세요.

"npx: command not found"​

Node.js가 설치되어 있지 않거나 PATH에 등록되지 않습니다.

Node.js 18 이상을 설치하세요.

node --version   # v18 이상 확인
npx --version    # 버전 출력 확인

"spawn git ENOENT" 또는 "An unknown git error occurred"​

Git이 설치되어 있지 않거나 실행 경로가 PATH에 등록되지 않습니다.

WhaTap MCP 서버는 GitHub 저장소를 직접 참조하므로 Git이 필요합니다. 이 오류는 주로 Windows 환경에서 발생합니다.

winget install --id Git.Git -e --source winget

설치 후 터미널을 새로 열고 아래 명령어를 실행하세요.

git --version   # 버전 출력 확인

자세한 절차는 시작하기 > Git 설치하기 문서를 참고하세요.

MCP 서버가 시작되지 않거나 타임아웃 발생​

MCP 서버가 시작되지 않거나 타임아웃이 발생합니다.

서버를 직접 실행하여 오류 메시지를 확인하세요.

WHATAP_API_TOKEN=여기에_토큰_입력 npx -y github:whatap/whatap-open-mcp

서버가 정상 실행되면 입력 대기 상태가 됩니다. Ctrl+C로 종료하세요. 오류 메시지가 출력되면 토큰 값 또는 Node.js 버전을 확인하세요.

Claude Desktop에서 도구가 나타나지 않는 경우​

Claude Desktop에서 MCP 도구가 표시되지 않습니다.

다음 항목을 순서대로 확인하세요.

  1. JSON 파일이 유효한지 확인합니다(쉼표 누락, 괄호 불일치 등).

  2. Claude Desktop을 완전히 종료 후 재시작합니다(창 닫기가 아닌 앱 종료).

  3. 로그를 확인합니다. ~/Library/Logs/Claude/mcp*.log (macOS)

Codex CLI에서 도구가 나타나지 않는 경우​

Codex CLI에서 MCP 도구가 표시되지 않습니다.

다음 항목을 순서대로 확인하세요.

  1. codex mcp list로 등록 여부를 확인합니다.

  2. ~/.codex/config.toml이 올바른 TOML 형식인지 확인합니다(JSON 문법 사용 불가).

  3. 삭제 후 재등록합니다. codex mcp add whatap ...

Gemini CLI에서 도구가 나타나지 않는 경우​

Gemini CLI에서 MCP 도구가 표시되지 않습니다.

다음 항목을 순서대로 확인하세요.

  1. gemini mcp list로 등록 여부를 확인합니다.

  2. ~/.gemini/settings.json이 올바른 JSON 형식인지 확인합니다.

  3. 적용 범위를 확인합니다. -scope user(전체) 또는 -scope project(프로젝트)

"WhaTap API error (401)" 또는 "(403)"​

API 토큰이 유효하지 않거나 만료되었습니다.

WhaTap Console에서 계정 관리 > API 토큰으로 이동하여 새 토큰을 발급하세요.

응답이 느린 경우​

응답이 느려요.

조회 시간 범위를 줄이세요. "5m"(5분)이면 수 초, "1d"(1일)이면 수십 초 걸릴 수 있습니다. 연속 요청 시 WhaTap API 속도 제한에 걸릴 수 있습니다. 잠시 후 다시 시도하세요.

데이터가 조회되지 않는 경우​

데이터가 조회되지 않습니다.

원인과 확인 방법을 참고하세요.

원인확인 방법
프로젝트 유형 불일치 (예: Server 프로젝트에 APM 쿼리)whatap_data_availability(projectCode)로 활성 카테고리 확인 → "이 프로젝트에서 조회 가능한 데이터 보여줘"
에이전트 미설치 또는 비활성whatap_list_agents(projectCode)로 에이전트 상태 확인 → "에이전트 목록 보여줘"
시간 범위가 너무 좁음timeRange="1h" 등 범위 확대 후 재시도
최종 수정: