treasury-fiscaldata-mcp-server

Query Treasury Fiscal Data Dataset

treasury_query_dataset

Read-onlyIdempotent

Query any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page. Call treasury_list_datasets first to get the correct endpoint path and exact field names — a typo in either causes a 400. Filter syntax: each condition is { field, operator, value } where operator is eq/gt/gte/lt/lte/in (e.g., record_date:gte:2024-01-01). Multiple conditions are ANDed together. All response values are strings per the API contract, including numbers and dates; "null" (string) means no value. Supply canvas_id to stage the page result as a DataCanvas table — read its column schema with treasury_dataframe_describe, then run SQL over it with treasury_dataframe_query (requires CANVAS_PROVIDER_TYPE=duckdb on the server).

Input Schema

TableJSON Schema

Name	Required	Description
`sort`	No	Sort expression: field name optionally prefixed with "-" for descending (e.g., "-record_date" for newest-first).
`fields`	No	Fields to return. Omit to return all fields. Specify field names exactly as listed by treasury_list_datasets — a typo causes a 400.
`filters`	No	Filter conditions (ANDed together). Multiple filters on different fields are combined in one filter= parameter.
`endpoint`	Yes	Endpoint path returned by treasury_list_datasets (e.g., "/v2/accounting/od/debt_to_penny"). Include the leading slash.
`canvas_id`	No	Set any non-empty value to stage this page as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Omit to receive results inline only. Requires CANVAS_PROVIDER_TYPE=duckdb on the server.
`page_size`	No	Rows per page. Default 100. Raise to 10000 to minimize round trips for small datasets. For large time-series pulls, use canvas_id with treasury_dataframe_query instead.
`page_number`	No	Page to fetch (1-indexed). Check total_pages in the response to know if more pages exist.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	No	Rows returned. All values are strings per API contract — including numeric and date fields. Convert in the calling context. Null values appear as the string "null".
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when results are empty, a field typo is suspected, the endpoint was not found in the catalog, or staging was requested.
`endpoint`	No	Endpoint that was queried.
`canvas_id`	No	DuckDB table name (df_XXXXX_XXXXX) holding this page. 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.
`page_size`	No	Rows per page.
`totalCount`	No	Total rows matching the query across all pages — discloses that this page is a subset.
`page_number`	No	Current page (1-indexed).
`total_count`	No	Total rows matching the query (across all pages).
`total_pages`	No	Total pages at the current page_size.
`field_labels`	No	Human-readable label for each returned field.
`applied_filters`	No	Filter expression sent to the API, for verification.
`canvas_expires_at`	No	ISO 8601 expiry for the canvas dataframe.

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: `invalid_endpoint`: The endpoint path does not exist (API returns 404 HTML) `invalid_field`: A field name in fields= or filter= does not exist on this endpoint — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Field 'X' does not exist...\"} `invalid_filter`: The filter expression uses an unsupported operator — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Operator ':op:' is not supported...\"} `page_out_of_range`: page_number is past the last page of the matched set — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Page #N is out of range...\"} Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_endpoint`: The endpoint path does not exist (API returns 404 HTML). `invalid_field`: A field name in fields= or filter= does not exist on this endpoint — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Field 'X' does not exist...\"}. `invalid_filter`: The filter expression uses an unsupported operator — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Operator ':op:' is not supported...\"}. `page_out_of_range`: page_number is past the last page of the matched set — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Page #N is out of range...\"}. Other values are possible when a failure originates below the handler."

Changed7 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
```
addedInput schema / properties / filters / items / 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": [
+      "endpoint",
+      "data",
+      "total_count",
+      "total_pages",
+      "page_number",
+      "page_size",
+      "field_labels"
+    ]
+  },
+  {
+    "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: `invalid_endpoint`: The endpoint path does not exist (API returns 404 HTML) `invalid_field`: A field name in fields= or filter= does not exist on this endpoint — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Field 'X' does not exist...\"} `invalid_filter`: The filter expression uses an unsupported operator — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Operator ':op:' is not supported...\"} `page_out_of_range`: page_number is past the last page of the matched set — API returns JSON {\"error\":\"Invalid Query Param\",\"message\":\"...Page #N is out of range...\"} Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_endpoint",
+            "invalid_field",
+            "invalid_filter",
+            "page_out_of_range"
+          ],
+          "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: -[
-  "endpoint",
-  "data",
-  "total_count",
-  "total_pages",
-  "page_number",
-  "page_size",
-  "field_labels"
-]

Changed4 schema fields changedAug 13, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"DataCanvas ID to spill results into for SQL analysis. Omit to receive results inline. Requires CANVAS_PROVIDER_TYPE=duckdb on the server. When provided, the full page result is registered as a dataframe and a canvas_id is returned for use with treasury_dataframe_query."New value: +"Set any non-empty value to stage this page as a DataCanvas table for SQL analysis — the value only requests staging; the server picks the table name. The assigned name (df_XXXXX_XXXXX) comes back in the output canvas_id; pass it to treasury_dataframe_describe, then treasury_dataframe_query. Omit to receive results inline only. Requires CANVAS_PROVIDER_TYPE=duckdb on the server."

changedInput schema / properties / filters / items / properties / value / anyOf

Previous value: -[
-  {
-    "description": "Single filter value. Dates use YYYY-MM-DD format.",
-    "type": "string"
-  },
-  {
-    "description": "List of values for \"in\" operator.",
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "description": "Single filter value. Dates use YYYY-MM-DD format.",
+    "minLength": 1,
+    "type": "string"
+  },
+  {
+    "description": "List of values for \"in\" operator.",
+    "items": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "minItems": 1,
+    "type": "array"
+  }
+]

changedOutput schema / properties / canvas_id / description

Previous value: -"DataCanvas ID where this page is registered. Use with treasury_dataframe_query to run SQL."New value: +"DuckDB table name (df_XXXXX_XXXXX) holding this page. 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."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when results are empty, a field typo is suspected, or the endpoint was not found in the catalog."New value: +"Guidance when results are empty, a field typo is suspected, the endpoint was not found in the catalog, or staging was requested."

Changed1 schema field changedJun 13, 2026

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total rows matching the query across all pages — discloses that this page is a subset.",
+  "type": "number"
+}

First observedJun 3, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses that typos cause a 400, that all response values are strings including dates and numbers, that 'null' (string) means no value, that multiple filters are ANDed, and that canvas staging is server-side with a generated table name. This is substantive behavioral context well above the annotation baseline.

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

Conciseness4/5

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

The description is dense and logically ordered: core action, prerequisite, filter syntax, response semantics, staging workflow. It is longer than minimal but every section earns its place, with only minor redundancy against schema details like the typo warning.

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 rich schema, output schema, and annotations, the description covers the full operational flow: prerequisites, parameter semantics, response quirks, and the downstream DataCanvas path. Nothing an agent needs to call this tool correctly 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 100%, so the baseline is 3. The description adds filter operator syntax with an example (record_date:gte:2024-01-01), explains AND semantics, and clarifies that 'null' is a string, adding value beyond the schema while not carrying the full burden.

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 opens with a specific verb and resource: 'Query any Treasury Fiscal Data endpoint by path, field list, filters, sort, and page.' It clearly distinguishes this tool from treasury_list_datasets (which discovers endpoints) and treasury_dataframe_describe/query (which operate on staged DataCanvas tables).

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

Usage Guidelines5/5

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

It gives an explicit prerequisite: 'Call treasury_list_datasets first to get the correct endpoint path and exact field names.' It also routes large pulls to the DataCanvas workflow with treasury_dataframe_queryhol, explicitly naming the alternative and the condition for choosing it.

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.