> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

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

## Server doesn't appear in Claude Desktop

Symptom: you added `mireye-earth` to `claude_desktop_config.json` and
restarted, but the 🔌 menu shows no Mireye entry, or it's red.

1. **Validate the config JSON.** A trailing comma or unbalanced brace
   silently disables all MCP servers.

   ```bash theme={null}
   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:

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

   Don't have `uv` at all? Install it:

   ```bash theme={null}
   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

Symptom: server is connected (green dot) but no tools show.

* **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 hosted API keeps its machines running, but the first calls right
after a backend deploy can be slow while geospatial sources warm in the
background, and a handful of fields depend on slow upstream federal
services at the best of times.

* **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:

  ```json theme={null}
  {
    "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`

Mireye is US-only in V1. Accepted envelope:

| Bound     | Value  |
| --------- | ------ |
| `lat_min` | 18.0   |
| `lat_max` | 72.0   |
| `lng_min` | -180.0 |
| `lng_max` | -65.0  |

This covers the lower 48, Alaska, Hawaii, and US territories. Coordinates
outside this envelope return:

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

If your caller might pass non-US coordinates, validate client-side first.

## HTTP 400 `fields_unknown`

A requested field name is not in the catalog. The response lists exactly
which names failed:

```json theme={null}
{
  "detail": {
    "error": "fields_unknown",
    "message": "Unknown field names: ['elevation_m']",
    "fields_unknown": ["elevation_m"]
  }
}
```

Common renames (see also [/api-reference/errors](/api-reference/errors#fields_unknown)):

* `elevation_m` → `elevation`
* `slope` → `slope_degrees`
* `floodplain` → `within_floodplain_polygon`
* `power_plant` → `nearest_power_plant_name`

The canonical list lives at
[`/v1/meta/fields`](https://api.mireye.com/v1/meta/fields).

## HTTP 400 `fields_too_many`

You requested more than 50 fields (after preset expansion). Two paths:

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

## `401` / `403` errors

For the local stdio adapter, `401` means the MCP server did not send a
valid bearer token. Run `mireye-mcp login`, or set
`MIREYE_BEARER_TOKEN` in your MCP config. `403` means the signed-in
account failed backend policy, such as a non-Google provider or
unverified email.

Two adapter-side errors look similar but never reach the API:

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

For the hosted remote endpoint (`https://api.mireye.com/mcp`),
`401` should include a `WWW-Authenticate` header pointing at the OAuth
protected-resource metadata. If your client does not open an OAuth
browser flow after that challenge, confirm it supports remote MCP
authorization over Streamable HTTP.

## Unexplained `500`s

These are bugs. Include the `X-Request-ID` when reporting (structured
errors carry it; plain unhandled 500s don't — include the timestamp and
tool name instead). The MCP server logs each tool call to stderr with
the request ID:

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

Grab that and email [ansh@mireye.earth](mailto:ansh@mireye.earth).

## Server keeps restarting

Claude Desktop will respawn the MCP server if the process exits
unexpectedly. If you see flapping (the server going green/red
repeatedly), check stderr — most often it's a Python crash on import.
Run the binary directly:

```bash theme={null}
uvx mireye-mcp
# should hang waiting on stdin; ctrl-c to exit
```

Any traceback printed before it hangs is the real error.