Troubleshooting

Common failures wiring up the MCP server, and how to fix them.

​ Server doesn’t appear in Claude Desktop

• Validate the config JSON. A trailing comma or unbalanced brace silently disables all MCP servers. python -c "import json,sys; json.load(open(sys.argv[1]))" \ ~/Library/Application\ Support/Claude/claude_desktop_config.json

python -c "import json,sys; json.load(open(sys.argv[1]))" \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json

• Confirm uvx is on PATH. macOS launches GUI apps with a minimal PATH (no shell profile loaded). If which uvx prints ~/.local/bin/uvx, that path may not be visible to Claude. Use the absolute path in your config: { "mcpServers": { "mireye-earth": { "command": "/Users/you/.local/bin/uvx", "args": ["mireye-mcp"] } } } Don’t have uv at all? Install it: curl -LsSf https://astral.sh/uv/install.sh | sh

{
  "mcpServers": {
    "mireye-earth": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["mireye-mcp"]
    }
  }
}

• Check the Claude logs. Logs live at ~/Library/Logs/Claude/mcp-server-mireye-earth.log. On startup you should see one line: [mireye-mcp] starting base_url=https://api.mireye.com timeout_s=120.0 If you see a Python ImportError, mireye-mcp was launched against an interpreter that doesn’t have the mcp SDK installed. With uvx, this shouldn’t happen — uvx provisions a managed environment per call. If you switched to plain pip, make sure pip show mcp returns >= 1.27.2 in the same interpreter the binary lives in.

[mireye-mcp] starting base_url=https://api.mireye.com timeout_s=120.0

​ Tools not appearing in the picker

• Old mcp SDK. The package pins mcp >= 1.27.2, < 2.0. If you installed an older version manually, upgrade: pip install --upgrade 'mcp>=1.27.2,<2.0'.
• Import failure. Run uvx mireye-mcp from a terminal. It should sit silently waiting for stdio input — anything printed to stderr beyond the starting … line is a real error.

​ ConnectError / ReadTimeout on the first call

• The default already covers this. MIREYE_TIMEOUT_S defaults to 120 s, above the server’s ~110 s /v1/ask deadline, so a cold start completes within it. Only raise it further (never set it below 120 — that would abandon requests the server still completes) if you still time out: { "mcpServers": { "mireye-earth": { "command": "uvx", "args": ["mireye-mcp"], "env": { "MIREYE_TIMEOUT_S": "180" } } } }

{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"],
      "env": { "MIREYE_TIMEOUT_S": "180" }
    }
  }
}

• Pre-warm with a cheap call. Hit https://api.mireye.com/healthz before your first user-facing call (e.g. in your agent’s session-start hook).

​ HTTP 400 coord_out_of_bounds

{
  "detail": {
    "error": "coord_out_of_bounds",
    "message": "lng=-0.1 outside US envelope [-180.0, -65.0]"
  }
}

​ HTTP 400 fields_unknown

{
  "detail": {
    "error": "fields_unknown",
    "message": "Unknown field names: ['elevation_m']",
    "fields_unknown": ["elevation_m"]
  }
}

• elevation_m → elevation
• slope → slope_degrees
• floodplain → within_floodplain_polygon
• power_plant → nearest_power_plant_name

​ HTTP 400 fields_too_many

• Drop the preset and pick fields explicitly.
• Split into multiple fetch calls (e.g. one per layer).

​ 401 / 403 errors

• Stored credentials bound to a different URL. Stored logins only attach to the MIREYE_BASE_URL they were created against. If you changed MIREYE_BASE_URL after logging in, tool calls behave as logged out and the error names both the stored and the active URL. Re-run mireye-mcp login against the new URL, or set MIREYE_BEARER_TOKEN.
• insecure_base_url. Tokens are never sent over plain http:// except to loopback hosts (localhost / 127.0.0.1 / [::1]). login also refuses to run against a remote plain-http URL. Use https for any non-local deployment.

​ Unexplained 500s

[mireye-mcp] tool_call path=/v1/ask status=500 request_id=req_a1b2c3d4e5f6

​ Server keeps restarting

uvx mireye-mcp
# should hang waiting on stdin; ctrl-c to exit