socrata-mcp-server

List Socrata Portals

socrata_list_portals

Read-onlyIdempotent

List known Socrata-powered government open-data portals with their domain, organization name, and approximate dataset count. The catalog is a curated list of 39 well-known portals; dataset counts are fetched from the Discovery API and cached for ~24 hours. Filtering is client-side substring match on the query parameter. Use this first when you do not know which portal to target, then pass the domain to socrata_find_datasets.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Max portals to return (1–200). Default 50.
`query`	No	Keyword to filter portal names or organization names (case-insensitive substring match). Omit to list all portals.
`offset`	No	Pagination offset. Default 0.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Recovery hint when no portals matched the filter. Absent on non-empty pages.
`portals`	No	Matching portals. Empty when no results.
`totalCount`	No	Total portals before pagination. 0 when empty.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 22, 2026

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."

removedOutput schema / properties / error / properties / data / properties / reason / examples
```
Removed value: -[
-  "rate_limited"
-]
```

Changed2 schema fields changedSep 20, 2026
- removedOutput schema / properties / portals / items / properties / dataset_count / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / portals / items / properties / dataset_count / type
```
Added value: +[
+  "number",
+  "null"
+]
```

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": [
+      "portals",
+      "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: -[
-  "portals",
-  "totalCount"
-]

Changed3 schema fields changedJul 5, 2026

addedOutput schema / properties / portals / items / properties / dataset_count / anyOf
```
Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]
```

changedOutput schema / properties / portals / items / properties / dataset_count / description

Previous value: -"Number of datasets on this portal."New value: +"Approximate count of dataset-type assets on this portal from the Discovery API catalog (point-in-time, refreshed ~daily). 0 means the portal exposes no dataset assets to the catalog; null means the live count is temporarily unavailable."

removedOutput schema / properties / portals / items / properties / dataset_count / type
```
Removed value: -"number"
```

Changed5 schema fields changedMay 30, 2026

removedOutput schema / properties / message

Removed value: -{
-  "description": "Recovery hint when no portals matched the filter. Absent on non-empty pages.",
-  "type": "string"
-}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery hint when no portals matched the filter. Absent on non-empty pages.",
+  "type": "string"
+}

addedOutput schema / properties / totalCount

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

removedOutput schema / properties / total_count

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

changedOutput schema / required

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

First observedMay 25, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already signal read-only and idempotent behavior, and the description adds valuable context beyond that: the catalog is curated to 39 portals, dataset counts are approximate and cached for ~24 hours, and filtering is client-side. These details help the agent anticipate staleness and performance characteristics.

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, each earning its place: what the tool returns, behavioral caveats (curated list, caching), and usage routing. Key information is front-loaded in the first sentence, and no redundant or speculative content is present.

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?

The tool is simple, has no required parameters, has a complete schema, an output schema, and safety annotations. The description fully covers what an agent needs to know to call it correctly, including data freshness and how to proceed afterward.

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 descriptions cover 100% of parameters, including limit bounds, query substring behavior, and offset pagination, so the schema carries the semantic load. The description adds only a minor implementation detail ('client-side substring match'), which does not meaningfully exceed the baseline for fully documented parameters.

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 uses a specific verb and resource ('List known Socrata-powered government open-data portals') and specifies the returned fields: domain, organization name, and approximate dataset count. It also distinguishes itself from siblings by framing this as the entry-point tool before calling socrata_find_datasets.

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?

The description gives explicit guidance: use this tool first when the target portal is unknown, then pass the chosen domain to socrata_find_datasets. This clear when-to-use directive and sibling routing leaves no ambiguity about the tool's place in the workflow.

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.