Quickstart - Mireye Earth

This walkthrough makes three real API calls. No SDK, no install — just curl, jq, and a Mireye API token. We’ll ask about a Manhattan rooftop, fetch the same location’s flood-risk preset, and then wire up the hosted MCP server for Claude Code.

1. Pick a coordinate

Use any US lat/lng. We’ll use the corner of Beekman and Park Row in lower Manhattan, near City Hall:

lat = 40.7128
lng = -74.0060

The accepted coordinate envelope is lat ∈ [18, 72], lng ∈ [-180, -65] (lower 48, Alaska, Hawaii, US territories). Anything outside returns 400 coord_out_of_bounds.

2. Get a token

/v1/ask and /v1/fetch require a bearer token. Sign in at www.mireye.com, create an API token in account settings, and export it:

export MIREYE_API_TOKEN="<paste from dashboard>"

See Authentication for the other credential paths (device-flow login for the local MCP adapter, OAuth for the hosted MCP endpoint).

3. Ask a question

curl -s https://api.mireye.com/v1/ask \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "question": "What is the elevation here?"
  }' | jq

Response:

{
  "lat": 40.7128,
  "lng": -74.006,
  "question": "What is the elevation here?",
  "answered_at": "2026-06-12T07:29:37.353451+00:00",
  "answer": "The ground elevation at coordinate 40.7128, -74.006 is 13.15 meters above sea level (NAVD88 datum), per USGS 3DEP/EPQS at ~10m resolution. This elevation is above the 10-meter storm-surge exposure threshold, though proximity to the coast would warrant further review in conjunction with flood zone and coastal distance data for a complete flood-risk assessment.",
  "confidence": "high",
  "citations": [
    {
      "source": "USGS_EPQS",
      "source_url": "https://epqs.nationalmap.gov/v1/json?x=-74.006&y=40.7128&wkid=4326&units=Meters",
      "fields": [
        "elevation"
      ],
      "fetched_at": "2026-06-12T07:29:40.330095+00:00",
      "confidence": "high"
    }
  ],
  "fields_used": [
    "elevation"
  ]
}

What just happened:

The planner (Claude Sonnet 4.6) read the question, looked at the field catalog, and decided only elevation was needed.
The terrain layer fetched 3DEP elevation for the coordinate.
The synthesizer (also Claude Sonnet 4.6) wrote the prose answer, grounded in the fetched value, and the citation engine attached the source.

Read the fields top-to-bottom: answer is the prose, confidence summarizes the whole response, citations is the audit trail, and fields_used lists exactly which catalog fields the answer depends on.

4. Fetch raw fields

When you know what you want, skip the planner and hit /v1/fetch:

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "fields": ["elevation", "coast_distance_m"]
  }' | jq

Response:

{
  "lat": 40.7128,
  "lng": -74.006,
  "fetched_at": "2026-06-12T07:27:35.840477+00:00",
  "fields": {
    "elevation": {
      "value": 13.150006294,
      "unit": "meters",
      "source": "USGS_EPQS",
      "source_url": "https://epqs.nationalmap.gov/v1/json?x=-74.006&y=40.7128&wkid=4326&units=Meters",
      "confidence": "high",
      "fetched_at": "2026-06-12T07:27:35.826959+00:00",
      "dataset_vintage": "3DEP dynamic service",
      "ttl_seconds": 31536000,
      "notes": null
    },
    "coast_distance_m": {
      "value": 764.2256402243065,
      "unit": "meters",
      "source": "NOAA_CUSP",
      "source_url": "https://shoreline.noaa.gov/data/datasheets/cusp.html",
      "confidence": "high",
      "fetched_at": "2026-06-12T07:27:35.839783+00:00",
      "dataset_vintage": null,
      "ttl_seconds": 31536000,
      "notes": null
    }
  },
  "partial_failures": []
}

Each field is a self-contained record with provenance inline. The partial_failures array is empty here; on a call where the LCMS source times out, that field gets moved to partial_failures with retryable: true and the rest of the call still returns 200. Skip the field list entirely and use a preset for common workflows:

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 40.7128, "lng": -74.0060, "preset": "flood_risk"}' | jq '.fields | keys'

[
  "coast_distance_m",
  "elevation",
  "intersects_nhd_area",
  "intersects_wetland",
  "nearest_waterbody_name",
  "nearest_wetland_distance_m",
  "surface_water_permanence_pct",
  "wetland_acres",
  "wetland_subtype",
  "wetland_type",
  "wetlands_within_100m_count",
  "wetlands_within_500m_count",
  "within_floodplain_polygon"
]

All presets and their field expansions are listed at /api-reference/fetch.

5. Use it from Claude Code

If you previously configured a local stdio server named mireye-earth, remove it first:

claude mcp remove mireye-earth -s user

Add the hosted MCP endpoint:

claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp

Restart Claude Code, run /mcp, and complete the browser sign-in flow. Two tools are then available: mireye_ask and mireye_fetch. Ask Claude:

“What’s the elevation at 40.7128, -74.0060?”

Claude will call mireye_ask, get the cited answer back, and surface the citation in chat. See /mcp/installation for Cursor and custom-agent setup.

6. Self-discover the catalog

Long-lived clients (agents, services) should fetch the catalog once at startup and cache it for an hour. This endpoint is public — no token needed:

curl -i https://api.mireye.com/v1/meta/fields | head -20

The response sets ETag and Cache-Control: public, max-age=3600. Subsequent requests with If-None-Match: "<etag>" return 304. See /api-reference/meta-fields for the full flow.

What’s next

POST /v1/ask

The natural-language endpoint. Two-model planner + synthesizer.

POST /v1/fetch

Fields, presets, and partial_failures semantics.

MCP tools

mireye_ask vs mireye_fetch from an agent’s perspective.

Insurance use case

A worked underwriting flow with real values.

​1. Pick a coordinate

​2. Get a token

​3. Ask a question

​4. Fetch raw fields

​5. Use it from Claude Code

​6. Self-discover the catalog

​What’s next