Troubleshooting

​

Server doesn’t appear in Claude Desktop

1. 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
   
2. 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
   
3. 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.

​

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" }
      }
    }
  }
  
• 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": "V1 supports US coordinates only; received lat=40.7, lng=-0.1"
  }
}

​

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).

​

HTTP 502 ask_answer_incomplete

{
  "detail": {
    "error": "ask_answer_incomplete",
    "message": "The synthesizer returned an incomplete answer, so there is nothing usable to serve. Retry the request — this failure is stochastic and the same question usually succeeds on the next attempt.",
    "retryable": true
  }
}

​

HTTP 422 ask_question_refused

{
  "detail": {
    "error": "ask_question_refused",
    "message": "The model declined to answer this question, so there is nothing to serve. This is deterministic for the same input — retrying it unchanged will not succeed. Rephrase the question.",
    "retryable": false
  }
}

​

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