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.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "socrata_list_portals"
  }
}

Input 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

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Recovery hint for an empty page: no portals matched the filter, or offset passed the last portal (names the offset to page below). 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.

Changed1 schema field changedOct 31, 2026

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when no portals matched the filter. Absent on non-empty pages."New value: +"Recovery hint for an empty page: no portals matched the filter, or offset passed the last portal (names the offset to page below). Absent on non-empty pages."

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

Behavior4/5

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

Annotations already declare readOnly, idempotent, and openWorld, so safety basics are covered. The description adds genuinely non-obvious traits: the catalog is a fixed curated set of 39 portals, dataset counts come from the Discovery API and are cached ~24 hours (hence "approximate" and potentially stale), and filtering happens client-side. It does not explain how limit/offset interact with the client-side filter, which keeps it below a 5.

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 compact sentences, each carrying distinct information: what it returns, how counts are sourced/cached, and where it sits in the workflow. The routing instruction is front-loaded at the end with no filler.

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 not be explained, and annotations cover the safety profile. The description supplies everything else an agent needs: catalog size bounds, staleness of counts, filter semantics, and the next step in the workflow.

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%, with limit, query, and offset each documented including ranges and defaults. The description largely restates the query parameter's substring-match behavior already in the schema; the only added nuance is that the match is client-side, which is marginal beyond what the schema provides.

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 ("List known Socrata-powered government open-data portals") and enumerates the returned fields: domain, organization name, approximate dataset count. The scope (curated list of 39 portals) makes it clearly distinct from socrata_find_datasets, which operates on a single portal.

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 entry-point rule ("Use this first when you do not know which portal to target") and the follow-on action ("then pass the domain to socrata_find_datasets"), naming the sibling tool that consumes the output. No inference is required about when this tool applies.

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.