fema-mcp-server

Query FEMA DataCanvas Table

fema_dataframe_query

Read-onlyIdempotent

Run a read-only SQL SELECT against a DataCanvas table staged by fema_search_nfip. Enables aggregation, GROUP BY, SUM/COUNT, time-series, and filtered analysis over the full NFIP claims result without re-fetching from the API. Call fema_dataframe_describe first to get the exact table name and column names needed for valid SQL. Only SELECT statements are allowed — DDL, DML, COPY, and file-reading functions are blocked. A response holds at most 100,000 characters of rows; when it holds fewer rows than the query returned, truncated and shown are set and the notice says how to page with OFFSET.

Input Schema

Name	Required	Description	Default
`query`	Yes	SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Results are capped at the canvas row limit and at 100,000 characters of rows; append LIMIT/OFFSET, under an ORDER BY, to page through additional rows, or aggregate (GROUP BY, COUNT, SUM) to summarize the full set in one query. Example: "SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss"
`canvas_id`	Yes	Canvas ID from the fema_search_nfip response (the canvas_id field).

Output Schema

Name	Required	Description
`cap`	No	The canvas row limit, present only when it capped the result. Absent when only the response budget cut it.
`rows`	No	Result rows from the query, bounded by the canvas row limit and by 100,000 characters of rows — when the truncated enrichment field is set, page the remainder with OFFSET (see the notice guidance).
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of rows in this truncated response — the amount to advance OFFSET by, and to lower any LIMIT by, for the next page.
`notice`	No	Continuation guidance when truncated — how far to advance OFFSET, and lower any LIMIT, under an ORDER BY, to page the remainder.
`canvas_id`	No	Canvas ID that was queried — reuse for follow-up queries.
`row_count`	No	Number of rows in this response — fewer than the query returned when truncated is set.
`truncated`	No	True when more rows match than this response holds: the result was capped at the canvas row limit, or cut at the 100,000-character response budget.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 16, 2026

changedInput schema / properties / query / description

Previous value: -"SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Results are capped at the canvas row limit; append LIMIT/OFFSET to page through additional rows, or aggregate (GROUP BY, COUNT, SUM) to summarize the full set in one query. Example: \"SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss\""New value: +"SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Results are capped at the canvas row limit and at 100,000 characters of rows; append LIMIT/OFFSET, under an ORDER BY, to page through additional rows, or aggregate (GROUP BY, COUNT, SUM) to summarize the full set in one query. Example: \"SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss\""

changedOutput schema / properties / cap / description

Previous value: -"The canvas row limit that was applied when the result was capped."New value: +"The canvas row limit, present only when it capped the result. Absent when only the response budget cut it."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `sql_execution_error`: A SELECT fails while converting or calculating values in the staged data. `canvas_not_found`: The canvas_id does not correspond to an active canvas session. `canvas_unavailable`: DataCanvas is disabled on this deployment (CANVAS_PROVIDER_TYPE is not set to duckdb). `invalid_query`: The SQL statement is not a valid SELECT, references a non-existent table or column, or uses blocked operations. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: DataCanvas is disabled on this deployment (CANVAS_PROVIDER_TYPE is not set to duckdb). `canvas_not_found`: The canvas_id does not correspond to an active canvas session. `missing_table`: The SELECT names a table that is not staged on this canvas — misspelled, dropped, or expired. `invalid_sql`: A SELECT fails to prepare — an unknown column, function, or type, or an invalid expression. `non_select_statement`: The statement is not a SELECT (DDL, DML, PRAGMA, EXPLAIN, ATTACH) or cannot be parsed. `multi_statement`: The query holds more than one SQL statement. `denied_function`: The SELECT calls a blocked function — a file reader, an engine-setting reader, or query()/query_table() over anything but one literal SELECT. `plan_operator_not_allowed`: The query plan uses an operator outside the read-only allowlist, such as a table function like range() or a system catalog like information_schema. `sql_read_only`: The statement writes or names a file, such as COPY … TO or a quoted file path in FROM. `sql_execution_error`: A SELECT fails while converting or calculating values in the staged data. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "sql_execution_error",
-  "canvas_not_found",
-  "canvas_unavailable",
-  "invalid_query"
-]New value: +[
+  "canvas_unavailable",
+  "canvas_not_found",
+  "missing_table",
+  "invalid_sql",
+  "non_select_statement",
+  "multi_statement",
+  "denied_function",
+  "plan_operator_not_allowed",
+  "sql_read_only",
+  "sql_execution_error"
+]

changedOutput schema / properties / notice / description

Previous value: -"Continuation guidance when capped — how to page the remainder with LIMIT/OFFSET."New value: +"Continuation guidance when truncated — how far to advance OFFSET, and lower any LIMIT, under an ORDER BY, to page the remainder."

changedOutput schema / properties / row_count / description

Previous value: -"Number of rows in this response (may be capped at the canvas row limit)."New value: +"Number of rows in this response — fewer than the query returned when truncated is set."

