<!-- mcp-name: com.deepmapai/earth-grounding -->
# DeepMap AI — Earth Grounding MCP

**Verifiable physical-world ground truth for AI agents.** Ask about subsurface water,
seismic and space-weather hazard, ground stability, and resource indications for any point
on Earth — and every answer carries a **Bitcoin-anchored provenance record**, so a
physical-world claim can be *checked* rather than trusted.

This repository holds the published **thin client**: a small stdio
[Model Context Protocol](https://modelcontextprotocol.io) server that proxies your calls to
DeepMap's hosted engine at `https://deepmapai.com/mcp`. It is **stdlib-only** — no
dependencies, no platform code, no proprietary data. The answers and their provenance come
from the hosted service.

- **Registry id:** `com.deepmapai/earth-grounding`
- **PyPI:** [`deepmap-earth-grounding-mcp`](https://pypi.org/project/deepmap-earth-grounding-mcp/)
- **Hosted endpoint:** `https://deepmapai.com/mcp` (Streamable HTTP)
- **Public ledger:** <https://deepmapai.com/track-record>

## Quick start

```bash
uvx deepmap-earth-grounding-mcp
```

A free demo key works with no signup:

```bash
export DEEPMAP_API_KEY=demo-free
```

Claude Code, hosted (no install):

```bash
claude mcp add --transport http deepmap-earth-grounding https://deepmapai.com/mcp --header "apiKey: demo-free"
```

Claude Code, local stdio:

```bash
claude mcp add deepmap-earth-grounding -e DEEPMAP_API_KEY=demo-free -- uvx deepmap-earth-grounding-mcp
```

Per-client config snippets (Claude Desktop, Cursor, VS Code, generic) are in
[`connectors/`](connectors/); see [INSTALL.md](INSTALL.md).

## Tools

Eight answer questions about a place. Three answer questions about *the evidence itself* —
those are the ones worth reading twice.

| tool | what it answers |
|---|---|
| `water_availability` | replenishable-water availability at a point |
| `seismic_hazard` | seismic hazard via the public, outcome-excluded prediction ledger |
| `ground_stability` | subsidence / void / karst / fault risk from verified observations |
| `resource_indication` | geothermal / mineral / gas / water indication (gated) |
| `space_weather_grid_risk` | live geomagnetic (Kp) activity as GIC / grid exposure |
| `verify` | verify a claim hash / the ledger hash chain against the Bitcoin anchor |
| `ground_truth` | the bundled five-question answer + one provenance record |
| `capabilities` | what DeepMap can answer now + public coverage counts |
| `check_hypothesis` | **has this Earth-science hypothesis already been tested?** Queries the Null Museum and the anchored hypothesis registry, and returns the verdict *with the positive control that proves the test was sensitive* |
| `list_nulls` | the documented nulls, bounds and **retractions** — we carry our own, and that is the point |
| `run_controlled_test` | **Lab-as-an-API**: fetches real data, runs a bounded controlled test with a local-background null *and* a positive control, and returns `UNTESTABLE` rather than a fabricated null |

## Why it answers differently

- **Grounded** on a geophysical sensor network and live feeds, not on the open web.
- **Verifiable** — answers reference a Bitcoin-anchored, pre-registered ledger. Call
  `verify` on any claim hash and check it yourself.
- **Honest by construction** — it returns `null` rather than a fabricated value, publishes
  no platform-wide accuracy headline, and will tell you a question is `UNTESTABLE` instead
  of inventing a clean answer. A negative result is only worth anything next to the
  positive control that shows the test could have detected something; both are returned.

## Design

`tools/list` is answered **locally**, so the tool surface is visible offline and without a
key. `tools/call` is proxied to the hosted endpoint with your `apiKey`. If the endpoint is
unreachable the client returns an honest tool error rather than crashing — and never a
substituted value.

Run the self-test:

```bash
python -m deepmap_earth_mcp --self-test
```

## Support

<info@deepmapai.com> · service terms: <https://deepmapai.com/terms>