Tools

Five tools for querying the US Treasury Fiscal Data API, plus two for SQL analytics over DuckDB-backed DataCanvas dataframes:

treasury_list_datasets

Browse the embedded catalog of available Treasury Fiscal Data endpoints. No network calls — serves from a static catalog bundled with the server.

• Filter by category: debt, interest_rates, exchange_rates, revenue_spending, savings_bonds, securities, other
• Keyword search against dataset name and description (case-insensitive substring)
• Returns endpoint paths, field names, types, and update cadence
• Use this first to get the exact endpoint path and field names before calling treasury_query_dataset
• Every path and field name is checked against the live API by bun run verify:catalog, so a dataset Treasury moves or renames fails a gate rather than reaching a caller

treasury_query_dataset

Generic parameterized query against any Treasury Fiscal Data endpoint.

• Filter syntax: { field, operator, value } where operator is eq, gt, gte, lt, lte, in
• Multiple filters ANDed together
• Pagination via page_size (1–10000) and page_number
• Sort by any field, descending with - prefix (e.g. -record_date)
• All response values are strings per the API contract — including numeric and date fields; "null" means no value
• Pass canvas_id to stage the page as a DataCanvas table — the server assigns the name and returns it in canvas_id; read its schema with treasury_dataframe_describe, then SQL it with treasury_dataframe_query (requires CANVAS_PROVIDER_TYPE=duckdb)

treasury_get_debt

Convenience tool for national debt (Debt to the Penny) — total public debt outstanding broken into publicly-held debt and intragovernmental holdings.

• mode=latest — most recent business-day record
• mode=date — specific business day (YYYY-MM-DD; API only records debt on market-open days)
• mode=series — date range, sorted newest-first; auto-spills to DataCanvas when the series exceeds 500 rows
• Records go back to 1993-04-01

treasury_get_interest_rates

Average interest rates the Treasury pays on outstanding securities. Updated monthly (end-of-month records).

• Covers every security type Treasury reports — marketable issues, non-marketable series, and aggregate totals
• security_type takes any security_desc value the data carries, matched exactly; which types Treasury publishes changes over the years, so when a filter matches nothing the response names the types the data does hold
• mode=latest — most recent month's rates for all or one security type
• mode=series — time-range history; auto-spills to DataCanvas when results exceed 200 rows

treasury_get_exchange_rates

Official Treasury statutory reporting exchange rates for ~165 countries, published quarterly (March 31, June 30, Sep 30, Dec 31).

• Rate expressed as foreign currency units per 1 USD (a Japan-Yen rate of 159.41 means 1 USD = 159.41 JPY)
• These are not market exchange rates — required by US federal agencies for foreign-currency-to-USD conversions in official reporting
• Filter to one or more countries by exact name; omit for every country in a quarter
• mode=latest returns one row per currency — the operative rate, newest record_date and then newest effective_date, so an amended rate supersedes the one it replaced and a country holding two legal tenders keeps both
• Treasury amends a published quarter by reissuing a rate under the same record_date with a later effective_date, so both dates ride every row; mixed_record_dates flags a result whose rows are not all from one quarter
• mode=series auto-spills to DataCanvas when results exceed 500 rows (~19,000 rows full history, back to 2001-03-31)

treasury_dataframe_describe / treasury_dataframe_query

In-conversation SQL analytics over the dataframes that treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates materialize on a shared DuckDB-backed DataCanvas. Each data-returning call with canvas_id adds a df_XXXXX_XXXXX handle; read its columns with treasury_dataframe_describe, then pass the handle to treasury_dataframe_query for joins, aggregates, window functions, and CTEs — standard DuckDB SQL.

• Read-only. Writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected by the SQL gate. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer.
• All Treasury columns are VARCHAR. CAST to DECIMAL or DATE for arithmetic and date comparisons.
• register_as chaining. treasury_dataframe_query can persist its result as a new dataframe with a fresh TTL for multi-step analysis.
• Per-table TTL. Dataframes age on their own clock (default 24h, override with CANVAS_TTL_MS).
• Requires CANVAS_PROVIDER_TYPE=duckdb.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Structured output schemas with automatic formatting for human-readable display
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Structured logging with request-scoped context
• STDIO and Streamable HTTP transports

Treasury-specific:

• Curated catalog of 17 Treasury Fiscal Data endpoints with field metadata — no discovery round-trip required. Pass any endpoint path directly to treasury_query_dataset to access datasets not in the catalog.
• Convenience tools for the three most-queried datasets (national debt, interest rates, exchange rates)
• Full generic access to any Fiscal Data endpoint via treasury_query_dataset
• DataCanvas integration: large time-series pulls register as df_<id> dataframes queryable via DuckDB SQL
• No API keys required — the US Treasury Fiscal Data API is free and public

Agent-friendly output: