Tools

Eight tools for working with ECB FX rate data — currency lookup and disambiguation, point-in-time rates and conversions, historical time-series retrieval, and SQL analytics over the DataCanvas workspace that long time-series calls produce. Five are advertised by default; the three fx_dataframe_* tools need CANVAS_PROVIDER_TYPE=duckdb, and the destructive one among them additionally needs FX_ENABLE_CANVAS_DROP=true.

The three fx_dataframe_* tools require DataCanvas. With CANVAS_PROVIDER_TYPE unset (the default) they are not advertised in tools/list at all, so a client never sees a tool it cannot call; the HTTP landing page still lists them as disabled cards hinting CANVAS_PROVIDER_TYPE=duckdb, so operators can tell they exist. In that mode fx_get_timeseries returns every range inline:

fx_list_currencies

Enumerate all supported currencies before converting or querying.

• Returns [{ code, name }] for all ~30 ECB-scoped currencies
• ECB coverage fluctuates as currencies enter/exit scope — always call this tool to validate user-supplied codes rather than hard-coding a list

fx_get_rates

Full rates snapshot for a base currency in one call.

• Returns all available quote currencies at a given date (default: latest)
• Optional symbols parameter narrows the response to specific quote currencies
• Naming the base currency in symbols is valid — it is answered locally with a rate of 1 rather than sent upstream, which keeps a self-quote from failing
• Useful for seeding bulk comparison workflows or discovering what's available

fx_get_rate

Point-in-time exchange rate for a single pair.

• Returns the rate, the actual rate date, and date_snapped: true when the API silently moved a weekend/holiday request to the prior business day
• Cross-rates (neither side EUR) are triangulated in a single API call — no extra round trip
• A same-currency pair returns a rate of 1 without a self-quote reaching the API, but still reports the publication date the ECB actually had for that currency, so rate_date and date_snapped read the same as for any other pair
• Use fx_convert_currency when you need the converted amount; use this tool when you only need the rate number

fx_convert_currency

Convert an amount between any two currencies.

• Handles EUR ↔ any, any ↔ EUR, and cross-rate (USD → JPY via EUR) in one upstream call
• Returns quote_amount, rate, rate_date, date_snapped, plus rate_type and source provenance on every response
• Historical conversions supported back to 1999-01-04 (ECB launch date)

fx_get_timeseries + fx_dataframe_describe / fx_dataframe_query

Historical rate series and DataCanvas SQL analytics.

fx_get_timeseries returns a date-keyed series (business days only — ECB publishes once per business day):

• Short ranges (≤ FX_TIMESERIES_CANVAS_THRESHOLD_DAYS, default 90 days) → inline rates map + metadata
• Long ranges, when DataCanvas is enabled → first N rows inline + canvas_id, table_name, and spilled: true — the full series is registered as a DuckDB-backed table. Without CANVAS_PROVIDER_TYPE=duckdb a long range comes back inline with spilled: false and a notice saying the threshold was crossed but no canvas was configured
• Requesting the same currency on both sides returns a rate of 1 on each publication day in the range, taken from the ECB's real calendar rather than a synthetic Mon–Fri loop

The response never carries a date outside the requested range. Frankfurter snaps a range that opens on a weekend or bank holiday back to the prior publication day; those rows are dropped, so start_date and end_date always sit inside the window you asked for. A range covering only non-publication days therefore returns an empty rates map with rate_count: 0 and a notice explaining that the ECB published nothing in that window — distinguishable from an error.

Once a canvas_id is in hand:

1. fx_dataframe_describe — list the tables and columns on the canvas (required before fx_dataframe_query)
2. fx_dataframe_query — run arbitrary SQL SELECT against the registered table; supports aggregations, GROUP BY, window functions, JOINs across tables from multiple fx_get_timeseries calls

The canvas uses a session-scoped TTL. To continue working with a prior series, call fx_get_timeseries again with the same parameters to obtain a fresh canvas_id.

Resources and prompts

All resource data is also reachable via tools. Use fx_list_currencies or fx_get_rates for programmatic access.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Typed error contracts with recovery hints — unsupported_currency, date_out_of_range, canvas_not_found, missing_table, invalid_query
• Pluggable auth: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

ECB FX–specific: