socrata-mcp-server

Find Socrata Datasets

socrata_find_datasets

Read-onlyIdempotent

Search for datasets across all Socrata-powered government open-data portals, or scope to one portal with the domain parameter. Returns dataset IDs, names, domains, update timestamps, and column_names — the API field names SoQL takes, not display labels. Use socrata_get_dataset to fetch the typed column schema before writing queries — column_names carry no type information.

Input Schema

Name	Required	Description
`only`	No	Filter by asset type. Omit to include all types. Usually "datasets" is what you want.
`tags`	No	Filter by the portal's own tags (e.g. ["covid19", "permits"]). Requires domain: each portal assigns its own tags. Multiple values are ORed: a dataset carrying any listed tag matches. Across portals, search with query instead.
`limit`	No	Number of results to return (1–10,000). One call returns at most 100 results: a larger limit is served as 100, with a notice naming the offset that continues. Default 10.
`order`	No	Sort order. Defaults to relevance. Use updated_at to surface recently-refreshed datasets.
`query`	No	Full-text search across dataset names and descriptions. Omit to browse without filtering.
`domain`	No	Scope search to a single portal by bare hostname (e.g. data.seattle.gov, data.cityofnewyork.us); URL forms like https://data.seattle.gov/ are accepted and reduced to the host. Omit to search all portals. Required with categories or tags.
`offset`	No	Pagination offset. Default 0. Must be below 10,000: the Discovery catalog serves only the first 10,000 matches of a search.
`categories`	No	Filter by the portal's own categories (e.g. ["Public Safety", "Transportation"]). Requires domain: each portal assigns its own categories. Multiple values are ORed: a dataset in any listed category matches. Across portals, search with query instead.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance for this page. When limit was served below the requested value (the 100-result per-call cap or the 10,000-match window), names the served limit and where paging continues; when results are empty, echoes the filters and suggests how to broaden, or, when offset passed the last match, names the offset to page below. Absent otherwise.
`results`	No	Matching datasets. Empty when no results.
`totalCount`	No	Total matches before pagination. 0 when empty. Discovery counts no further than 10,000: when totalCountCapped is true, 10,000 is a lower bound.
`effectiveQuery`	No	Search query applied, for reference.
`totalCountCapped`	No	True when totalCount reached Discovery's 10,000-match count ceiling, so more datasets may match than totalCount says. Absent otherwise.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedNov 4, 2026

changedInput schema / properties / categories / description

Previous value: -"Filter by domain categories (e.g. [\"Public Safety\", \"Transportation\"]). Multiple values are ORed: a dataset in any listed category matches."New value: +"Filter by the portal's own categories (e.g. [\"Public Safety\", \"Transportation\"]). Requires domain: each portal assigns its own categories. Multiple values are ORed: a dataset in any listed category matches. Across portals, search with query instead."

changedInput schema / properties / domain / description

Previous value: -"Scope search to a single portal by bare hostname (e.g. data.seattle.gov, data.cityofnewyork.us); URL forms like https://data.seattle.gov/ are accepted and reduced to the host. Omit to search all portals."New value: +"Scope search to a single portal by bare hostname (e.g. data.seattle.gov, data.cityofnewyork.us); URL forms like https://data.seattle.gov/ are accepted and reduced to the host. Omit to search all portals. Required with categories or tags."

changedInput schema / properties / tags / description

Previous value: -"Filter by tags (e.g. [\"covid19\", \"permits\"]). Multiple values are ORed: a dataset carrying any listed tag matches."New value: +"Filter by the portal's own tags (e.g. [\"covid19\", \"permits\"]). Requires domain: each portal assigns its own tags. Multiple values are ORed: a dataset carrying any listed tag matches. Across portals, search with query instead."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `result_window_exceeded`: offset is 10,000 or more: the Discovery catalog serves only the first 10,000 matches of a search. `rate_limited`: Discovery API returned 429. `unknown_domain`: The Discovery catalog does not index the domain (\"Domain not found\"). `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. `retry_deadline_exceeded`: The Discovery API did not answer within the 50-second time limit the call shares across its requests, retries included. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `domain_required`: categories or tags was sent without domain: both match one portal's own vocabulary, and without domain the catalog matches them against a Socrata-wide taxonomy that portal results do not report. `result_window_exceeded`: offset is 10,000 or more: the Discovery catalog serves only the first 10,000 matches of a search. `rate_limited`: Discovery API returned 429. `unknown_domain`: The Discovery catalog does not index the domain (\"Domain not found\"). `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. `retry_deadline_exceeded`: The Discovery API did not answer within the 50-second time limit the call shares across its requests, retries included. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "result_window_exceeded",
-  "rate_limited",
-  "unknown_domain",
-  "invalid_domain",
-  "retry_deadline_exceeded"
-]New value: +[
+  "domain_required",
+  "result_window_exceeded",
+  "rate_limited",
+  "unknown_domain",
+  "invalid_domain",
+  "retry_deadline_exceeded"
+]

addedOutput schema / properties / results / items / properties / asset_type

Added value: +{
+  "description": "Catalog asset type, such as dataset, filter (a filtered view), map, chart, calendar, visualization, measure, story, href (an external link), federated_href, file. Only dataset and filter answer socrata_query_dataset with rows. Absent when the catalog lists none.",
+  "type": "string"
+}

addedOutput schema / properties / results / items / properties / parent_dataset_ids

Added value: +{
+  "description": "IDs, on the same domain, of the assets this one is built from (Discovery parent_fxf): the table a filter, map, chart, or calendar reads, or every asset a story embeds, charts and maps included. Not every parent is public. Absent when the catalog lists none.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed10 schema fields changedOct 31, 2026

changedInput schema / properties / categories / description

Previous value: -"Filter by domain categories (e.g. [\"Public Safety\", \"Transportation\"])."New value: +"Filter by domain categories (e.g. [\"Public Safety\", \"Transportation\"]). Multiple values are ORed: a dataset in any listed category matches."

changedInput schema / properties / limit / description

Previous value: -"Number of results to return (1–100). Default 10."New value: +"Number of results to return (1–10,000). One call returns at most 100 results: a larger limit is served as 100, with a notice naming the offset that continues. Default 10."

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

changedInput schema / properties / offset / description

Previous value: -"Pagination offset. Default 0."New value: +"Pagination offset. Default 0. Must be below 10,000: the Discovery catalog serves only the first 10,000 matches of a search."

changedInput schema / properties / tags / description

Previous value: -"Filter by tags (e.g. [\"covid19\", \"permits\"])."New value: +"Filter by tags (e.g. [\"covid19\", \"permits\"]). Multiple values are ORed: a dataset carrying any listed tag matches."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `rate_limited`: Discovery API returned 429. `unknown_domain`: The Discovery catalog does not index the domain (\"Domain not found\"). `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `result_window_exceeded`: offset is 10,000 or more: the Discovery catalog serves only the first 10,000 matches of a search. `rate_limited`: Discovery API returned 429. `unknown_domain`: The Discovery catalog does not index the domain (\"Domain not found\"). `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. `retry_deadline_exceeded`: The Discovery API did not answer within the 50-second time limit the call shares across its requests, retries included. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "rate_limited",
-  "unknown_domain",
-  "invalid_domain"
-]New value: +[
+  "result_window_exceeded",
+  "rate_limited",
+  "unknown_domain",
+  "invalid_domain",
+  "retry_deadline_exceeded"
+]

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when results are empty — echoes filters and suggests how to broaden. Absent on non-empty result pages."New value: +"Guidance for this page. When limit was served below the requested value (the 100-result per-call cap or the 10,000-match window), names the served limit and where paging continues; when results are empty, echoes the filters and suggests how to broaden, or, when offset passed the last match, names the offset to page below. Absent otherwise."

changedOutput schema / properties / totalCount / description

Previous value: -"Total matches before pagination. 0 when empty."New value: +"Total matches before pagination. 0 when empty. Discovery counts no further than 10,000: when totalCountCapped is true, 10,000 is a lower bound."

addedOutput schema / properties / totalCountCapped

Added value: +{
+  "description": "True when totalCount reached Discovery's 10,000-match count ceiling, so more datasets may match than totalCount says. Absent otherwise.",
+  "type": "boolean"
+}

Changed4 schema fields changedSep 22, 2026

changedInput schema / properties / domain / description

Previous value: -"Scope search to a single portal (e.g. data.seattle.gov, data.cityofnewyork.us). Omit to search all portals."New value: +"Scope search to a single portal by bare hostname (e.g. data.seattle.gov, data.cityofnewyork.us); URL forms like https://data.seattle.gov/ are accepted and reduced to the host. Omit to search all portals."

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `rate_limited`: Discovery API returned 429. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `rate_limited`: Discovery API returned 429. `unknown_domain`: The Discovery catalog does not index the domain (\"Domain not found\"). `invalid_domain`: The domain is not a hostname, even after dropping a URL scheme, path, or query. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "rate_limited"
-]New value: +[
+  "rate_limited",
+  "unknown_domain",
+  "invalid_domain"
+]

changedOutput schema / properties / results / items / properties / column_names / description

Previous value: -"Preview column name list (no type info). Call socrata_get_dataset for typed schema."New value: +"API field names — the identifiers SoQL takes in select/where/group/order (e.g. cuisine_description), not display labels. Computed-region system columns are dropped; empty when the catalog lists no field names. No type info — call socrata_get_dataset for the typed schema."

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": [
+      "results",
+      "totalCount"
+    ]
+  },
+  {
+    "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: `rate_limited`: Discovery API returned 429. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "rate_limited"
+          ],
+          "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: -[
-  "results",
-  "totalCount"
-]

