treasury-fiscaldata-mcp-server

Get Treasury Exchange Rates

treasury_get_exchange_rates

Read-onlyIdempotent

Official Treasury reporting exchange rates for ~165 countries — the rates US federal agencies are required to use when converting foreign currency to USD for official reporting. Published quarterly (March 31, June 30, Sep 30, Dec 31); mode "latest" returns the most recently published quarter. Rate is expressed as foreign currency units per 1 USD (e.g., a Japan-Yen rate of 159.41 means 1 USD = 159.41 JPY). These are NOT market exchange rates and are not suitable for financial transaction pricing. Mode "series" stages the result as a DataCanvas table when canvas_id is set or the range matches more than 500 rows — read the table's column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	"latest" returns the most recently published quarter's rates. "series" returns a date range of quarterly reports.	latest
`end_date`	No	ISO 8601 end date for mode=series.
`canvas_id`	No	Set any non-empty value to stage mode=series results as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. Staging also happens on its own when a series matches more than 500 rows, which multi-year multi-country pulls do (~19,000 rows for the full history). The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Requires CANVAS_PROVIDER_TYPE=duckdb.
`countries`	No	Filter to specific countries by exact country name (e.g., ["Japan", "Germany", "France"]). Case-sensitive, matches the "country" field. Omit for every country in the quarter (~165).
`start_date`	No	ISO 8601 start date for mode=series. Rates are published end-of-quarter (March 31, June 30, Sep 30, Dec 31).

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The preview cap applied to the inline rates array.
`note`	No	Contextual note reminding that these are official reporting rates, not market rates.
`error`	No	Present when the call failed. Absent on success.
`rates`	No	Exchange rates for the requested countries/quarter, newest first. Whole in mode=latest — a quarter is a bounded set. In mode=series an inline preview of at most 20 rows; compare its length against retrieved_records to detect the cap, and reach the rest through canvas_id when one is returned.
`shown`	No	Rate rows returned inline.
`notice`	No	Guidance when a requested country matched no records, when the inline series is a preview, when the series was staged as a DataCanvas table, or when the returned rows were published in more than one quarter.
`canvas_id`	No	DuckDB table name (df_XXXXX_XXXXX) holding the staged series. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged.
`truncated`	No	True when the inline rates array holds fewer rows than were retrieved.
`as_of_date`	No	Most recent quarter-end record_date among the returned rows (YYYY-MM-DD). Not necessarily a date every row shares — check mixed_record_dates.
`total_records`	No	In mode=latest, the number of rows in rates. In mode=series, the full upstream match — larger than rates.length whenever the preview cap applied, and larger than retrieved_records when paging stopped first.
`effective_date`	No	Effective date of the as_of_date row (YYYY-MM-DD). Every row carries its own effective_date; this one does not describe the rest.
`canvas_expires_at`	No	ISO 8601 expiry for the canvas dataframe.
`retrieved_records`	No	Rows actually fetched for mode=series across every page, and the row count of the canvas table when one was registered. Never larger than total_records.
`mixed_record_dates`	No	True when the retrieved rows were not all published on as_of_date — including rows past the inline preview. Read each row's record_date rather than applying the top-level date to the set.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 20, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `country_not_found`: One or more requested countries have no records — API returns HTTP 200 with empty data[]; total-count is 0 or fewer countries were returned than requested Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `country_not_found`: One or more requested countries have no records — API returns HTTP 200 with empty data[]; total-count is 0 or fewer countries were returned than requested. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "as_of_date",
+      "effective_date",
+      "mixed_record_dates",
+      "rates",
+      "total_records",
+      "note"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `country_not_found`: One or more requested countries have no records — API returns HTTP 200 with empty data[]; total-count is 0 or fewer countries were returned than requested Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "country_not_found"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "as_of_date",
-  "effective_date",
-  "mixed_record_dates",
-  "rates",
-  "total_records",
-  "note"
-]

Changed17 schema fields changedAug 13, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"DataCanvas table name (df_XXXXX_XXXXX) to register series results into for SQL analysis. Useful when pulling multi-year history for many countries (~18,800 rows total). When provided, or when mode=series and results exceed 500 rows, the result is registered and canvas_id is returned. Use treasury_dataframe_query to query it. Requires CANVAS_PROVIDER_TYPE=duckdb."New value: +"Set any non-empty value to stage mode=series results as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. Staging also happens on its own when a series matches more than 500 rows, which multi-year multi-country pulls do (~19,000 rows for the full history). The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Requires CANVAS_PROVIDER_TYPE=duckdb."

changedInput schema / properties / countries / description

Previous value: -"Filter to specific countries by exact country name (e.g., [\"Japan\", \"Germany\", \"France\"]). Case-sensitive, matches the \"country\" field. Omit for all ~130 countries in the quarter."New value: +"Filter to specific countries by exact country name (e.g., [\"Japan\", \"Germany\", \"France\"]). Case-sensitive, matches the \"country\" field. Omit for every country in the quarter (~165)."

