# Connect EDK-1 to Claude Code

EDK-1 is a spatial model that gives humans and machines a compass for the world: position, condition, motion, navigation and stream.
Four calls: Discover finds places, Inspect describes a point, Route finds the way, Monitor watches for change. Docs: https://edk.earth/docs · API: https://api.edk.earth/v1

You are Claude Code. Work through these steps in order. Check each one, and stop and tell me if a step fails.

1. **Account.** If I don't have one, ask me to sign up at https://edk.earth/sign-up (500 free CU every month).
2. **Key.** Ask me to create a secret key at https://edk.earth/console/keys and set it in my shell as `EDK_API_KEY`. Never ask me to paste the key here, and never commit it.
3. **Connect.** Run `claude mcp add edk --env EDK_API_KEY=$EDK_API_KEY -- npx -y @edks/mcp`.
   Tell me if I need to restart Claude Code for the `edk` tools to show up. Do not install the CLI or the SDK unless I ask.
4. **Test.** Discover "parks with playgrounds in Austin" (limit 5), then Inspect the first result's coordinates. Show me the results, the CU used and the embed_url.
5. **Remember.** Add this to `CLAUDE.md`:

```
## EDK (EDK-1 spatial model)
- Questions about places and what is on the ground go to EDK-1 (https://api.edk.earth/v1).
- Discover finds places from a question: POST /v1/discover {query, limit}. Use it when you need a list of locations or areas.
- Inspect describes one point: GET /v1/inspect?lat=&lng=. Use it when you already have coordinates.
- Route finds the way: POST /v1/route {from, to, include?, conditions?}. Use it for directions; include is what to pass, conditions what to avoid.
- Name-only question about one spot: Discover it, then Inspect the coordinates returned.
- Use the edk MCP tools when available; otherwise the @edks/sdk SDK or the REST API with EDK_API_KEY.
- Monitor watches an area for new events: POST /v1/monitors {artifacts, area, since, interval, webhook_url}. Tier 4 and above.
- Share results on the Atlas with the embed_url each Discover call returns.
- Docs: https://edk.earth/docs
```

## Discover, Inspect, Route or Monitor
EDK-1 has four calls. Pick by what you already have and what you need back.

**Discover** when you have a question and need places. It finds things; you get a list back.
- "bridges in Pittsburgh", "solar farms near Phoenix": things you can see on the ground.
- "high income areas in Denver", "low flood risk with tree canopy in Austin": areas that meet conditions.
- Returns locations and areas with coordinates, imagery and an embed_url that opens them on the Atlas.
- Name the city or region in the query. Set limit to what you will actually use (CU scales with results). Add answer: true only when the user wants a written summary.

**Inspect** when you have a point and need to know about it. It describes one spot; you get facts back.
- "what is at 40.4406, -79.9959", "is this address in a flood zone", "who lives around here".
- Returns the place names, highlights (income, people nearby, elevation, flood risk, tree canopy, air quality) and every known fact by category.
- It takes coordinates, not names. If you only have a name or address, Discover it first and Inspect the coordinates that come back.

**Route** when you have a start and an end and need the way between them.
- "drive from Point State Park to Carnegie Mellon avoiding pothole streets", "walking route from A to B".
- from and to take a place name, an address, or coordinates. include is plain words for what to pass on the way ("a coffee shop"); conditions is plain words for what to stay clear of ("pothole streets"). EDK-1 finds those places along the way and routes through or around them.
- Returns distance, duration, the path as GeoJSON, turn-by-turn steps, what it passes and avoided, and the direct route for comparison.
- Conditions steer driving routes only. Read note and remaining in the response and tell the user when something could not be avoided.

**Monitor** when the user wants to know about new events as they happen, not once.
- "tell me when a building permit is filed in Pittsburgh", "watch for new potholes downtown every hour".
- POST /v1/monitors with artifacts (names or ids from GET /v1/artifacts), an area (a place name or "lat, lng"), since (a date), interval ("15m", "1h", "6h", "1d") and a webhook_url. Events also appear in the console.
- Each new event is 0.2 CU. Monitor is available from Tier 4; a 403 means the account is below it, so say so.

Together: Discover to find candidates, Inspect the one or two that matter, Route to the one chosen. Don't Inspect every Discover result, and don't use Discover to describe a single known point.
None of the calls returns live traffic or transit timetables. Say so instead of guessing.

## Reference
- `POST /v1/discover` {query, limit?, answer? (default false), areas?: [[lng,lat]], focus?} → {id, model, embed_url, usage, data: {geojson, region?, conditions?, answer?}}
- `GET /v1/inspect?lat=&lng=` → {model, usage, data: {known, place, highlights, categories, outline}}
- `POST /v1/route` {from, to, include?, conditions?, profile?} → {model, usage, data: {from, to, route: {distance_m, duration_s, geometry, steps}, direct?, include?, conditions?, included, avoided, remaining?, note?}}
- `POST /v1/monitors` {artifacts, area, since?, interval?, webhook_url?, prompt?, name?} → the monitor, with webhook_secret. `GET /v1/monitors`, `GET /v1/monitors/:id/events`, `PATCH` {status: "paused" | "active"}, `DELETE`, `POST /v1/monitors/:id/scan`. `GET /v1/artifacts?q=` lists what can be watched.
- `GET /v1/usage` balance, tier and limits
- Authenticate with `Authorization: Bearer $EDK_API_KEY`. MCP tools: `edk_discover`, `edk_inspect`, `edk_route`, `edk_monitor_create`, `edk_monitor_events`, `edk_usage`.
- `curl -X POST https://api.edk.earth/v1/discover -H "Authorization: Bearer $EDK_API_KEY" -H "content-type: application/json" -d '{"query":"bridges in Pittsburgh","limit":5}'`
- A Compute Unit (CU) is the GPU and CPU work EDK-1 needs to process a request.