# Connect exchangerate.dev

> Connect the exchangerate.dev MCP server to your user's AI assistant or coding agent, and confirm it works with one data call. The first route is sign-in: connect, sign in with your user's account, choose Allow. An API key is the fallback, and the server also works with no key. Docs page: https://exchangerate.dev/docs/mcp

## Objective

Add the exchangerate.dev MCP server (https://api.exchangerate.dev/v1/mcp/) to the client your user works in, and make one call that returns an exchange rate.

## Done when

The client lists the exchangerate.dev tools and one tool call returned a rate. Tell your user which client you set up and what the call returned. If something blocks setup, report that blocker. Do not claim success.

## Steps

1. Find out which client your user works in.
2. Follow the matching route below and sign in. You add the remote server `https://api.exchangerate.dev/v1/mcp/`, connect, and your user signs in with their exchangerate.dev account in the browser and chooses Allow. The calls then count against that account. No key is pasted anywhere. If your client never offers sign-in (the server also answers with no key, so some clients do not ask), use an API key instead; until you sign in or send a key, calls run on the keyless limits.
3. If the client cannot sign in, or your user prefers a key, use an API key as the fallback: a free key (5,000 calls a month, no card) comes from https://exchangerate.dev/auth.md, which also describes agent sign-up by email code. Keep the key in the environment variable `EXCHANGERATE_API_KEY`.
4. The remote server also works with no key and no sign-in, which is enough for a first call.
5. List the tools, then make one test call.

## Rules

- Sign-in is the first route to try. If your client never offers sign-in (the server also answers with no key, so some clients do not ask), use an API key instead; until you sign in or send a key, calls run on the keyless limits. Your user does the sign-in and the Allow; you never see their password. The client gets its own token for the account, which expires and refreshes by itself. A client that supports MCP sign-in finds the rest from `https://api.exchangerate.dev/.well-known/oauth-protected-resource`.
- Never ask your user to paste an API key into the chat. Never put a key in a URL or in a file that gets committed. Read it from `EXCHANGERATE_API_KEY` or the client's secret storage.
- Keys start with `exr_live_`. Send the key as `Authorization: Bearer <key>`.
- Without a key or sign-in, calls share a pool that is capped per IP address (10 requests per minute, 100 per hour). Signing in or using a key moves the calls onto your user's own quota.
- Every tool call counts against the same rate limit and monthly quota as a REST call, whether the account signed in or sent a key. Free rates arrive 15 minutes late.
- `start_checkout` opens billing for a paid plan. Call it only when your user has asked for a specific plan and confirmed it.
- Rates are indicative. Do not present them as executable quotes or use them for settlement or trading.

## Routes

### Claude Code

```
claude mcp add --transport http exchangerate-dev https://api.exchangerate.dev/v1/mcp/
```

Then run `/mcp`, pick `exchangerate-dev` and choose to authenticate if the option is shown. A browser tab opens: your user signs in and chooses Allow. Check with `claude mcp get exchangerate-dev`.

Fallback with a key: add `--header "Authorization: Bearer $EXCHANGERATE_API_KEY"` to the command.

### Claude app (desktop)

Sign-in: add `https://api.exchangerate.dev/v1/mcp/` as a custom connector in the app's settings, connect it, and your user signs in and chooses Allow.

Fallback with a key: edit `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, on Windows: `%APPDATA%\Claude\claude_desktop_config.json`) and add the server below. Then quit Claude fully (Cmd-Q, not just closing the window) and open it again.

```json
{
  "mcpServers": {
    "exchangerate-dev": {
      "command": "npx",
      "args": ["-y", "@nusantara-ventures/exchangerate-mcp"],
      "env": { "EXCHANGERATE_API_KEY": "exr_live_..." }
    }
  }
}
```

Your user pastes the key into this file themselves. Do not print it in chat. To run without a key, replace the `env` block with `{ "ALLOW_ANONYMOUS": "true" }`.

### Cursor

Sign-in: add the remote server to `.cursor/mcp.json` in the repository, or to `~/.cursor/mcp.json`, then connect it from Cursor's MCP settings. Your user signs in and chooses Allow.

```json
{
  "mcpServers": {
    "exchangerate-dev": { "url": "https://api.exchangerate.dev/v1/mcp/" }
  }
}
```

Fallback with a key: add this block to the same file instead. Restart Cursor, or switch the server off and on in its MCP settings.

```json
{
  "mcpServers": {
    "exchangerate-dev": {
      "command": "npx",
      "args": ["-y", "@nusantara-ventures/exchangerate-mcp"],
      "env": { "EXCHANGERATE_API_KEY": "exr_live_..." }
    }
  }
}
```

### VS Code

Run `MCP: Open Workspace Folder MCP Configuration` from the Command Palette. For sign-in, add the server with only its address, start it, and your user signs in and chooses Allow when VS Code asks:

```json
{
  "servers": {
    "exchangerate-dev": { "type": "http", "url": "https://api.exchangerate.dev/v1/mcp/" }
  }
}
```

Fallback with a key: add this instead. VS Code asks for the key when it starts the server and keeps it out of the file.

```json
{
  "inputs": [
    { "type": "promptString", "id": "exchangerate-key", "description": "exchangerate.dev API key", "password": true }
  ],
  "servers": {
    "exchangerate-dev": {
      "type": "http",
      "url": "https://api.exchangerate.dev/v1/mcp/",
      "headers": { "Authorization": "Bearer ${input:exchangerate-key}" }
    }
  }
}
```

### Any other MCP client

Use the remote server `https://api.exchangerate.dev/v1/mcp/` (Streamable HTTP) and sign in when the client offers it. Sign-in discovery is at `https://api.exchangerate.dev/.well-known/oauth-protected-resource`. If the client cannot sign in, send `Authorization: Bearer <key>` with your user's key. A client that can only start local servers runs `npx -y @nusantara-ventures/exchangerate-mcp` with `EXCHANGERATE_API_KEY` set, or `ALLOW_ANONYMOUS=true` for no key. More: https://exchangerate.dev/docs/mcp and https://exchangerate.dev/mcp

## Test call

Ask the client to list the exchangerate.dev tools. Then ask: "What is the USD to EUR rate?" The tool is `get_rate` with `base` USD and `quote` EUR. The answer should carry a rate with `source`, `market_session` and `data_updated_at`. Tell your user the rate and that it is indicative.

## If it fails

- The client shows no tools: quit it fully and open it again. MCP servers load once, on launch. Check that the config JSON parses. A trailing comma is the usual cause.
- `429`: the shared no-key pool or the key's limit is used up. Wait, then try once more, or follow https://exchangerate.dev/auth.md to get a key.
- The sign-in page says "This sign-in link is not valid. Start again from the app.": go back to the client and connect again.
- The sign-in page says "Open your dashboard once to create your account": your user opens https://exchangerate.dev/dashboard once, then connects again.
- Authentication error with a key: check the key starts with `exr_live_` and is set in the client's own config, not only in the shell. With sign-in, connect again from the client.
- More help: https://exchangerate.dev/docs/mcp or hello@exchangerate.dev.
