eurostat-mcp-server

Browse Eurostat Theme Hierarchy

eurostat_browse_themes

Read-onlyIdempotent

Navigate the Eurostat theme tree. Without theme_code returns the top-level theme folders (Economy, Population, Transport, etc.) — the practical starting points. With a theme_code returns its immediate children: subtheme folders and datasets in that branch. Use this for structured discovery when you know the domain but not the dataset code, or to drill down from a broad topic to a specific dataset. Pair with eurostat_search_datasets for keyword-based discovery. The tree is the dissemination table of contents plus the Comext host's DS-* collections: detailed trade under ext_go_detail (inside ext_go, "International trade in goods") and PRODCOM under prom (inside icts, "Industry, trade and services"). A collection on neither, such as the legacy PRODCOM DS-056120, is not disseminated and appears nowhere in the tree.

Input Schema

Name	Required	Description	Default
`theme_code`	No	Folder code to expand (e.g., "economy", "reg"). Exact codes take precedence, then case-insensitive matching applies. Omit to list the top-level theme folders.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`items`	No	Immediate children of the requested theme, or the root themes if theme_code was omitted.
`notice`	No	Names each part of the catalogue this listing is missing — the Comext collections, or updates since a refresh failed — and what to do about it. Omitted when the whole catalogue answered.
`nextStep`	No	Suggested next action based on these results. Populated when there is a clear follow-up call.
`itemCount`	No	Number of items returned in this level.
`themeCode`	No	Folder code that was browsed, or omitted for root.
`parentPath`	No	Breadcrumb from root to the requested theme (e.g., ["Database by themes", "Economy and finance"]). Empty when browsing root.
`otherPlacements`	No	Breadcrumbs of the other branches that file this same theme_code. Eurostat lists a few folder codes in more than one branch; the items above come from the first one the catalogue lists, which never has fewer children than the branches named here but can list different ones. theme_code takes a bare code, so those branches cannot be addressed directly — browse down to them from the root instead. Omitted when the code has a single placement — the normal case.
`catalogueLoadedAt`	No	When the catalogue that answered was loaded (ISO 8601). Present only when a refresh failed and that older copy is still in service; omitted otherwise.
`comextListMissing`	No	True on a browse of ext_go or icts when the Comext dataflow list could not be loaded, so the DS-* collection folder filed there is not listed. Omitted otherwise.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist in the TOC — or is a Comext folder (ext_go_detail, prom, comext) or DS-* code while the Comext dataflow list cannot be loaded. `not_a_folder`: The provided theme_code identifies a dataset or table entry instead of a folder. `upstream_fault`: The server had no catalogue loaded yet, and Eurostat's table of contents answered HTTP 5xx or could not be reached on every retry, which the error marks retryable. Once a catalogue is loaded, a failed refresh serves that copy instead. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist in the TOC — or is a Comext folder (ext_go_detail, prom, comext) or DS-* code while the Comext dataflow list cannot be loaded. `not_a_folder`: The provided theme_code identifies a dataset or table entry instead of a folder. `upstream_fault`: The server had no catalogue loaded yet, and Eurostat's table of contents answered HTTP 501, which is not retried; or it answered another HTTP 5xx or could not be reached on every retry, which the error marks retryable. Once a catalogue is loaded, a failed refresh serves that copy instead. Other values are possible when a failure originates below the handler."

Changed1 schema field changedOct 26, 2026

changedInput schema / properties / theme_code / description

Previous value: -"Folder code to expand (e.g., \"economy\", \"reg\"). Omit to list the top-level theme folders."New value: +"Folder code to expand (e.g., \"economy\", \"reg\"). Exact codes take precedence, then case-insensitive matching applies. Omit to list the top-level theme folders."

Changed5 schema fields changedOct 15, 2026

addedOutput schema / properties / catalogueLoadedAt

Added value: +{
+  "description": "When the catalogue that answered was loaded (ISO 8601). Present only when a refresh failed and that older copy is still in service; omitted otherwise.",
+  "type": "string"
+}

addedOutput schema / properties / comextListMissing

Added value: +{
+  "description": "True on a browse of ext_go or icts when the Comext dataflow list could not be loaded, so the DS-* collection folder filed there is not listed. Omitted otherwise.",
+  "type": "boolean"
+}

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist in the TOC. `not_a_folder`: The provided theme_code identifies a dataset or table entry instead of a folder. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist in the TOC — or is a Comext folder (ext_go_detail, prom, comext) or DS-* code while the Comext dataflow list cannot be loaded. `not_a_folder`: The provided theme_code identifies a dataset or table entry instead of a folder. `upstream_fault`: The server had no catalogue loaded yet, and Eurostat's table of contents answered HTTP 5xx or could not be reached on every retry, which the error marks retryable. Once a catalogue is loaded, a failed refresh serves that copy instead. Other values are possible when a failure originates below the handler."

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

Previous value: -[
-  "not_found",
-  "not_a_folder"
-]New value: +[
+  "not_found",
+  "not_a_folder",
+  "upstream_fault"
+]

