MCP Tools

The CurrencyCore MCP server exposes 14 tools. Each one wraps one public REST endpoint, so the response fields match the REST reference exactly. This page lists the purpose, inputs, plan requirement, a call example, the response shape, and the errors for every tool.

• Reference tools: list_countries, list_currencies
• Core currency tools: convert, get_rates, get_rates_by_base, get_history, get_ppp_factor
• Analytics tools: analyze_history, analyze_ppp, analyze_volatility, analyze_correlation, analyze_drawdown, analyze_safe_haven, analyze_mean_reversion

All tools are read-only. Amounts and rates are numbers; dates are UTC YYYY-MM-DD strings.

How tool calls behave

Arguments

Tool arguments are the same parameters as the REST endpoint, without the URL. Optional parameters can be omitted. Numbers may arrive as strings over JSON-RPC, so the server coerces numeric arguments. Booleans are real booleans.

Missing required path parameters, such as base for get_rates_by_base, return a tool error before any API call is made.

Successful calls

A successful call returns the API’s JSON body as text. When the body is a JSON object, the server also returns it as structuredContent, which clients that support structured tool output can consume directly.

Every result includes _meta fields for usage reconciliation:

A successful keyed tool call counts as one API request. Public tool calls and failed calls are not billed.

Errors

The REST API uses one error envelope:

{
  "error": {
    "code": "unknown_currency",
    "message": "Unknown currency: XYZ",
    "details": {}
  }
}

The MCP server returns that body as the tool text with isError: true. It does not convert an API error into a JSON-RPC transport error, so the model can read the code and decide what to do next.

A 403 is not always an expired connection. Read the message: an analytics plan gate and a disabled MCP toggle both return 403 for different reasons. A removed membership usually surfaces as 401, because the grant no longer resolves to an organization. The troubleshooting guide maps each one to a fix.

Some server versions replace the API body with a reconnect message when a keyed call returns 401 or 403. If the text says the connection expired but you expected a plan gate, check structuredContent.error.code or the currencycore/status metadata. A 403 with forbidden is a plan, history window, or MCP-toggle problem, not an expired token.

Retries

The MCP server retries transient failures (network errors, timeouts, 429, and 5xx) up to two attempts with a short jittered backoff. A 4xx client error is returned immediately. Retry-After is capped at 5 seconds for the MCP retry, so a longer server-side window still surfaces as a 429 to the client.

Reference tools

list_countries

Returns every supported country and its official currency. Use it to resolve a country name to the alpha-3 code that PPP calls need.

• Plan: every plan, after an authorized MCP connection.
• Inputs: none.
• Call: {}
• Returns: an array of objects with code (ISO/IMF alpha-3), name, and currencies (an array of ISO 4217 codes).
• Errors: none expected after connection. The underlying REST endpoint is public, but the MCP server requires OAuth.

list_currencies

Returns every supported ISO 4217 currency, plus the documented non-ISO codes. Use it before a conversion so an unsupported code fails clearly instead of silently.

• Plan: every plan, after an authorized MCP connection.
• Inputs: none.
• Call: {}
• Returns: an array of objects with code, numeric, name, and symbol. numeric is the zero-padded ISO numeric code, or an empty string for CNH, GGP, IMP, and JEP. The list can include codes beyond the fiat rate feed, such as XAU, XAG, XPT, XPD, and XDR. The rate feed is fiat only, so check with convert before relying on a metal or a synthetic unit.
• Errors: none expected after connection. The underlying REST endpoint is public, but the MCP server requires OAuth.

Core currency tools

convert

Converts an amount between currencies, optionally with a purchasing-power-parity adjustment. This is the tool most agent conversations use.

• Plan: every plan.
• Inputs:

• Call:

{ "from": "USD", "to": "EUR,INR", "amount": 100 }

• Returns: from, amount, date, and results. Each result has to, result (the plain FX conversion), rate (result divided by amount), and, when PPP was requested, fromCountry, toCountry, and a ppp object. results[].ppp contains fromFactor, toFactor, and result, or an error string when PPP could not be applied for that target.
• Errors: invalid_input for a bad amount or date, and unknown_currency. A missing PPP factor is not a request error: that target returns ppp.error in a 200 response. An out-of-window history date on Free returns 403, and a rate limit returns 429.
• REST reference: /convert

get_rates

Returns the full exchange-rate snapshot for a date, with USD as the base.

• Plan: every plan.
• Inputs:

• Call:

{ "date": "2026-11-10" }

• Returns: base (USD), date, and rates, a map of currency code to units per 1 USD.
• Errors: 404 rate_not_found when no snapshot exists for that date, 403 for an out-of-window history date on Free, 429.
• REST reference: /rates

get_rates_by_base

Returns the same snapshot re-expressed against a base currency other than USD.

• Plan: every plan.
• Inputs:

• Call:

{ "base": "EUR" }

• Returns: base, date, and rates. The base itself is 1 in the map.
• Errors: a missing base is rejected by the MCP server before the API call. An unknown base returns 400 unknown_currency; a missing snapshot returns 404 rate_not_found. An out-of-window date on Free returns 403, and a rate limit returns 429.
• REST reference: /rates/{base}

