The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Idescat MCP Server listing page.
MCP (Model Context Protocol) server that exposes tools to query the official statistics of Catalonia, published by Idescat (Institut d'Estadística de Catalunya), from any MCP client (Claude, Windsurf, Cursor, VS Code, etc.).
https://api.idescat.cat/mcpThe public endpoint is https://api.idescat.cat/mcp. Add one of the snippets
below to your MCP client's configuration. Different clients expect a different
key (serverUrl, url, ...) and sometimes a type.
serverUrl)type: streamable-http)type: streamableHttp)servers, type: http)Claude.ai (web and desktop apps) can reach the remote server directly as a custom connector, no configuration file needed.
Idescathttps://api.idescat.cat/mcpmcp-remote)Clients that only speak stdio can reach the remote server through the
mcp-remote bridge:
Most clients ignore keys they don't recognise, so this superset works with many of them at once:
| Tool | Description |
|---|---|
get_idescat_stats | Full list of available statistics. |
get_idescat_stat | Information about a statistic (by acronym: censph, pibc, ...). |
get_idescat_stat_tables | List of tables of a statistic. |
get_table_metadata | Table metadata (dimensions, categories, units, ...). |
get_table_data | Table data in JSON-stat: full, or filtered by dimension/territory/periods with the optional filters and last parameters (max. 20,000 cells after applying filters). |
get_table_geo | Territorial divisions available for a table (cat, prov, com, mun, ...). |
render_table | Ready-pivoted Markdown table (selectable rows/columns) with an attribution link to the table on the Idescat website. |
Beyond the tools, the server exposes MCP resources — content a client can attach to the context without executing any action.
Static resources (resources/list):
| URI | Description |
|---|---|
idescat://instructions | Usage guidance. |
idescat://glossary/geo | Glossary of territorial codes (cat, prov, com, mun, ...). |
idescat://catalog/stats | Full catalogue of statistics. |
Resource templates (resources/templates/list) — parametrised URIs:
| URI template | Description |
|---|---|
idescat://stat/{stat} | Information about a statistic (e.g. .../censph). |
idescat://stat/{stat}/tables | List of tables of a statistic. |
idescat://table/{stat}/{table} | Table metadata (e.g. .../censph/538). |
idescat://table/{stat}/{table}/data | JSON-stat data of a table (max. 20,000 cells). |
The transport is stateless, so
subscribeandresources/list_changednotifications are not offered (there is no persistent connection).
Two skills in the Agent Skills open format (a
directory with a SKILL.md file: YAML frontmatter + Markdown instructions)
teach agents how to use Idescat data correctly. They are published on the
website and advertised in the ARD manifest:
| Skill | URL | Description |
|---|---|---|
jsonstat | https://www.idescat.cat/dev/api/taules/jsonstat/SKILL.md | How to read JSON-stat 2.0 datasets: dimension index, row-major order, stride/offset arithmetic, null and status handling. Generic — useful with any JSON-stat producer. |
workflow | https://www.idescat.cat/dev/api/taules/workflow/SKILL.md | How to query Idescat data reliably (via this MCP server or the Tables API): choosing the statistic and territorial level, metadata-first flow, the 20,000-cell limit and filters, and mandatory source citation. |
The following files define the server's guidance and resources and are served, unchanged, to MCP clients:
instructions.md — usage guidance the server sends to
clients during the handshake and exposes as the idescat://instructions
resource. It explains how to choose a statistic, the data-retrieval flow, how
to interpret JSON-stat, and the source-attribution rules.resources.json — declaration of the MCP resources
and resource templates the server exposes (the two tables in the
Available resources section above), including each
URI, title, description, MIME type, and its backing file or tool.resources/geo.md — glossary of territorial codes
(cat, prov, at, com, mun, dis, sec) used by the geo parameter,
exposed as the idescat://glossary/geo resource.The repository also includes:
server.json — the server's metadata manifest in the
standard
server.json format,
used to publish the server to the official
MCP Registry.jsonstat/SKILL.md and
workflow/SKILL.md — the two
agent skills, also published on the website under
https://www.idescat.cat/dev/api/taules/.The server is advertised using the Agentic Resource Discovery (ARD) specification (v0.91) so agents can find it automatically:
https://www.idescat.cat/.well-known/ard.json and
https://api.idescat.cat/.well-known/ard.json. The legacy predecessor path
(/.well-known/ai-catalog.json) is redirected (301) to the new manifest.
The manifest advertises four entries: this MCP server
(application/mcp-server-card+json), the
Idescat Tables API, described by
its OpenAPI document (application/openapi+json) at
https://www.idescat.cat/dev/api/taules/openapi.json, and the two
agent skills
(text/markdown; profile="urn:air:agent-skills").GET request to the endpoint https://api.idescat.cat/mcp returns the
MCP server card (application/mcp-server-card+json), generated from the
server's tool and resource definitions. A GET requesting
text/event-stream returns 405, since this stateless server offers no SSE
stream.https://www.idescat.cat/.well-known/mcp/server-card.json (and https://www.idescat.cat/.well-known/mcp.json), which redirects
to https://api.idescat.cat/mcp.<link rel="ard" href="https://github.com/idescat/mcp/blob/HEAD/.well-known/ard.json" type="application/json">
(the ard link relation replaces the predecessor ai-catalog relation).robots.txt includes an Agentmap: directive pointing to the manifest.llms.txt file.The server is listed in the official
MCP Registry under the name
cat.idescat/mcp (see server.json). MCP clients and
aggregators can retrieve its metadata from the registry API:
Pinning a specific version (e.g. @2.0.0) keeps the tool reproducible and
avoids picking up unexpected changes; it requires Node.js >= 22.19.0. Any
npm warn deprecated ... / ERESOLVE messages come from the Inspector's own
dependencies and are harmless — they do not affect this MCP server.
Select the "Streamable HTTP" transport and enter the endpoint URL.