Changed7 schema fields changedMay 30, 2026

addedOutput schema / properties / effectiveQuery

Added value: +{
+  "description": "Search query applied, for reference.",
+  "type": "string"
+}

removedOutput schema / properties / message

Removed value: -{
-  "description": "Recovery hint when results are empty — echoes filters and suggests how to broaden. Absent on non-empty result pages.",
-  "type": "string"
-}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery hint when results are empty — echoes filters and suggests how to broaden. Absent on non-empty result pages.",
+  "type": "string"
+}

removedOutput schema / properties / query

Removed value: -{
-  "description": "Search query applied, for reference.",
-  "type": "string"
-}

addedOutput schema / properties / totalCount

Added value: +{
+  "description": "Total matches before pagination. 0 when empty.",
+  "type": "number"
+}

removedOutput schema / properties / total_count

Removed value: -{
-  "description": "Total matches before pagination. 0 when empty.",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "results",
-  "total_count"
-]New value: +[
+  "results",
+  "totalCount"
+]

First observedMay 25, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds real behavioral context beyond that: it lists returned fields and warns that column_names are SoQL API field names, not display labels, and carry no type information — a non-obvious gotcha. It omits the 100-result-per-call pagination cap, but the schema already documents that.

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?

Three sentences, zero filler, with the search scope and returned fields front-loaded and the follow-up action placed last where it naturally belongs in a workflow.

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 8 fully documented optional parameters, an output schema, and rich annotations, the description covers the essentials an agent needs to invoke it correctly. The only meaningful omission is the per-call result cap, which the schema handles, leaving this near-complete rather than fully self-contained.

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 description coverage is 100%, so every parameter (including domain, only, categories, tags) is already fully explained in the schema. The description restates domain scoping but adds no syntax or format detail beyond what the schema provides; baseline 3 applies when the schema does the heavy lifting.

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 ('Search for datasets') plus the scope options (all Socrata portals or one via domain). It also enumerates what comes back (dataset IDs, names, domains, update timestamps, column_names) and explicitly names the sibling socrata_get_dataset, so an agent can distinguish it without opening a schema.

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 clear routing guidance: search here, then call socrata_get_dataset before writing queries because column_names lack type information. It does not address when to prefer socrata_list_portals or socrata_query_dataset, so the alternative coverage is partial rather than exhaustive.

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.

Find Socrata Datasets

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources