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.

Input Schema

TableJSON 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; 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"
`canvas_id`	Yes	Canvas ID from the fema_search_nfip response (the canvas_id field).

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The canvas row limit that was applied when the result was capped.
`rows`	No	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).
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of rows returned in this (capped) response.
`notice`	No	Continuation guidance when capped — how to page the remainder with LIMIT/OFFSET.
`canvas_id`	No	Canvas ID that was queried — reuse for follow-up queries.
`row_count`	No	Number of rows in this response (may be capped at the canvas row limit).
`truncated`	No	True when the result was capped at the canvas row limit — more rows match than were returned.

Schema Changelog

Changes observed during successful MCP inspections.

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.5/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the description's note about only SELECT is consistent and adds value by specifying blocked operations. Also discloses row capping and suggests LIMIT/OFFSET or aggregation to handle full data, which is beyond the schema.

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?

Concise yet comprehensive. The description is front-loaded with purpose, followed by usage prerequisite and safety constraints. No redundant information—every sentence adds value.

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 output schema exists and schema covers parameters, the description is complete: it identifies the source table, explains how to get column names, demonstrates example usage, and warns about blocking. An agent has all needed to invoke correctly.

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

Parameters3/5

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

Schema coverage is 100%, so description doesn't need to add much. It provides examples and explains how to use query (e.g., table name from describe, aggregation patterns), but largely reinforces schema descriptions. Slight value add with example.

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?

Clear verb (Run), resource (DataCanvas table), and scope (read-only SQL SELECT, aggregation, etc.). Distinguishes from siblings by explicitly referencing the staging process and naming fema_dataframe_describe as a prerequisite.

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?

Explicit when to use (for analysis on NFIP claims without API re-fetch), and provides a concrete alternative/sequential tool (fema_dataframe_describe) to get table/column names. Also states what is blocked (DDL, DML, COPY, file-reading), guiding safe usage.

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.