socrata-mcp-server

Query DataCanvas Table

socrata_dataframe_query

Read-onlyIdempotent

Run SELECT-only SQL against a DataCanvas table populated by socrata_query_dataset. Columns SODA types as number (including aggregate aliases like count(*) as n) are staged as DOUBLE, so numeric comparisons work without a cast (year > 2020, amount < 500). Text and timestamp columns stay VARCHAR — compare times with CAST(date AS TIMESTAMP). Works when the server has a DataCanvas. Use socrata_dataframe_describe to see registered tables and their schemas.

Input Schema

Name	Required	Description
`sql`	Yes	SELECT-only SQL to run against registered canvas tables. DDL, DML, and file-reading functions are rejected. Use table names from socrata_dataframe_describe.
`limit`	No	Max rows to return (1–50,000). One call returns at most 10,000 rows: a larger limit is served as 10,000, with a notice naming how to page through the rest when more rows match. Default 1000.
`canvas_id`	Yes	Canvas ID returned from socrata_query_dataset or socrata_dataframe_describe.

Output Schema

Name	Required	Description
`cap`	No	The row limit that was applied when capped.
`sql`	No	SQL that was executed.
`rows`	No	Query result rows. DuckDB may return native JS types (number, boolean, null) for numeric/boolean columns.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Rows returned in this response when capped.
`notice`	No	Guidance for this page: how to adjust the SQL when it returned zero rows, or how to reach the rest when rows were capped, naming the requested and served limit when a limit above the 10,000-row per-call cap was served as 10,000. Absent otherwise.
`canvas_id`	No	Canvas ID queried.
`row_count`	No	Number of rows returned.
`truncated`	No	True when results were capped at the limit — more rows match the query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 31, 2026

changedInput schema / properties / limit / description

Previous value: -"Max rows to return (1–10000). Default 1000."New value: +"Max rows to return (1–50,000). One call returns at most 10,000 rows: a larger limit is served as 10,000, with a notice naming how to page through the rest when more rows match. Default 1000."

changedInput schema / properties / limit / maximum
```
Previous value: -10000New value: +50000
```

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the SQL returned zero rows. Absent when rows are present."New value: +"Guidance for this page: how to adjust the SQL when it returned zero rows, or how to reach the rest when rows were capped, naming the requested and served limit when a limit above the 10,000-row per-call cap was served as 10,000. Absent otherwise."

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

Changed6 schema fields changedAug 22, 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",
+      "sql",
+      "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_disabled`: CANVAS_PROVIDER_TYPE is not set to duckdb — DataCanvas is unavailable. `canvas_not_found`: canvas_id does not match any registered canvas. `table_not_found`: The SQL referenced a canvas table that does not exist — expired, dropped, or a mistyped name. `sql_rejected`: SQL was not a SELECT statement, referenced a system catalog, or contained disallowed functions. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_disabled",
+            "canvas_not_found",
+            "table_not_found",
+            "sql_rejected"
+          ],
+          "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",
-  "sql",
-  "canvas_id"
-]

Changed3 schema fields changedJun 12, 2026

addedOutput schema / properties / cap

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

addedOutput schema / properties / shown

Added value: +{
+  "description": "Rows returned in this response when capped.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when results were capped at the limit — more rows match the query.",
+  "type": "boolean"
+}

Changed1 schema field changedMay 30, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when the SQL returned zero rows. Absent when rows are present.",
+  "type": "string"
+}

First observedMay 25, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: SODA numeric types are staged as DOUBLE while text/timestamps remain VARCHAR, which determines whether comparisons need CAST. It adds little about failure modes or the row-cap/paging behavior, which the schema already carries.

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 compact sentences, front-loaded with purpose, then the type-staging rule that most affects query authoring, then the environment precondition and discovery pointer. No redundant restatement of the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema and fully described parameters, the description only needs to supply the type-system and environment context, which it does. The main gap is lifecycle: nothing says whether the canvas persists between calls or how it relates to prior socrata_query_dataset runs.

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 baseline is 3, but the description adds real semantic guidance for the sql parameter: which column types allow bare numeric comparison and which require CAST(date AS TIMESTAMP). That is meaning an agent would not get from the schema alone.

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 SELECT-only SQL against a DataCanvas table") and ties the table back to socrata_query_dataset, which distinguishes it from the SODA query sibling. An agent can tell this is an analytics step over staged data, not a dataset fetch.

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?

Gives a clear precondition ("Works when the server has a DataCanvas") and routes the agent to socrata_dataframe_describe to discover registered tables. It does not explicitly state when to prefer this over socrata_query_dataset or what to do when no canvas exists, so it stops short of full when/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 socrata-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.