changedOutput schema / properties / as_of_date / description

Previous value: -"Quarter-end date of the most recent rates (YYYY-MM-DD)."New value: +"Most recent quarter-end record_date among the returned rows (YYYY-MM-DD). Not necessarily a date every row shares — check mixed_record_dates."

changedOutput schema / properties / canvas_id / description

Previous value: -"DataCanvas table name for series results. Use treasury_dataframe_query to run SQL."New value: +"DuckDB table name (df_XXXXX_XXXXX) holding the staged series. Pass it to treasury_dataframe_describe for the column schema, then use it as the FROM target in treasury_dataframe_query SQL. Absent when nothing was staged."

addedOutput schema / properties / cap

Added value: +{
+  "description": "The preview cap applied to the inline rates array.",
+  "type": "number"
+}

changedOutput schema / properties / effective_date / description

Previous value: -"Effective date of the rates (same as record_date)."New value: +"Effective date of the as_of_date row (YYYY-MM-DD). Every row carries its own effective_date; this one does not describe the rest."

addedOutput schema / properties / mixed_record_dates

Added value: +{
+  "description": "True when the retrieved rows were not all published on as_of_date — including rows past the inline preview. Read each row's record_date rather than applying the top-level date to the set.",
+  "type": "boolean"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when a requested country was not found or returned no records."New value: +"Guidance when a requested country matched no records, when the inline series is a preview, when the series was staged as a DataCanvas table, or when the returned rows were published in more than one quarter."

changedOutput schema / properties / rates / description

Previous value: -"Exchange rates for the requested countries/quarter."New value: +"Exchange rates for the requested countries/quarter, newest first. Whole in mode=latest — a quarter is a bounded set. In mode=series an inline preview of at most 20 rows; compare its length against retrieved_records to detect the cap, and reach the rest through canvas_id when one is returned."

addedOutput schema / properties / rates / items / properties / effective_date

Added value: +{
+  "description": "Date this rate takes effect (YYYY-MM-DD). Later than record_date when Treasury amends a rate mid-quarter, in which case the quarter carries more than one row for the country.",
+  "type": "string"
+}

changedOutput schema / properties / rates / items / properties / record_date / description

Previous value: -"Quarter-end record date (YYYY-MM-DD)."New value: +"Quarter-end record date this rate was published under (YYYY-MM-DD)."

changedOutput schema / properties / rates / items / required

Previous value: -[
-  "country",
-  "currency",
-  "country_currency_desc",
-  "exchange_rate",
-  "record_date"
-]New value: +[
+  "country",
+  "currency",
+  "country_currency_desc",
+  "exchange_rate",
+  "record_date",
+  "effective_date"
+]

addedOutput schema / properties / retrieved_records

Added value: +{
+  "description": "Rows actually fetched for mode=series across every page, and the row count of the canvas table when one was registered. Never larger than total_records.",
+  "type": "number"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Rate rows returned inline.",
+  "type": "number"
+}

changedOutput schema / properties / total_records / description

Previous value: -"Total records returned."New value: +"In mode=latest, the number of rows in rates. In mode=series, the full upstream match — larger than rates.length whenever the preview cap applied, and larger than retrieved_records when paging stopped first."

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the inline rates array holds fewer rows than were retrieved.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "as_of_date",
-  "effective_date",
-  "rates",
-  "total_records",
-  "note"
-]New value: +[
+  "as_of_date",
+  "effective_date",
+  "mixed_record_dates",
+  "rates",
+  "total_records",
+  "note"
+]

First observedJun 3, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly and idempotent annotations, the description discloses important behavior: quarterly publication dates, the exact rate convention (foreign currency per 1 USD), automatic staging for large results, the canvas_id naming behavior, and the CANVAS_PROVIDER_TYPE=duckdb requirement. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense but well organized: core purpose first, then caveats, then mode and staging workflow. Every sentence contributes meaningful guidance without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 5-parameter schema, output schema, and annotations, the description covers all behavior an agent needs: units, publication schedule, staging triggers, downstream analysis steps, and environment requirements. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, and the description adds extra meaning, especially for canvas_id: it explains how the server picks the table name, when staging triggers automatically, and what to do with the returned canvas_id. It also clarifies the scale of a full multi-year pull.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: fetching official Treasury reporting exchange rates for ~165 countries. It clearly distinguishes this tool from market-rate and sibling treasury data tools by its exact domain and required-use context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong usage context: when to use 'latest' vs 'series', when staging occurs, and that the data is not for financial transaction pricing. It also routes to treasury_dataframe_describe and treasury_dataframe_query for series results, but it does not explicitly contrast with siblings like treasury_get_interest_rates or treasury_get_debt.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All treasury-fiscaldata-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.