exchange-rates-mcp-server

List all supported ISO 4217 currency codes with their full names. Call this before converting to disambiguate "dollars" (USD vs AUD vs CAD vs HKD vs SGD) or to validate a user-supplied currency code. Covers the ~30 ECB reference currencies.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "currencies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "ISO 4217 currency code (e.g. USD, EUR, JPY)."
          },
          "name": {
            "type": "string",
            "description": "Full currency name (e.g. \"United States Dollar\")."
          }
        },
        "required": [
          "code",
          "name"
        ],
        "additionalProperties": false,
        "description": "A single supported currency."
      },
      "description": "All supported currencies, sorted alphabetically by code."
    },
    "count": {
      "type": "number",
      "description": "Total number of supported currencies."
    },
    "source": {
      "type": "string",
      "description": "Always \"ECB via Frankfurter\" — the upstream data provider."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode."
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "currencies",
        "count",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Get all available exchange rates for one base currency in a single snapshot. Useful for bulk comparison and seeding downstream tools. Returns a map of quote currency → rate, the actual snapshot date, and whether a historical date was snapped from a weekend/holiday to the prior business day. Optionally filter to a subset of quote currencies via symbols. Listing the base currency itself in symbols is accepted and returns a rate of 1 for it.

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.",
      "type": "string"
    },
    "symbols": {
      "description": "Optional list of quote currency codes to filter the response. When provided, must contain at least one currency code — omit the field entirely, not an empty array, to return all ~30 supported currencies (the base is not among them). Including base_currency here is valid — it comes back with a rate of 1.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "description": "ISO 4217 currency code to include in the response."
      }
    }
  },
  "required": [
    "base_currency"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "The base currency code."
    },
    "rate_date": {
      "type": "string",
      "description": "Actual date of the rates. May differ from requested date on weekends/holidays — ECB publishes business days only; the API silently snaps to the prior business day."
    },
    "rates": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      },
      "description": "Map of quote currency code → exchange rate (units of quote per 1 base)."
    },
    "date_snapped": {
      "type": "boolean",
      "description": "True when the API returned a different date than requested — ECB silently snaps weekend/holiday requests to the prior business day. Always false when date is omitted."
    },
    "rate_type": {
      "type": "string",
      "description": "Always \"ECB reference (mid-market)\" — these are reference rates, not tradeable bid/ask."
    },
    "source": {
      "type": "string",
      "description": "Always \"ECB via Frankfurter\" — the upstream data provider."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_date_format`: date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or an entry in symbols is not in the ECB currency set. `date_out_of_range`: date is before 1999-01-04 or in the future. `upstream_no_data`: Every requested currency is supported but the ECB published no rates for this date. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_date_format",
                "unsupported_currency",
                "date_out_of_range",
                "upstream_no_data"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "base_currency",
        "rate_date",
        "rates",
        "date_snapped",
        "rate_type",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Get the exchange rate for a currency pair on a given date (default: latest). Returns the rate, the actual rate date (which may differ from the requested date on weekends/holidays — ECB publishes business days only), and source provenance. Cross-rates are triangulated through EUR automatically. A same-currency pair returns a rate of 1, dated to the same publication day any other pair would report for that date. Use fx_convert_currency when you want the converted amount; use this tool when you only need the rate number.

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "quote_currency": {
      "type": "string",
      "description": "ISO 4217 quote currency code (e.g. EUR). The rate is expressed as \"how many quote units per 1 base unit\". Call fx_list_currencies to get valid codes."
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.",
      "type": "string"
    }
  },
  "required": [
    "base_currency",
    "quote_currency"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "The base currency code."
    },
    "quote_currency": {
      "type": "string",
      "description": "The quote currency code."
    },
    "rate": {
      "type": "number",
      "description": "Exchange rate: units of quote currency per 1 unit of base currency."
    },
    "rate_date": {
      "type": "string",
      "description": "Actual date of the rate returned."
    },
    "date_snapped": {
      "type": "boolean",
      "description": "True when the API returned a different date than requested — ECB silently snaps weekend/holiday requests to the prior business day."
    },
    "rate_type": {
      "type": "string",
      "description": "Always \"ECB reference (mid-market)\" — these are reference rates, not tradeable bid/ask."
    },
    "source": {
      "type": "string",
      "description": "Always \"ECB via Frankfurter\" — the upstream data provider."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_date_format`: date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or quote_currency is not in the ECB currency set. `date_out_of_range`: date is before 1999-01-04 or in the future. `upstream_no_data`: Both currencies are supported but the ECB published no rate for this date. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_date_format",
                "unsupported_currency",
                "date_out_of_range",
                "upstream_no_data"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "base_currency",
        "quote_currency",
        "rate",
        "rate_date",
        "date_snapped",
        "rate_type",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Convert an amount between any two currencies at the latest or a historical rate. Returns the converted amount, the rate used, the actual rate date, and whether the date was snapped from a weekend/holiday to the prior business day. Cross-rates are triangulated through EUR automatically.

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 source currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "quote_currency": {
      "type": "string",
      "description": "ISO 4217 target currency code (e.g. EUR). The amount will be expressed in this currency. Call fx_list_currencies to get valid codes."
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "Amount in the base currency to convert. Must be greater than zero."
    },
    "date": {
      "description": "ISO 8601 date (YYYY-MM-DD) for a historical rate. Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.",
      "type": "string"
    }
  },
  "required": [
    "base_currency",
    "quote_currency",
    "amount"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "Source currency code."
    },
    "quote_currency": {
      "type": "string",
      "description": "Target currency code."
    },
    "base_amount": {
      "type": "number",
      "description": "The input amount in the base currency."
    },
    "quote_amount": {
      "type": "number",
      "description": "The converted amount in the quote currency, rounded to 6 decimal places."
    },
    "rate": {
      "type": "number",
      "description": "Exchange rate used: units of quote currency per 1 unit of base currency."
    },
    "rate_date": {
      "type": "string",
      "description": "Actual date of the rate used for conversion."
    },
    "date_snapped": {
      "type": "boolean",
      "description": "True when the API returned a different date than requested — ECB silently snaps weekend/holiday requests to the prior business day."
    },
    "rate_type": {
      "type": "string",
      "description": "Always \"ECB reference (mid-market)\" — these are reference rates, not tradeable bid/ask."
    },
    "source": {
      "type": "string",
      "description": "Always \"ECB via Frankfurter\" — the upstream data provider."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_date_format`: date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or quote_currency is not in the ECB currency set. `date_out_of_range`: date is before 1999-01-04 or in the future. `upstream_no_data`: Both currencies are supported but the ECB published no rate for this date. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_date_format",
                "unsupported_currency",
                "date_out_of_range",
                "upstream_no_data"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "base_currency",
        "quote_currency",
        "base_amount",
        "quote_amount",
        "rate",
        "rate_date",
        "date_snapped",
        "rate_type",
        "source"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Get historical daily exchange rates for a currency pair over a date range. ECB publishes on business days only — weekends and holidays produce no entry, and no date outside the requested range is ever returned, so a range covering only non-publication days comes back with an empty rates map and a notice explaining why. A same-currency pair returns a rate of 1 on each publication day in the range. Inline results are returned as a date→rate map paged at 500 publication days: rate_count is always the total for the requested range, and when a page is cut short the response carries truncated=true and next_start_date — call again with start_date set to next_start_date and the same end_date for the next page. When DataCanvas is enabled (CANVAS_PROVIDER_TYPE=duckdb) long ranges (>90 days by default) spill to it instead: the response carries spilled=true, a canvas_id, and a table_name — call fx_dataframe_describe to inspect the staged table, then fx_dataframe_query to run SQL against it. Without DataCanvas long ranges are paged inline (spilled=false) and the notice says so.

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes."
    },
    "quote_currency": {
      "type": "string",
      "description": "ISO 4217 quote currency code (e.g. EUR). Call fx_list_currencies to get valid codes."
    },
    "start_date": {
      "type": "string",
      "description": "ISO 8601 start date (YYYY-MM-DD). ECB data starts 1999-01-04. The actual first data point may be later if start_date falls on a weekend/holiday."
    },
    "end_date": {
      "type": "string",
      "description": "ISO 8601 end date (YYYY-MM-DD). Must be >= start_date. Future dates are not supported."
    },
    "canvas_id": {
      "description": "Optional canvas ID from a prior call. Omit on the first call to start a fresh canvas; pass the returned canvas_id to append tables to an existing canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "base_currency",
    "quote_currency",
    "start_date",
    "end_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "base_currency": {
      "type": "string",
      "description": "Base currency code."
    },
    "quote_currency": {
      "type": "string",
      "description": "Quote currency code."
    },
    "start_date": {
      "type": "string",
      "description": "First publication date in the requested range, and the first key in rates. Always inside the requested range — later than the requested start when that day had no ECB fix, and equal to it when the series is empty."
    },
    "end_date": {
      "type": "string",
      "description": "Last publication date in the requested range. Always inside the requested range — earlier than the requested end when that day had no ECB fix, and equal to it when the series is empty. Later than the last key in rates when truncated is true."
    },
    "rates": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "number"
      },
      "description": "Date → rate map in date order, publication days inside the requested range only. Holds every publication day when truncated is false; otherwise the first 500 of an inline page (continue with next_start_date) or the preview of a spilled series (the full series is on the canvas). Empty when the range contains no publication day at all."
    },
    "rate_count": {
      "type": "number",
      "description": "Total publication days in the requested range (the start_date through end_date passed on this call) — not the number of entries in rates, which is smaller when truncated is true. On a continuation call it counts the days from that start_date onward."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when rates holds only part of the series: an inline page (next_start_date continues it) or a spilled preview (spilled is true). False when rates holds every publication day in the requested range."
    },
    "next_start_date": {
      "description": "Present only when an inline page was cut short: the first publication date not in rates. Pass it as start_date with the same end_date to get the next page. Absent on the final page.",
      "type": "string"
    },
    "rate_type": {
      "type": "string",
      "description": "Always \"ECB reference (mid-market)\" — these are reference rates, not tradeable bid/ask."
    },
    "source": {
      "type": "string",
      "description": "Always \"ECB via Frankfurter\" — the upstream data provider."
    },
    "spilled": {
      "type": "boolean",
      "description": "True when the full result was staged on the DataCanvas (range exceeded threshold)."
    },
    "canvas_id": {
      "description": "Canvas ID — present when spilled is true. Pass to fx_dataframe_describe to inspect the staged table, then to fx_dataframe_query to run SQL.",
      "type": "string"
    },
    "table_name": {
      "description": "Canvas table name — present when spilled is true. Use it as the FROM target in fx_dataframe_query SQL; fx_dataframe_describe lists its columns.",
      "type": "string"
    },
    "notice": {
      "description": "Explains a result that would otherwise look broken or incomplete: an empty series (no publication day in the range); an inline page cut short (the start_date to continue from, plus why a long range was not staged when DataCanvas is not configured); or a spilled series (the canvas and table it was staged to, and the tools that read it).",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_date_format`: start_date or end_date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or quote_currency is not in the ECB currency set. `date_out_of_range`: start_date is before 1999-01-04 or end_date is in the future. `invalid_range`: start_date is after end_date. `upstream_no_data`: Both currencies are supported but the ECB published no rates across this range. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_date_format",
                "unsupported_currency",
                "date_out_of_range",
                "invalid_range",
                "upstream_no_data"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "base_currency",
        "quote_currency",
        "start_date",
        "end_date",
        "rates",
        "rate_count",
        "truncated",
        "rate_type",
        "source",
        "spilled"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

List tables and columns staged on a DataCanvas from a prior fx_get_timeseries call. Required first step before fx_dataframe_query — use it to discover table names and column schemas. Requires DataCanvas (CANVAS_PROVIDER_TYPE=duckdb) — without it this tool is not listed at all and fx_get_timeseries returns every range inline.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "description": "The canvas ID echoed back — use this in fx_dataframe_query."
    },
    "tables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Table or view name."
          },
          "kind": {
            "type": "string",
            "description": "Either \"table\" or \"view\"."
          },
          "row_count": {
            "type": "number",
            "description": "Number of rows in this table or view."
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Column name."
                },
                "type": {
                  "type": "string",
                  "description": "DuckDB column type (e.g. VARCHAR, DOUBLE, BIGINT)."
                },
                "nullable": {
                  "type": "boolean",
                  "description": "Whether the column accepts NULL values."
                }
              },
              "required": [
                "name",
                "type",
                "nullable"
              ],
              "additionalProperties": false,
              "description": "A single column descriptor."
            },
            "description": "Column schema for this table."
          }
        },
        "required": [
          "name",
          "kind",
          "row_count",
          "columns"
        ],
        "additionalProperties": false,
        "description": "A single table or view staged on the canvas."
      },
      "description": "All tables and views currently staged on this canvas."
    },
    "expires_at": {
      "type": "string",
      "description": "ISO 8601 timestamp when this canvas will be evicted."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not exist or has been evicted. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "canvas_id",
        "tables",
        "expires_at"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Run a read-only SQL SELECT against DataCanvas tables staged by fx_get_timeseries. Supports aggregations, GROUP BY, window functions, and JOINs across multiple registered tables. Run fx_dataframe_describe first to discover table names and column schemas. Requires DataCanvas (CANVAS_PROVIDER_TYPE=duckdb) — without it this tool is not listed at all and fx_get_timeseries returns every range inline.

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired."
    },
    "query": {
      "type": "string",
      "description": "Read-only SQL SELECT statement. Reference tables by the names returned by fx_dataframe_describe or the table_name field from fx_get_timeseries. Example: SELECT date, rate FROM fx_usd_eur WHERE date > '2024-01-01' ORDER BY date"
    },
    "row_limit": {
      "default": 150,
      "description": "Most rows to return (1–10000, default 150). When the query produces more, truncated is true — page with ORDER BY <column> LIMIT <n> OFFSET <m> in the SQL, or aggregate, rather than raising this toward the maximum.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "canvas_id",
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {},
        "description": "One result row — column-name → value pairs matching the SELECT columns."
      },
      "description": "Result rows, at most row_limit (default 150). Each key is a column name from the query."
    },
    "row_count": {
      "type": "number",
      "description": "Rows returned — always the length of rows. When truncated is true this equals row_limit, not the full result size."
    },
    "truncated": {
      "type": "boolean",
      "description": "True when the query produced more rows than row_limit and rows holds only the first row_limit of them. Fetch the rest with ORDER BY <column> LIMIT <n> OFFSET <m> — ORDER BY is required for deterministic paging — or aggregate to shrink the result."
    },
    "canvas_id": {
      "type": "string",
      "description": "The canvas ID used — pass to a subsequent fx_dataframe_query or fx_dataframe_describe call."
    },
    "notice": {
      "description": "Present when truncated is true: how many rows came back and the ORDER BY … LIMIT … OFFSET query shape that fetches the next page.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not exist or has been evicted. `missing_table`: The SQL references a table that is not staged on this canvas, or whose TTL expired. `invalid_query`: SQL is not a SELECT, references unknown columns, or has a syntax error. Other values are possible when a failure originates below the handler.",
              "examples": [
                "canvas_not_found",
                "missing_table",
                "invalid_query"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "rows",
        "row_count",
        "truncated",
        "canvas_id"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}