addedOutput schema / properties / notice

Added value: +{
+  "description": "Names each part of the catalogue this listing is missing — the Comext collections, or updates since a refresh failed — and what to do about it. Omitted when the whole catalogue answered.",
+  "type": "string"
+}

Changed2 schema fields changedAug 31, 2026

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

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist as a folder in the TOC. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: The provided theme_code does not exist in the TOC. `not_a_folder`: The provided theme_code identifies a dataset or table entry instead of a folder. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples
```
Previous value: -[
-  "not_found"
-]New value: +[
+  "not_found",
+  "not_a_folder"
+]
```

Changed6 schema fields changedAug 21, 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": [
+      "items",
+      "parentPath",
+      "itemCount"
+    ]
+  },
+  {
+    "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: `not_found`: The provided theme_code does not exist as a folder in the TOC. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found"
+          ],
+          "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: -[
-  "items",
-  "parentPath",
-  "itemCount"
-]

Changed1 schema field changedAug 4, 2026

addedOutput schema / properties / otherPlacements

Added value: +{
+  "description": "Breadcrumbs of the other branches that file this same theme_code. Eurostat lists a few folder codes in more than one branch; the items above come from the first one the catalogue lists, which never has fewer children than the branches named here but can list different ones. theme_code takes a bare code, so those branches cannot be addressed directly — browse down to them from the root instead. Omitted when the code has a single placement — the normal case.",
+  "items": {
+    "description": "Breadcrumb from root to one other folder carrying the requested code.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "type": "array"
+}

Changed2 schema fields changedAug 4, 2026

changedInput schema / properties / theme_code / description

Previous value: -"Folder code to expand (e.g., \"econ\", \"reg\"). Omit to list the top-level theme folders."New value: +"Folder code to expand (e.g., \"economy\", \"reg\"). Omit to list the top-level theme folders."

changedOutput schema / properties / parentPath / description

Previous value: -"Breadcrumb from root to the requested theme (e.g., [\"Economy and finance\", \"National accounts\"]). Empty when browsing root."New value: +"Breadcrumb from root to the requested theme (e.g., [\"Database by themes\", \"Economy and finance\"]). Empty when browsing root."

Changed3 schema fields changedJul 10, 2026

changedInput schema / properties / theme_code / description

Previous value: -"Folder code to expand (e.g., \"econ\", \"reg\"). Omit to list the 11 top-level theme folders."New value: +"Folder code to expand (e.g., \"econ\", \"reg\"). Omit to list the top-level theme folders."

changedOutput schema / properties / items / description

Previous value: -"Immediate children of the requested theme, or the 11 root themes if theme_code was omitted."New value: +"Immediate children of the requested theme, or the root themes if theme_code was omitted."

addedOutput schema / properties / nextStep

Added value: +{
+  "description": "Suggested next action based on these results. Populated when there is a clear follow-up call.",
+  "type": "string"
+}

Changed3 schema fields changedMay 30, 2026

addedOutput schema / properties / itemCount

Added value: +{
+  "description": "Number of items returned in this level.",
+  "type": "number"
+}

addedOutput schema / properties / themeCode

Added value: +{
+  "description": "Folder code that was browsed, or omitted for root.",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "items",
-  "parentPath"
-]New value: +[
+  "items",
+  "parentPath",
+  "itemCount"
+]

First observedMay 24, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover the read-only, idempotent, open-world profile, so the description is free to add non-obvious operational context — which it does: the tree's scope (dissemination table of contents plus Comext DS-* collections), where detailed trade and PRODCOM data sit, and the important warning that non-disseminated collections like the legacy PRODCOM DS-056120 appear nowhere in the tree. That last point prevents an agent from concluding a dataset does not exist when it merely is not in the tree.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the two-mode behavior and the usage guidance before the scope caveat, which is the right ordering. The Comext/PRODCOM paragraph is dense and slightly over-detailed for a browse tool, but each claim (ext_go_detail, prom, DS-056120) is substantive rather than 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?

A single optional parameter tool with an output schema, so return-value detail is unnecessary. The description covers mode behavior, discovery use case, sibling routing, and tree coverage limits — nothing an agent needs in order to call it correctly is missing.

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% and the schema itself already documents precedence (exact code, then case-insensitive) and the omit-to-list-top-level behavior. The description restates the omit case and the children semantic but adds no format or matching detail beyond the schema, so it sits at the baseline.

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 opens with a specific verb and resource ("Navigate the Eurostat theme tree") and then states exactly what each invocation mode returns: top-level theme folders without a code, immediate children (subthemes and datasets) with one. That is enough for an agent to distinguish it from eurostat_search_datasets and the dataset-level siblings without opening any schema.

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?

It names the condition that selects this tool ("when you know the domain but not the dataset code") and the drill-down pattern, then explicitly routes keyword-based discovery to eurostat_search_datasets. When-to-use, why-to-use, and the alternative are all stated rather than inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All eurostat-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.

Browse Eurostat Theme Hierarchy

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources