treasury-fiscaldata-mcp-server

Query Treasury Dataframes

treasury_dataframe_query

Read-onlyIdempotent

Run a single-statement SELECT against DataCanvas dataframes registered by treasury_query_dataset, treasury_get_debt, treasury_get_interest_rates, and treasury_get_exchange_rates. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer. All Treasury dataframe columns are VARCHAR — CAST to DECIMAL or DATE for arithmetic and date comparisons. Use treasury_dataframe_describe to list available table names and column schemas before querying.

Input Schema

TableJSON Schema

Name	Required	Description
`sql`	Yes	Single-statement SELECT against df_<id> tables. All values in Treasury dataframes are VARCHAR (strings) per the API contract — CAST to DECIMAL or DATE for arithmetic and date comparisons. Example: SELECT record_date, CAST(tot_pub_debt_out_amt AS DECIMAL) AS debt FROM df_xxxxx ORDER BY record_date DESC LIMIT 10.
`preview`	No	Rows in the immediate response. Defaults to row_limit and may not exceed it. Set lower when using register_as.
`row_limit`	No	Hard cap on rows the query may produce. Default 1000, max 10000. A query matching more rows than this stops at the cap and row_count_capped comes back true — raise it, or use register_as to materialize the whole result.
`register_as`	No	Persist the result as a new dataframe under this exact name, to chain analyses. The name is used verbatim — any name works, and a df_ prefix keeps it consistent with the tables the data tools mint. Echoed back in registered_as.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The row cap that was applied — preview when supplied, otherwise row_limit.
`rows`	No	Materialized rows, bounded by preview / row_limit.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of rows returned in this response.
`notice`	No	Guidance when the query returned no rows, or when results were capped by preview or row_limit.
`columns`	No	Column names in projection order.
`row_count`	No	Rows the query produced, up to row_limit. Exceeds rows.length when preview returned fewer. Read with row_count_capped: when that is true this number is row_limit itself, and the size of the full result is not in this response.
`truncated`	No	True when the returned rows were capped below the full result set.
`expires_at`	No	ISO 8601 expiry timestamp for the newly registered dataframe, when applicable.
`registered_as`	No	Set when register_as was supplied and the new dataframe was materialized.
`row_count_capped`	No	True when the query matched more rows than row_limit, so row_count is that cap rather than a total. False means row_count is exact — including when it happens to equal row_limit.

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: `canvas_unavailable`: CANVAS_PROVIDER_TYPE is not set to duckdb `system_catalog_access`: SQL references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*) `invalid_sql`: SQL is not a SELECT, contains DDL/DML, or uses disallowed table functions `missing_table`: A df_<id> table named in the SQL is not on the canvas — its TTL expired, it was dropped, or it was never registered `invalid_query_bounds`: preview exceeds row_limit, or row_limit exceeds the row ceiling this server allows Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: CANVAS_PROVIDER_TYPE is not set to duckdb. `system_catalog_access`: SQL references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*). `invalid_sql`: SQL is not a SELECT, contains DDL/DML, or uses disallowed table functions. `missing_table`: A df_<id> table named in the SQL is not on the canvas — its TTL expired, it was dropped, or it was never registered. `invalid_query_bounds`: preview exceeds row_limit, or row_limit exceeds the row ceiling this server allows. 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": [
+      "columns",
+      "row_count",
+      "row_count_capped",
+      "rows"
+    ]
+  },
+  {
+    "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: `canvas_unavailable`: CANVAS_PROVIDER_TYPE is not set to duckdb `system_catalog_access`: SQL references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*) `invalid_sql`: SQL is not a SELECT, contains DDL/DML, or uses disallowed table functions `missing_table`: A df_<id> table named in the SQL is not on the canvas — its TTL expired, it was dropped, or it was never registered `invalid_query_bounds`: preview exceeds row_limit, or row_limit exceeds the row ceiling this server allows Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_unavailable",
+            "system_catalog_access",
+            "invalid_sql",
+            "missing_table",
+            "invalid_query_bounds"
+          ],
+          "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: -[
-  "columns",
-  "row_count",
-  "row_count_capped",
-  "rows"
-]

