> ## 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. # Install > Wire Mireye Earth into Claude Desktop, Claude Code, Cursor, or a custom MCP agent. Mireye serves a hosted OAuth-protected MCP endpoint at `https://api.mireye.com/mcp`. Use this remote HTTP endpoint for Claude Code so `/mcp` can open the browser sign-in flow and Claude Code can store and refresh OAuth credentials for you. Mireye also ships a local stdio adapter (`mireye-mcp`) for Claude Desktop, Cursor, and custom agents that do not use hosted HTTP MCP. Local stdio does not launch Claude's native OAuth flow; it requires `mireye-mcp login` or `MIREYE_BEARER_TOKEN`. Both distributions ship under the MCP server name **`com.mireye/earth`**. Publication to the [Official MCP Registry](https://registry.modelcontextprotocol.io) is in flight — until the entry is live, use the manual setup below (it is the same config either way). ## Claude Code — hosted OAuth If you previously configured the local stdio adapter under the same name, remove it first: ```bash theme={null} claude mcp remove mireye-earth -s user ``` Then add the hosted MCP endpoint: ```bash theme={null} claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp ``` Restart any running Claude Code session, then run `/mcp` and follow the browser login flow. After authentication, both tools (`mireye_ask`, `mireye_fetch`) are available for natural chat and tool calls. Catalog resources and workflow prompts are also available to clients that surface those MCP primitives. Matching slash commands also appear: * `/mcp__mireye-earth__mireye_ask ` * `/mcp__mireye-earth__mireye_fetch [fields] [preset]` (The `/mcp____` format is Claude Code's slash-command convention for MCP prompts — it isn't customizable.) ## Local stdio adapter — fallback Use the local adapter when your MCP client does not support remote HTTP OAuth, or when you need a local stdio process. It exposes the same two tools, catalog resources, and prompts, and ships as its own slim PyPI package: two runtime dependencies (`httpx` + `mcp`), no native builds, no GDAL. Install with `uvx`: ```bash theme={null} uvx mireye-mcp ``` > The six siting presets (catalog 0.6.0) and the credential URL-binding > behavior described on this page require `mireye-mcp >= 0.2.0`. > If `pip index versions mireye-mcp` returns nothing yet, the > release is in flight — use the hosted endpoint until it lands. `uvx` (bundled with [`uv`](https://docs.astral.sh/uv/)) downloads the package on first run, caches it, and the next invocation is instant. No venv to manage. Don't have `uv`? ```bash theme={null} curl -LsSf https://astral.sh/uv/install.sh | sh ``` Plain pip works too: ```bash theme={null} pip install 'mireye-mcp>=0.2.0' ``` This installs the `mireye-mcp` console entry point. Verify: ```bash theme={null} which mireye-mcp # /Users/you/.local/bin/mireye-mcp (or similar) ``` ## Claude Desktop Edit the Claude Desktop config: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` Add `mireye-earth` to `mcpServers`: ```json theme={null} { "mcpServers": { "mireye-earth": { "command": "uvx", "args": ["mireye-mcp"] } } } ``` After running `mireye-mcp login` or setting `MIREYE_BEARER_TOKEN`, restart Claude Desktop. Two tools — `mireye_ask` and `mireye_fetch` — appear in the 🔌 menu, with catalog resources and workflow prompts available to clients that expose them. Click through to confirm both tools are green; then start a new chat and ask: > What's the elevation at 40.7128, -74.0060? Claude calls `mireye_ask`, returns the cited answer. ### `uvx` not on PATH? macOS launches GUI apps with a minimal PATH (no shell profile loaded). If your `uv` install lives at `~/.local/bin/uvx`, that path may not be visible to Claude. Use the absolute path: ```json theme={null} { "mcpServers": { "mireye-earth": { "command": "/Users/you/.local/bin/uvx", "args": ["mireye-mcp"] } } } ``` `which uvx` from a terminal gives you the absolute path. ## Cursor Cursor reads MCP config from one of: * `~/.cursor/mcp.json` (global) * `/.cursor/mcp.json` (workspace) Same shape as Claude Desktop: ```json theme={null} { "mcpServers": { "mireye-earth": { "command": "uvx", "args": ["mireye-mcp"] } } } ``` Open **Cursor → Settings → MCP**. The `mireye-earth` server should show two tools with green status indicators. Resource and prompt visibility depends on the Cursor MCP UI version. ## Custom MCP agent (Python SDK) If you're embedding MCP in your own agent loop, use the official `mcp` Python SDK to talk to the server: ```python theme={null} import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client PARAMS = StdioServerParameters( command="uvx", args=["mireye-mcp"], # Optional: env vars passed to the spawned process. env={"MIREYE_BASE_URL": "https://api.mireye.com"}, ) async def main(): async with stdio_client(PARAMS) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print([t.name for t in tools.tools]) # ['mireye_ask', 'mireye_fetch'] resources = await session.list_resources() prompts = await session.list_prompts() result = await session.call_tool( "mireye_ask", { "lat": 40.7128, "lng": -74.0060, "question": "What is the elevation here?", }, ) print(result.content) asyncio.run(main()) ``` The `result.content` is the verbatim JSON body from `POST /v1/ask`. See the [tool reference](/mcp/tools) for the input schemas. ## Configuration Both tools share the same configuration, set via environment variables on the MCP server process: | Env var | Default | Purpose | | ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MIREYE_BASE_URL` | `https://api.mireye.com` | HTTP base URL the tools POST to. Useful for staging / self-hosted deploys. Stored login credentials only attach when they were created against this same URL. | | `MIREYE_TIMEOUT_S` | `120` | Per-request timeout (seconds). Must exceed the \~110 s `/v1/ask` server deadline; the default already covers cold starts. Raise it further (never below 120) only if you still time out. | | `MIREYE_BEARER_TOKEN` | unset | Optional Mireye bearer token. Overrides stored credentials for tool calls; `status` reports on the stored login first. | | `MIREYE_MCP_CREDENTIALS_FILE` | `~/.config/mireye-mcp/credentials.json` | Stored credential file used by login/status/logout. | Set them in the agent's MCP config: ```json theme={null} { "mcpServers": { "mireye-earth": { "command": "uvx", "args": ["mireye-mcp"], "env": { "MIREYE_BASE_URL": "https://staging.mireye.example" } } } } ``` ## Verify with MCP Inspector The MCP Inspector is the canonical way to debug a server end-to-end: ```bash theme={null} npx @modelcontextprotocol/inspector uvx mireye-mcp ``` It opens a web UI showing the server's tools, resources, and prompts, lets you call each one with synthetic arguments, and tails stderr logs from the server process. A passing smoke check: 1. Tools list shows **exactly two** entries: `mireye_ask`, `mireye_fetch`. 2. Resources list shows `mireye://catalog/fields`, `mireye://catalog/presets`, and `mireye://catalog/us-envelope`. 3. Prompt list includes `mireye_site_report`, `mireye_flood_check`, `mireye_wildfire_underwrite`, and `mireye_pick_fields`. 4. Call `mireye_ask` with `lat: 40.7128, lng: -74.006, question: "elevation?"` — get a JSON response with `answer`, `confidence`, `citations`. 5. Call `mireye_fetch` with `lat: 40.7128, lng: -74.006, fields: ["elevation"]` — get a JSON response with `fields.elevation.value` populated. ## Authentication The local stdio adapter does not launch native MCP OAuth. It runs on your machine and uses a one-time device login to store a Mireye API token locally. Run: ```bash theme={null} mireye-mcp login ``` The command prints a verification URL and code, waits while you approve the code in the Mireye account page, and stores a local API token. You can check or clear credentials with: ```bash theme={null} mireye-mcp status mireye-mcp logout mireye-mcp logout --revoke ``` Stored credentials are bound to the `MIREYE_BASE_URL` that `login` ran against, and the token is only ever sent to that same URL. If you later point `MIREYE_BASE_URL` somewhere else (staging, self-hosted), tool calls behave as logged out and the error names both URLs — re-run `mireye-mcp login` against the new URL, or set `MIREYE_BEARER_TOKEN` explicitly. Tokens are also never sent over plain `http://`, except to loopback hosts (`localhost` / `127.0.0.1` / `[::1]`) for local development. `status` and `logout --revoke` use the stored URL, so you can always inspect or revoke a stored login. For non-interactive hosts, set `MIREYE_BEARER_TOKEN` in the MCP config. The MCP server only forwards bearer tokens; Firebase verification and account policy live in the HTTP API. Remote MCP clients should connect to `https://api.mireye.com/mcp` instead. They will receive the OAuth metadata and complete a browser OAuth 2.1 + PKCE flow automatically when the client supports remote MCP authorization. ## Updating > **Switching from the old `mireye-earth-mcp` package?** Credentials now > live in `~/.config/mireye-mcp/credentials.json` (the old path was > `~/.config/mireye-earth-mcp/`), so the first run after switching looks > unauthenticated. Re-run `mireye-mcp login` once to re-authenticate. With `uvx`, just re-invoke — `uvx` checks for a new version on each cold call (or pin explicitly with `uvx mireye-mcp@latest`): ```bash theme={null} uvx mireye-mcp@latest ``` With pip: ```bash theme={null} pip install --upgrade mireye-mcp ``` Then restart Claude Desktop / Cursor so the new server binary is picked up. Tool input schemas are stable within a minor version; check the [catalog page](/api-reference/field-catalog) for any field additions.