# Geo-Parity MCP Server

A live, hosted [Model Context Protocol](https://modelcontextprotocol.io) server for
**geographic parity** — purchasing power, fair salaries across borders, cost of living,
FIRE and runway, visas and passports, tax residency, timezone overlap, climate, country
risk and relocation costs.

**Endpoint:** `https://geo-parity.com/api/mcp`
**Transport:** Streamable HTTP
**Auth:** none — open, no key, no sign-up

## Install

**Remote (recommended)** — connect straight to the hosted server:

```bash
claude mcp add --transport http geo-parity https://geo-parity.com/api/mcp
```

```json
{
  "mcpServers": {
    "geo-parity": {
      "type": "http",
      "url": "https://geo-parity.com/api/mcp"
    }
  }
}
```

**stdio** — for clients that do not speak Streamable HTTP. This package is a thin
bridge to the same hosted server:

```bash
npx -y geo-parity-mcp
```

```json
{
  "mcpServers": {
    "geo-parity": {
      "command": "npx",
      "args": ["-y", "geo-parity-mcp"]
    }
  }
}
```

The bridge **forwards JSON-RPC verbatim and declares no tools of its own**, so the tool
list is always the server's. New tools appear without updating this package, and the
protocol version your client negotiates is negotiated with the real server.

Environment variables (all optional):

| Variable | Default | Purpose |
|---|---|---|
| `GEO_PARITY_MCP_URL` | `https://geo-parity.com/api/mcp` | Point the bridge elsewhere |
| `GEO_PARITY_API_KEY` | — | `gp_live_…` key; raises rate limits |
| `GEO_PARITY_TIMEOUT_MS` | `30000` | Per-request timeout |

## Protocol support

The server is **dual-era**: one endpoint serves both the modern per-request revision and
the older initialization-handshake revisions, and it echoes back whichever version your
client asks for.

| Revision | Era | Notes |
|---|---|---|
| `2026-07-28` | modern | per-request `_meta`, `server/discover`, `UnsupportedProtocolVersionError` |
| `2025-11-25` | legacy | `initialize` handshake |
| `2025-06-18` | legacy | `initialize` handshake |
| `2025-03-26` | legacy | `initialize` handshake |
| `2024-11-05` | legacy | `initialize` handshake |

A version we do not implement is refused with `-32022` listing the ones we do, so a
client can pick one and retry.

## Tools (26)

Every tool is a **pure read** over static datasets — read-only, non-destructive,
idempotent and closed-world — so no call needs confirming.

| Tool | What it answers |
|---|---|
| `calculate_ppp` | What a US-baseline income is really worth in another country |
| `localize_salary` | Fair pay for the same role across borders |
| `calculate_wage_bands` | Local wage ladder: minimum, median, top 10% |
| `compare_total_cost` | Total cost of living against your income |
| `compare_countries` | Two countries' cost of living, side by side |
| `estimate_micro_costs` | Everyday prices (the Pint & Property Index) |
| `compare_housing` | Rent as a share of your income *and* of the local median wage |
| `compare_healthcare` | Health spending, out-of-pocket share and dentist access |
| `compare_connectivity` | Measured internet quality and price |
| `compare_climate` | Climate normals and comfortable days per year |
| `compare_public_holidays` | Shared working days and public holidays |
| `compare_country_risk` | Country risk (INFORM, EC JRC) |
| `rank_livability` | Quality of life against cost |
| `find_fire_locations` | Where a portfolio can fund early retirement |
| `calculate_runway` | How much longer your savings last if you relocate |
| `compare_contract` | Contractor vs employee net take-home |
| `required_rate` | The freelance hourly rate you actually need |
| `find_nomad_visas` | Digital nomad visas your income qualifies for |
| `passport_power` | Visa-free access score and global rank |
| `arrival_cost` | What it costs to *arrive*: entry fee, first rent, deposit |
| `check_schengen` | Whether an itinerary breaks Schengen 90/180 |
| `check_residency` | Tax-residency day counts |
| `check_tax_residency_risk` | Tax-residency risk for remote work abroad |
| `check_travel_residency` | Unified Schengen + residency + tax-cost tracker |
| `find_meeting_slot` | Team timezone friction and the meeting window |
| `select_region` | Lowest-latency cloud host region |

## Try it

```bash
curl -s -X POST https://geo-parity.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

```bash
curl -s -X POST https://geo-parity.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate_ppp","arguments":{"income":100000,"target":"TH"}}}'
```

Discover what the server supports in one request:

```bash
curl -s -X POST https://geo-parity.com/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"server/discover"}'
```

## Every result is citable

Successful responses carry an `attribution` block: the datasets used, their providers and
reference years, a ready-to-quote citation sentence, and a permalink to the page that
answers the same question. Quote it when you use these figures.

## Rate limits

Open and key-less. Anonymous callers get **1,500 requests/month** per IP plus a
**30/minute** burst cap. An optional API key (`Authorization: Bearer gp_live_…`, created
at <https://geo-parity.com/account>) raises both ceilings without changing any response,
and is metered per account rather than per key.

Over a ceiling, endpoints return HTTP 429 with `RATE_LIMITED` (slow down) or
`QUOTA_EXCEEDED` (allowance spent — retrying will not help).

## Also available as

- **REST** — every tool is a plain JSON endpoint: <https://geo-parity.com/openapi.json>
- **Capability index for agents** — <https://geo-parity.com/llms.txt>
- **Server card** — <https://geo-parity.com/.well-known/mcp.json>

## Caveats

Figures are estimates built from public datasets (World Bank, Eurostat, OECD, WHO, HUD,
INFORM, Nager.Date, Open-Meteo, Cloudflare Radar, ITU and others). They are **not tax,
legal or financial advice**. Where a figure could not be verified it is reported as
absent rather than guessed — an absent value never means zero.

## Links

- Site: <https://geo-parity.com>
- Full documentation: <https://geo-parity.com/llms.txt>

## Licence

MIT for this repository's contents. The hosted service is provided as-is under the site's
[terms](https://geo-parity.com/terms/).