Changed5 schema fields changedAug 13, 2026

changedInput schema / properties / register_as / description

Previous value: -"Persist result as a new dataframe. Use to chain analyses. The name must match df_XXXXX_XXXXX format or be a fresh df_<id>."New value: +"Persist the result as a new dataframe under this exact name, to chain analyses. The name is used verbatim — any name works, and a df_ prefix keeps it consistent with the tables the data tools mint. Echoed back in registered_as."

changedInput schema / properties / row_limit / description

Previous value: -"Hard cap on rows in the response. Default 1000, max 10000."New value: +"Hard cap on rows the query may produce. Default 1000, max 10000. A query matching more rows than this stops at the cap and row_count_capped comes back true — raise it, or use register_as to materialize the whole result."

changedOutput schema / properties / row_count / description

Previous value: -"Total rows the query produced (may exceed rows.length when capped)."New value: +"Rows the query produced, up to row_limit. Exceeds rows.length when preview returned fewer. Read with row_count_capped: when that is true this number is row_limit itself, and the size of the full result is not in this response."

addedOutput schema / properties / row_count_capped

Added value: +{
+  "description": "True when the query matched more rows than row_limit, so row_count is that cap rather than a total. False means row_count is exact — including when it happens to equal row_limit.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "columns",
-  "row_count",
-  "rows"
-]New value: +[
+  "columns",
+  "row_count",
+  "row_count_capped",
+  "rows"
+]

Changed5 schema fields changedAug 13, 2026

changedInput schema / properties / preview / description

Previous value: -"Rows in the immediate response. Defaults to row_limit. Set lower when using register_as."New value: +"Rows in the immediate response. Defaults to row_limit and may not exceed it. Set lower when using register_as."

addedOutput schema / properties / cap

Added value: +{
+  "description": "The row cap that was applied — preview when supplied, otherwise row_limit.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the query returned no rows, or when results were capped by row_limit."New value: +"Guidance when the query returned no rows, or when results were capped by preview or row_limit."

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of rows returned in this response.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the returned rows were capped below the full result set.",
+  "type": "boolean"
+}

First observedJun 3, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already mark the tool read-only and idempotent, and the description adds concrete enforcement details: writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file functions, and system catalogs are rejected or denied. The VARCHAR-column warning tells the agent how data will behave and what CASTing is needed for arithmetic and date comparisons. No statement contradicts the 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?

Four dense sentences, front-loaded with the core action and followed by restrictions, type caveat, and prerequisite. Every sentence earns its place; there is no fluff or restatement of the title.

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?

The description covers what the tool does, what SQL is permitted, what is denied, the VARCHAR type constraint, and how to discover valid table names. Combined with the rich input schema for row_limit, preview, and register_as, plus the presence of an output schema, an agent has everything needed to invoke the tool correctly.

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 100%, so the schema already documents sql, preview, row_limit, and register_as. The description adds value by directing the agent to treasury_dataframe_describe before querying, which is essential for constructing valid `sql` table names, and by clarifying that tables are DataCanvas dataframes registered by specific tools. It repeats some CAST guidance already present in the sql parameter description, so it is not a full 5.

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?

Opens with a specific verb and resource — 'Run a single-statement SELECT against DataCanvas dataframes' — and names the four registration tools that produce those dataframes. This clearly distinguishes it from treasury_dataframe_describe, which is positioned as the listing counterpart rather than the query tool. The single-statement SELECT restriction removes ambiguity about what kind of SQL this tool accepts.

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?

The description explicitly tells the agent to use treasury_dataframe_describe to discover available table names and schemas before querying, giving a concrete prerequisite. It also states that only SELECT is allowed and lists rejected statement types, which helps the agent avoid invalid calls. It does not explicitly route between this tool and raw-data retrieval tools like treasury_query_dataset, so it stops short of full when-not guidance.

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.