--- title: "MCP Server — AllRatesToday Documentation" description: "Connect Claude Code, Cursor, Claude Desktop, Windsurf, and any MCP-compatible client to live and historical currency exchange rate data via the AllRatesToday MCP server." canonical: https://allratestoday.com/docs/mcp-server/ source: AllRatesToday (https://allratestoday.com/) — Markdown mirror of the page above; index of all pages at https://allratestoday.com/llms.txt generated: 2026-10-24T17:02:32.223Z --- # MCP Server — AllRatesToday Documentation Connect Claude Code, Cursor, Claude Desktop, Windsurf, and any MCP-compatible client to live and historical currency exchange rate data via the AllRatesToday MCP server. By [Madhushan](https://allratestoday.com/authors/madhushan/), Founder & Lead Developer **Documentation index:** see the [full API reference](https://allratestoday.com/docs/) for all REST endpoints. For a feature overview, visit the [MCP landing page](https://allratestoday.com/mcp/). **📄 Prefer offline? [Download the full MCP guideline as PDF](https://allratestoday.com/docs/allratestoday-mcp-guideline.pdf) (12 sections, 52 KB).** # MCP Server — Official Guideline The [`@allratestoday/mcp-server`](https://www.npmjs.com/package/@allratestoday/mcp-server) package gives any [Model Context Protocol](https://modelcontextprotocol.io/) client direct access to the AllRatesToday currency API. Once installed, your AI assistant can fetch live mid-market rates, query historical time-series, list supported currencies, and pull authenticated multi-target rates — without you writing any glue code. The server is published on the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=cahthuranag) as `io.github.cahthuranag/mcp-server` and on [npm](https://www.npmjs.com/package/@allratestoday/mcp-server). The free tier is enough to evaluate it; two of the four tools work without an API key at all. ## Why MCP instead of direct REST? If you are building a single application with one well-defined call pattern, the REST API is simpler. If you want your AI assistant to flexibly use exchange-rate data as part of broader work, MCP is the better choice. | Concern | Direct REST | MCP Server | | --- | --- | --- | | Code to write | HTTP client, error handling, schema parsing | None — install once | | Tool discovery by the model | Manual prompt engineering | Automatic via tool schemas | | Tool chaining (multi-step queries) | Manual orchestration | Native — model chains calls itself | | API key handling | Often pasted into prompts (insecure) | Stays in environment, never seen by the model | | Reuse across clients | Reimplement per client | One install per client | ## Prerequisites - **Node.js 18 or later.** The server is distributed via npm and run with `npx`. Verify with `node --version`. - **An AllRatesToday API key** for the authenticated tools (free tier available). Get one at [allratestoday.com/register](https://allratestoday.com/register). - **An MCP-compatible client.** See the next section. The two public tools (`get_exchange_rate`, `list_currencies`) work without an API key — useful for testing connectivity before configuring auth. ## Adding MCP Servers The server runs locally on your machine via `npx` — there is nothing to host and your API key never leaves your computer. Pick your client below: - Claude Code - Cursor - Claude Desktop - ChatGPT Desktop - Windsurf - Other MCP clients ## Installation ### Hosted endpoint (remote MCP, no install) If your client supports remote MCP servers — Claude.ai and Claude Desktop connectors, ChatGPT, Cursor, VS Code, Codex, Gemini CLI, or Claude Code with `--transport http` — you can skip npm entirely and point it at the hosted Streamable HTTP endpoint, which exposes the currency tools *and* the official central-bank tools together: ``` https://allratestoday.com/api/mcp ``` ``` claude mcp add --transport http allratestoday https://allratestoday.com/api/mcp ``` It runs keyless out of the box. To use your key, send it as `Authorization: Bearer art_live_…` or, where the client only accepts a URL, connect to `https://allratestoday.com/api/mcp?api_key=art_live_…`. One-click Cursor and VS Code buttons are on the [MCP page](https://allratestoday.com/mcp/#hosted). ### Claude Code Run two commands in any terminal: ``` claude mcp add allratestoday -- npx -y @allratestoday/mcp-server claude mcp env allratestoday ALLRATES_API_KEY=art_live_xxxxx ``` The server is registered globally and available in every Claude Code session. Run `claude mcp list` to verify. ### Cursor Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root, and add an entry under `mcpServers`: ``` { "mcpServers": { "allratestoday": { "command": "npx", "args": ["-y", "@allratestoday/mcp-server"], "env": { "ALLRATES_API_KEY": "art_live_xxxxx" } } } } ``` Restart Cursor. The four tools appear under the MCP icon in chat. ### Claude Desktop Edit your Claude Desktop config file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Linux: `~/.config/Claude/claude_desktop_config.json` ``` { "mcpServers": { "allratestoday": { "command": "npx", "args": ["-y", "@allratestoday/mcp-server"], "env": { "ALLRATES_API_KEY": "art_live_xxxxx" } } } } ``` **Fully quit and reopen Claude Desktop** after editing — closing the window leaves it running and the new config will not load. ### ChatGPT Desktop ChatGPT Desktop reads the same JSON format. Add the block above to its MCP config and restart the app. ### Windsurf Open Windsurf settings → MCP → *Add custom server*. Use the same configuration block as Cursor. ### Other MCP clients Any client that supports the [MCP stdio transport](https://modelcontextprotocol.io/specification) will work. Point it at the command: ``` npx -y @allratestoday/mcp-server ``` Pass `ALLRATES_API_KEY` through the environment. ## Configuration The server reads two environment variables: | Variable | Required? | Purpose | | --- | --- | --- | | `ALLRATES_API_KEY` | For authenticated tools only | Bearer token from your [dashboard](https://allratestoday.com/profile). Looks like `art_live_xxxxx`. | | `ALLRATES_BASE_URL` | No | Override the API host (default `https://allratestoday.com/api`). Useful for staging or self-hosted deployments. | ## Tools The server exposes four typed tools. The MCP client introspects each tool's schema automatically and passes it to the model — you do not need to register them yourself. ### Currency / Exchange Rate - **`get_exchange_rate`** — current mid-market rate between any two of 160+ supported currencies. *No API key required.* - **`get_rates_authenticated`** — fetch one base currency against multiple targets in a single call. Higher rate limits. *API key required.* ### Historical - **`get_historical_rates`** — time-series data over `1d`, `7d`, `30d`, or `1y` windows for any currency pair. *API key required.* ### Discovery - **`list_currencies`** — every supported currency code with its name, symbol, and decimal precision. Useful as a one-shot reference for the model. *No API key required.* - **`request_trial_key`** — (hosted endpoint only) self-issues an API key with 100 lifetime calls, valid 7 days, no account or email. The agent then reconnects with `?api_key=`. Capped at 3 per IP per day; see [trial keys for agents](https://allratestoday.com/docs#agent-keys). ## Authentication No human available to sign up? Call `request_trial_key` (hosted endpoint) or `POST https://allratestoday.com/api/agent/keys` (JSON body, will do) for a 100-call trial key. Otherwise: 1. Sign up at [allratestoday.com/register](https://allratestoday.com/register) — about thirty seconds. 2. Verify your email. 3. Copy the key from your [dashboard](https://allratestoday.com/profile). It begins with `art_live_`. 4. Set it as `ALLRATES_API_KEY` in your MCP client's `env` block (see Installation). The free plan covers personal/dev use. Public tools (`get_exchange_rate` and `list_currencies`) work without a key — test connectivity with those first if you run into auth issues. ## Example prompts Once installed, try: - *"What's the USD to EUR rate right now?"* - *"Show me GBP/JPY over the last 30 days as a sparkline."* - *"If I had 1,000 EUR and converted half to GBP and half to JPY, what would I have in USD?"* — the model chains `get_exchange_rate` calls itself. - *"List every currency you support, sorted alphabetically."* - *"Give me a 1-year time series for AUD/USD."* ## Troubleshooting | Symptom | Fix | | --- | --- | | Client doesn't see any AllRatesToday tools. | Fully quit and restart the client. Claude Desktop and Cursor cache the server list and will not reload it on a soft window close. | | `command not found: npx` | Install Node.js 18+ — `npx` ships with it. [nodejs.org](https://nodejs.org/). | | Authenticated tools return 401. | Confirm `ALLRATES_API_KEY` is set on the right server entry and starts with `art_live_`. Public tools should still work — test those to isolate the problem. | | Authenticated tools return 429. | You've exceeded the free-tier quota. Upgrade at [allratestoday.com/pricing](https://allratestoday.com/pricing) or wait until the monthly reset. | | Server starts but model never calls it. | Re-prompt with an explicit instruction like *"use the AllRatesToday MCP tool"*. Some models are reluctant to call tools when they think they already know the answer. | ## Security best practices 1. **Treat your API key like a password.** Anyone with it can spend your monthly quota. 2. **Never commit `claude_desktop_config.json` or `.cursor/mcp.json` to git.** Add them to `.gitignore`. If you must share configurations, use placeholder strings for the key. 3. **Rotate the key** if you suspect exposure. Dashboard → Settings → Regenerate. 4. **Use the public tools first** when testing connectivity — `get_exchange_rate` and `list_currencies` need no key, so a failure there isolates network issues from auth issues. 5. **Set a quota alert** in your dashboard so a runaway agent does not silently exhaust your free tier overnight. 6. **Project-scoped vs. global config.** For shared codebases, prefer project-level `.cursor/mcp.json` over global, so the API key lives in a per-project `.env` rather than a user-wide config file. ## Versioning and updates The package follows semantic versioning. Because installs use `npx -y @allratestoday/mcp-server`, every client launch fetches the latest published version automatically — no manual updates needed. Pin a specific version if you need reproducibility (CI, audit environments): ``` "args": ["-y", "@allratestoday/mcp-server@0.3.1"] ``` Release notes are published on [GitHub Releases](https://github.com/AllRates-Today/mcp-server/releases). ## Support - **Bug reports & feature requests:** [GitHub Issues](https://github.com/AllRates-Today/mcp-server/issues) - **General API support:** [support@allratestoday.com](mailto:support@allratestoday.com) - **Status page:** [allratestoday.com/status](https://allratestoday.com/status) - **Community:** share what you build — tag [@allratestoday](https://twitter.com/allratestoday) on X or post in the [GitHub Discussions](https://github.com/AllRates-Today/mcp-server/discussions). ## Resources - **Source code & issues:** [github.com/AllRates-Today/mcp-server](https://github.com/AllRates-Today/mcp-server) - **npm package:** [`@allratestoday/mcp-server`](https://www.npmjs.com/package/@allratestoday/mcp-server) - **Official MCP registry entry:** [`io.github.cahthuranag/mcp-server`](https://registry.modelcontextprotocol.io/v0/servers?search=cahthuranag) - **Also listed on:** [Glama](https://glama.ai/mcp/servers/AllRates-Today/mcp-server), [Glama Connectors](https://glama.ai/mcp/connectors/com.allratestoday/mcp), [PulseMCP](https://www.pulsemcp.com/servers/allratestoday), [MCP Market](https://mcpmarket.com/server/allratestoday), [AI Agents Listing](https://aiagentslisting.com/mcp/central-bank-mcp), [Public APIs](https://publicapis.dev/resource/allratestoday/obgx1siv), [AlternativeTo](https://alternativeto.net/software/allratestoday/) - **Feature overview:** [/mcp/](https://allratestoday.com/mcp/) - **Official central-bank rates MCP server:** [`@allratestoday/central-bank-mcp`](https://www.npmjs.com/package/@allratestoday/central-bank-mcp) — published rates from [122 central banks & 4 tax authorities](https://allratestoday.com/central-bank-rates-api/institutions/) ([announcement](https://allratestoday.com/blog/central-bank-rates-mcp-server/)) - **Full API reference:** [/docs/](https://allratestoday.com/docs/) - **Python alternative for DeepSeek:** [/deepseek/](https://allratestoday.com/deepseek/) ## Ready to plug live FX data into your AI? One `npx` install. Free tier. No credit card. [Get a free API key](https://allratestoday.com/register) [View source on GitHub](https://github.com/AllRates-Today/mcp-server)