get_history

Returns a daily (or aggregated) rate series for one currency over a date range.

• Plan: every plan. Free is limited to the last 30 days; Starter and above get full history.
• Inputs:

• Call:

{ "currency": "INR", "base": "USD", "from": "2026-01-01", "to": "2026-11-10", "interval": "monthly" }

• Returns: currency, base, interval, from, to, and rates. rates is a map of bucket to rate. Daily keys are dates; weekly keys are the week’s Monday; monthly keys are YYYY-MM; yearly keys are YYYY.
• Errors: 403 when the range reaches past the Free 30-day window, 404 unknown_currency when no history exists for the currency, 429.
• REST reference: /history

get_ppp_factor

Returns one country’s IMF World Economic Outlook PPP conversion factor for a year.

• Plan: every plan, with an authorized connection.
• Inputs:

• Call:

{ "country": "IND", "year": 2024 }

• Returns: year, countryCode, pppFactor (local currency units per international dollar), and projected (true when the value is an IMF projection rather than actual data).
• Errors: unknown_ppp or 404 when no factor exists for that country and year, 429.
• REST reference: the PPP factor is the keyed /v1/ppp helper. For a consumer conversion with PPP applied, use convert with ppp=true. For multi-year analysis, see PPP analysis.

Analytics tools

These seven tools require Growth or higher. On Free and Starter, the API returns 403 forbidden at call time. The tools stay visible in the client, so an agent can still explain that the organization needs an upgrade.

All seven accept an optional base, default to USD, and return a results array. The window defaults are listed per tool. Dates are UTC.

analyze_history

Summarizes change, strength, and min/max/avg over a window, and can rank every currency as a “movers” list.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "currencies": "EUR,GBP", "base": "USD", "period": "5y", "interval": "yearly" }

• Returns: base, from, to, mode (compare or movers), sort, assetClass, stats, and results. Each result has currency, startRate, endRate, changePct, strengthenedPct, stats (min, max, avg), and series (period to average rate, when interval is set).
• Errors: 403 on Free or Starter, 404 when no data exists at or before the requested start or end date, 429.
• REST reference: /history/analysis

analyze_ppp

Shows how PPP factors changed over time for named countries, or ranks countries by PPP-factor change.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "countries": "IND,DEU,USA", "period": "10y" }

• Returns: from, to, mode, sort, stats, and results. Each result has country, startYear, endYear, startFactor, endFactor, changePct, projected, stats, and series (year to factor, in compare mode).
• Errors: 403 on Free or Starter, 429.
• REST reference: /ppp/analysis

analyze_volatility

Measures annualized volatility for named currencies, or ranks the liquid set by stability.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "currency": "INR,BRL", "base": "USD", "from": "2024-11-10", "to": "2026-11-10" }

• Returns: base, from, to, mode (compare or ranking), sort, basis (annualized-daily), and results. Each result has currency, volatility (annualized percent, or null when there is too little data), and observations.
• Errors: 403 on Free or Starter, 429.
• REST reference: /volatility

analyze_correlation

Measures how closely each named currency’s daily returns move with a base currency.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "base": "EUR", "currencies": "GBP,CHF,SEK", "from": "2025-11-10" }

• Returns: base, from, to, and results. Each result has currency, correlation (Pearson correlation of daily returns, from -1 to 1, or null if undefined), and observations.
• Errors: invalid_input when currencies is missing, 403 on Free or Starter, 429.
• REST reference: /correlation

analyze_drawdown

Finds the maximum peak-to-trough decline for named currencies, or ranks the set by drawdown depth or recovery speed.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "currency": "GBP", "base": "USD", "from": "2008-01-01", "to": "2012-12-31" }

• Returns: base, from, to, mode (compare or ranking), and results. Each result has currency, maxDrawdownPct (signed percent), peakDate, troughDate, recoveryDate (or null if not recovered by to), and recoveryDays (or null).
• Errors: 403 on Free or Starter, 429.
• REST reference: /drawdown

analyze_safe_haven

Ranks currencies by a composite safe-haven score built from volatility, drawdown, and crisis performance.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "currencies": "CHF,JPY", "base": "USD" }

• Returns: base, from, to, crisis (label, from, to), and results. Each result has currency, score (0 to 100, higher is safer, or null), volatility, maxDrawdownPct, and crisisReturnPct (appreciation during the reference crisis).
• Errors: 403 on Free or Starter, 429.
• REST reference: /safe-haven

analyze_mean_reversion

Ranks currencies by how strongly they revert to their mean, using crossing frequency and reversion half-life.

• Plan: Growth or higher.
• Inputs:

• Call:

{ "currencies": "EUR,GBP", "base": "USD" }

• Returns: base, from, to, and results. Each result has currency, score (0 to 100, higher is more mean-reverting, or null), deviationPct (current deviation from the window mean), reversionFrequency (mean crossings per observation, 0 to 1), and halfLifeDays (null when non-reverting).
• Errors: 403 on Free or Starter, 429.
• REST reference: /mean-reversion

Related

• MCP OAuth and access
• MCP troubleshooting
• MCP vs REST
• Errors and retries