changedOutput schema / properties / rows / description

Previous value: -"Result rows from the query. May be capped at the canvas row limit — when the truncated enrichment field is set, page the remainder with LIMIT/OFFSET (see the notice guidance)."New value: +"Result rows from the query, bounded by the canvas row limit and by 100,000 characters of rows — when the truncated enrichment field is set, page the remainder with OFFSET (see the notice guidance)."

changedOutput schema / properties / shown / description

Previous value: -"Number of rows returned in this (capped) response."New value: +"Number of rows in this truncated response — the amount to advance OFFSET by, and to lower any LIMIT by, for the next page."

changedOutput schema / properties / truncated / description

Previous value: -"True when the result was capped at the canvas row limit — more rows match than were returned."New value: +"True when more rows match than this response holds: the result was capped at the canvas row limit, or cut at the 100,000-character response budget."

Changed3 schema fields changedSep 19, 2026

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `canvas_not_found`: The canvas_id does not correspond to an active canvas session. `canvas_unavailable`: DataCanvas is disabled on this deployment (CANVAS_PROVIDER_TYPE is not set to duckdb). `invalid_query`: The SQL statement is not a valid SELECT, references a non-existent table or column, or uses blocked operations. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `sql_execution_error`: A SELECT fails while converting or calculating values in the staged data. `canvas_not_found`: The canvas_id does not correspond to an active canvas session. `canvas_unavailable`: DataCanvas is disabled on this deployment (CANVAS_PROVIDER_TYPE is not set to duckdb). `invalid_query`: The SQL statement is not a valid SELECT, references a non-existent table or column, or uses blocked operations. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "canvas_not_found",
-  "canvas_unavailable",
-  "invalid_query"
-]New value: +[
+  "sql_execution_error",
+  "canvas_not_found",
+  "canvas_unavailable",
+  "invalid_query"
+]

Changed6 schema fields changedAug 24, 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": [
+      "rows",
+      "row_count",
+      "canvas_id"
+    ]
+  },
+  {
+    "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_not_found`: The canvas_id does not correspond to an active canvas session. `canvas_unavailable`: DataCanvas is disabled on this deployment (CANVAS_PROVIDER_TYPE is not set to duckdb). `invalid_query`: The SQL statement is not a valid SELECT, references a non-existent table or column, or uses blocked operations. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_not_found",
+            "canvas_unavailable",
+            "invalid_query"
+          ],
+          "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: -[
-  "rows",
-  "row_count",
-  "canvas_id"
-]

Changed6 schema fields changedJul 10, 2026

changedInput schema / properties / query / description

Previous value: -"SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Example: \"SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss\""New value: +"SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Results are capped at the canvas row limit; append LIMIT/OFFSET to page through additional rows, or aggregate (GROUP BY, COUNT, SUM) to summarize the full set in one query. Example: \"SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss\""

addedOutput schema / properties / cap

Added value: +{
+  "description": "The canvas row limit that was applied when the result was capped.",
+  "type": "number"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Continuation guidance when capped — how to page the remainder with LIMIT/OFFSET.",
+  "type": "string"
+}

changedOutput schema / properties / rows / description

Previous value: -"All rows returned by the query."New value: +"Result rows from the query. May be capped at the canvas row limit — when the truncated enrichment field is set, page the remainder with LIMIT/OFFSET (see the notice guidance)."

addedOutput schema / properties / shown

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

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the result was capped at the canvas row limit — more rows match than were returned.",
+  "type": "boolean"
+}

First observedJun 7, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only cover safety (readOnly, idempotent, not open-world); the description goes well beyond them by disclosing the SELECT-only enforcement, the 100,000-character row cap, and the truncation contract (truncated/shown flags plus an OFFSET paging notice). These are exactly the operational traits an agent needs before issuing a query.

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 sentences, each carrying distinct information: purpose, prerequisite, restriction, and result-limit contract. The prerequisite is front-loaded right after the purpose rather than buried.

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?

An output schema exists, so return values need no explanation, yet the description still documents the truncation signal and how to page — the one piece of response behavior that affects follow-up calls. For a two-parameter, fully-annotated tool, nothing needed to call it 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, but the description adds real meaning: it explains where canvas_id comes from and why the query string must use the describe-derived table/column names, plus the LIMIT/OFFSET paging pattern tied to the truncation behavior. Much of the query guidance overlaps the schema example, keeping this below a 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?

States a specific verb and resource ('Run a read-only SQL SELECT against a DataCanvas table staged by fema_search_nfip') and ties the table's provenance to a named sibling, so an agent can tell this apart from fema_query_dataset and the fetch tools. The scope (full NFIP claims result without re-fetching) is unambiguous.

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?

Gives an explicit prerequisite ('Call fema_dataframe_describe first to get the exact table name and column names needed for valid SQL') and states the situation that motivates this tool over re-fetching from the API. It also names what is disallowed (DDL, DML, COPY, file-reading functions), which is genuine 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 fema-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.