Troubleshooting

If you encounter a problem while connecting to or using the MCP server, check the items below.

"WHATAP_API_TOKEN environment variable is required"

The API token is not configured or not being passed to the MCP server.

Check the following items in each client's configuration file.

• Claude Desktop: Verify the "env" block contains the "WHATAP_API_TOKEN" key (not "WHATAP_TOKEN")
• Codex CLI: Verify the [mcp_servers.whatap.env] section exists in the TOML file
• Gemini CLI: Verify the "env" block exists in settings.json
• Claude Code: Verify the -env flag is included in the claude mcp add command

"No API token found for project XXXXX"

The account token is valid, but the project code does not exist or you do not have access.

Enter "Show me my project list" in the AI assistant to confirm the correct project code.

"npx: command not found"

Node.js is not installed or not registered in PATH.

Install Node.js 18 or higher.

node --version   # Check for v18 or higher
npx --version    # Check that a version is printed

"spawn git ENOENT" or "An unknown git error occurred"

Git is not installed or its executable path is not registered in PATH.

The WhaTap MCP server references a GitHub repository directly, so it requires Git. This error occurs mainly on Windows.

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

After installation, open a new terminal and run the following command.

git --version   # Check that a version is printed

For more details, refer to the Getting Started > Install Git document.

MCP server fails to start or times out

The MCP server does not start or a timeout occurs.

Run the server directly to check for error messages.

WHATAP_API_TOKEN=your_token_here npx -y github:whatap/whatap-open-mcp

If the server starts normally, it will wait for input. Press Ctrl+C to stop. If error messages appear, check the token value or Node.js version.

Tools not appearing in Claude Desktop

MCP tools are not displayed in Claude Desktop.

Check the following items in order.

1. Verify the JSON file is valid (missing commas, mismatched brackets, etc.).

2. Fully quit and restart Claude Desktop (quit the app, do not just close the window).

3. Check the logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Tools not appearing in Codex CLI

MCP tools are not displayed in Codex CLI.

Check the following items in order.

1. Verify registration with codex mcp list.

2. Verify ~/.codex/config.toml is in valid TOML format (JSON syntax is not supported).

3. Remove and re-register: codex mcp add whatap ...

Tools not appearing in Gemini CLI

MCP tools are not displayed in Gemini CLI.

Check the following items in order.

1. Verify registration with gemini mcp list.

2. Verify ~/.gemini/settings.json is valid JSON.

3. Check the scope: -scope user (global) or -scope project (project-level)

"WhaTap API error (401)" or "(403)"

The API token is invalid or has expired.

Go to Account Management > API Token in WhaTap Console to issue a new token.

Slow responses

Responses are slow.

Reduce the query time range. "5m" (5 minutes) takes a few seconds, while "1d" (1 day) may take tens of seconds. Consecutive requests may hit WhaTap API rate limits. Wait a moment and try again.

No data returned

No data is returned.

Refer to the causes and remedies below.

Cause	How to check
Project type mismatch (e.g. APM query on a Server project)	Run whatap_data_availability(projectCode) to check active categories → "Show me what data I can query in this project"
Agent not installed or inactive	Run whatap_list_agents(projectCode) to check agent status → "Show me the agent list"
Time range too narrow	Expand the range (e.g. timeRange="1h") and retry