# MCP server | Rijwind docs

# MCP server

Rijwind ships a hosted [MCP](https://modelcontextprotocol.io) (Model
Context Protocol) server, so AI assistants and coding agents can use
the platform directly: geocode addresses, calculate routes and
matrices, compute isochrones, match GPS traces, optimize trips, and
render static map images — all as native tools.

```
https://mcp.rijwind.com
```

The server speaks streamable HTTP and supports two ways to
authenticate:

- **API key** — set your regular Rijwind key as a Bearer header.
  For coding agents (Claude Code, Codex, Cursor).
- **OAuth sign-in** — one-click connect with a browser login, no key
  to copy. For the Claude and ChatGPT apps (custom connectors).

**MCP access is included in every paid plan.** The Personal plan
(€5/month) is the cheapest way in. Free-tier accounts get
`403 mcp_not_enabled`.

## Connect your client

For the API-key clients below you need an [API key](/authentication).
MCP calls run server-side, so use a key **without an origin whitelist**
(an origin-restricted key is rejected with `403 origin_required`).

### Claude Code

```shell
claude mcp add --transport http rijwind https://mcp.rijwind.com \
  --header "Authorization: Bearer rw_live_•••YOUR_KEY•••"
```

This covers the **desktop app** too: it shares its configuration with
the CLI, so a server added with `claude mcp add` (or via `.mcp.json`)
appears there automatically. The in-app Connectors menu only lists
pre-built integrations — custom servers are added via the command or
config file.

To share the server with your team instead, commit it to your project's
`.mcp.json`:

```json
{
  "mcpServers": {
    "rijwind": {
      "type": "http",
      "url": "https://mcp.rijwind.com",
      "headers": {
        "Authorization": "Bearer rw_live_•••YOUR_KEY•••"
      }
    }
  }
}
```

### Codex

Codex configures remote MCP servers in `~/.codex/config.toml` (the
`codex mcp add` command is for local stdio servers only). It reads the
key from an environment variable, so the secret stays out of the
config file:

```toml
[mcp_servers.rijwind]
url = "https://mcp.rijwind.com"
bearer_token_env_var = "RIJWIND_API_KEY"
```

Then export the key in your shell profile, so it's set when Codex
launches:

```shell
export RIJWIND_API_KEY="rw_live_•••YOUR_KEY•••"
```

The **Codex IDE extension** shares this configuration with the CLI:
open the Codex side panel → gear icon → *MCP settings* → *Open
config.toml* to edit the same file from your editor.

### Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
Cursor interpolates `${env:…}` from your shell environment — recommended
over hardcoding the key, especially in a project file you might commit:

```json
{
  "mcpServers": {
    "rijwind": {
      "url": "https://mcp.rijwind.com",
      "headers": {
        "Authorization": "Bearer ${env:RIJWIND_API_KEY}"
      }
    }
  }
}
```

A literal `"Bearer rw_live_•••YOUR_KEY•••"` value works too.

Once added, the server shows up under *Cursor Settings → MCP*, where
you can toggle it on and off. Cursor's one-click marketplace installs
only cover its own directory — custom servers like this one are added
via `mcp.json`.

### Claude & ChatGPT apps (OAuth, no key needed)

The Claude apps (web and desktop) and ChatGPT connect via **custom
connectors** with a browser sign-in — no API key to copy:

1. Add a custom connector and enter `https://mcp.rijwind.com` as the
   URL (in Claude: *Settings → Connectors → Add custom connector*).
2. Your browser opens a Rijwind sign-in: log in with your dashboard
   account and approve the connection.
3. Done — the assistant can now use the Rijwind tools.

Behind the scenes the connection bills through a dedicated **"MCP
Connector"** API key that is created automatically in your dashboard
on first use, drawing from the same monthly unit pool. Revoking that
key simply rotates it — to actually disconnect, remove the connector
in the client (and the key from your dashboard if you like).

### Other clients

Any MCP client that supports remote servers over streamable HTTP works
with either auth mode:

| Setting | Value |
| --- | --- |
| URL | `https://mcp.rijwind.com` |
| Header (API-key mode) | `Authorization: Bearer rw_live_•••YOUR_KEY•••` |
| OAuth | supported — discovery + dynamic client registration per the MCP spec |

## Tools

| Tool | What it does | Cost (units) |
| --- | --- | --- |
| `geocode_forward` | Search places / forward geocoding | 1 |
| `geocode_reverse` | Coordinates → nearest address | 1 |
| `geocode_autocomplete` | Complete a partial query | 0.1 |
| `directions` | Route along waypoints (car / bike / foot) | 1 |
| `directions_matrix` | Travel-time + distance matrix | sources × targets |
| `isochrone` | Reachable-area polygons | 5 × locations × contours |
| `map_matching` | Snap a GPS trace to the road network | 1 |
| `optimized_route` | Optimal visiting order over stops | 1 per location |
| `static_map` | Render a map image with overlays | 1 (2 for `@2x`) |
| `show_map` | **Interactive map** with markers, routes, isochrones | 1 per map session |

These are the same endpoints as the [REST API](/api), with the same
parameters and the same responses — the MCP server is a thin
translation layer, not a separate product.

## Maps in the conversation

Two tools draw maps, for different situations:

- **`static_map`** returns a real image — it renders inline in any
  client that displays image results (the Claude apps, Claude Code,
  Cursor) and is ideal for reports and quick previews.
- **`show_map`** opens an **interactive map** (pan, zoom, clickable
  markers) directly in the conversation, on the Rijwind basemap. It
  accepts markers, encoded route polylines (straight from
  `directions`), and GeoJSON (straight from `isochrone`). It uses the
  [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)
  standard, supported by the Claude apps, ChatGPT, and VS Code, among
  others. Costs 1 unit per map session — panning, zooming, and tile
  refreshes within the session are free. In clients without MCP Apps
  support (e.g. terminal agents), the tool degrades to its structured
  JSON result; use `static_map` there.

## Quotas and scopes

- **Units come from your regular monthly pool.** An MCP call costs
  exactly what the equivalent REST call costs — see
  [Quotas & rate limits](/quotas). There is no separate MCP meter.
- **Key scopes filter the tool list.** A key scoped to `geocode` only
  exposes the three geocoding tools; routing and static-map tools
  don't appear to the agent at all. An unscoped key exposes
  everything.
- Requests are rate-limited per key. Sustained agent workloads are
  fine; runaway loops get `429`.

## What the server won't do

The MCP server is deliberately **data-plane only and read-only**: no
tool can change your subscription, spend money, or alter billing
settings. Plan changes and payment settings live exclusively in the
[dashboard](https://rijwind.com/dashboard).