Idescat MCP Server

Idescat MCP サーバー

あらゆる MCP クライアント（Claude、Windsurf、Cursor、VS Code など）から、Idescat（Institut d'Estadística de Catalunya）が公開するカタルーニャの公式統計を照会するツールを提供する MCP（Model Context Protocol）サーバーです。

• 公開エンドポイント： https://api.idescat.cat/mcp
• トランスポート： Streamable HTTP（MCP 仕様 2026-07-28、リクエストごとのメタデータと server/discover に対応。2025-11-25 以前との互換性のため、従来の initialize にも対応）、ステートレス — 各 POST リクエストは独立しており、セッションはありません。POST のレスポンスはクライアントの Accept ヘッダーに応じて JSON または SSE を使用します。GET による永続的な SSE ストリームは提供されません。
• 認証： 不要（データは公開されています）。
• データ： JSON-stat 形式の Idescat 公式統計。ラベルと説明はカタルーニャ語です。対象地域はカタルーニャおよびその地域区分（郡、市町村、県など）です。

インストール

公開エンドポイントは https://api.idescat.cat/mcp です。以下の設定例のいずれかを MCP クライアントの設定に追加してください。クライアントによって必要なキー（serverUrl、url など）が異なり、type が必要な場合もあります。

Windsurf/Devin、Antigravity（serverUrl）

{
	"mcpServers": {
		"idescat": {
			"serverUrl": "https://api.idescat.cat/mcp"
		}
	}
}

Cursor、Roo Code、Zoo Code（type: streamable-http）

{
	"mcpServers": {
		"idescat": {
			"type": "streamable-http",
			"url": "https://api.idescat.cat/mcp"
		}
	}
}

Cline（type: streamableHttp）

{
	"mcpServers": {
		"idescat": {
			"type": "streamableHttp",
			"url": "https://api.idescat.cat/mcp"
		}
	}
}

VS Code および普及が進む標準形式（servers、type: http）

{
	"servers": {
		"idescat": {
			"type": "http",
			"url": "https://api.idescat.cat/mcp"
		}
	}
}

Claude.ai（カスタムコネクター）

Claude.ai（ウェブアプリおよびデスクトップアプリ）は、設定ファイルを使わずに、カスタムコネクターとしてリモートサーバーに直接接続できます。

1. Customize → Connectors を開きます。
2. Add custom connector をクリックします。
3. 次の項目を入力します。
   • Name： Idescat
   • Remote MCP server URL： https://api.idescat.cat/mcp
4. Add をクリックします。データは公開されているため、認証（OAuth／API キー）は不要です。
5. チャット画面に戻り、ツール／添付ファイルのメニューから Idescat コネクターを有効にします。これで、そのツールとリソースをアシスタントから利用できるようになります。
6. （任意）コネクターのツール設定で、各 Idescat ツールの Needs approval を Always allow に変更すると、毎回確認を求めずにアシスタントがツールを実行できます。すべてのツールは読み取り専用なので、安全です。

Claude Desktop および stdio のみ対応するクライアント（mcp-remote でブリッジ接続）

stdio のみを使用するクライアントは、mcp-remote ブリッジを介してリモートサーバーに接続できます。

{
	"mcpServers": {
		"idescat": {
			"command": "npx",
			"args": ["-y", "mcp-remote", "https://api.idescat.cat/mcp"]
		}
	}
}

クライアントが必要とするキーがわからない場合（包括的な設定）

ほとんどのクライアントは、認識できないキーを無視するため、このキーを網羅した設定は多くのクライアントでそのまま使えます。

{
	"mcpServers": {
		"idescat": {
			"url": "https://api.idescat.cat/mcp",
			"serverUrl": "https://api.idescat.cat/mcp",
			"type": "streamable-http",
			"streamableHttp": "https://api.idescat.cat/mcp"
		}
	}
}

プロトコルのバージョン

このサーバーは2つの時代のプロトコルに対応しています（MCP のバージョニング）。

時代	プロトコルのバージョン	バージョンの選択方法	動作
レガシー	2025-11-25、2025-06-18、2025-03-26、2024-11-05	initialize によるネゴシエーション	これまでどおりです。JSON-RPC を受信し、JSON-RPC を返します。ping と initialize に対応します。エラー時も HTTP 200 を返します（リソースが見つからない場合は -32002）。
モダン	2026-07-28	各リクエストの params._meta["io.modelcontextprotocol/protocolVersion"]（または server/discover）	結果には resultType: "complete"、_meta の serverInfo、およびキャッシュ可能なメソッドの ttlMs／cacheScope が含まれます。ここでは initialize／ping は存在しないため（-32601 → HTTP 404）、リソースが見つからない場合は -32602、未対応のバージョンは -32022、ヘッダー違反は -32020（HTTP 400）です。

モダンなリクエストでは、一致するヘッダーも送信する必要があります。MCP-Protocol-Version（_meta のバージョンと同じ値）、Mcp-Method（JSON-RPC メソッドと同じ値）、および tools/call（ツール名）と resources/read（URI）の Mcp-Name です（UTF-8 の値には =?base64?...?= センチネルを使用できます）。Origin は常に受け入れられます。データは公開されており、API は CORS * で応答します。

モダンなクライアントは subscriptions/listen を開くことができます。サーバーは SSE ストリームで、空のフィルターを含む notifications/subscriptions/acknowledged を返した後、仕様で定義された段階的なクローズを行います（通知タイプはサポートされていません。サーバーはステートレスであり、一覧も変更されません）。クライアントは代わりに ttlMs を参照してください。

利用可能なツール

ツール	説明
get_idescat_stats	利用可能な統計の全一覧。
get_idescat_stat	統計に関する情報（略称で指定：censph、pibc、...）。
get_idescat_stat_tables	統計のテーブル一覧。
get_table_metadata	テーブルのメタデータ（次元、カテゴリ、単位、...）。
get_table_data	JSON-stat 形式のテーブルデータ。全データ、またはオプションの filters パラメーターと last パラメーターを使い、次元／地域／期間で絞り込んだデータを取得できます（フィルター適用後は最大 20,000 セル）。サーバー側での計算に対応しています。年齢範囲フィルター（">=65"）、次元のカテゴリの sum、および derive（割合／差／変化率）が利用できます。
get_table_geo	テーブルで利用可能な地域区分（cat、prov、com、mun、...）。
render_table	行／列を選択でき、Idescat のウェブサイト上のテーブルへの出典リンクが付いた、ピボット済みの Markdown テーブル。get_table_data と同じ計算（年齢範囲フィルター、sum、derive）に対応し、テーブルの下に「Calculations:」ブロックとしてその内容を表示します。

利用可能なリソース

ツールに加えて、サーバーは MCP リソースも公開します。クライアントは、アクションを実行せずにリソースの内容をコンテキストに追加できます。

静的リソース（resources/list）：

URI	説明
idescat://instructions	使用方法のガイダンス。
idescat://glossary/geo	地域コードの用語集（cat、prov、com、mun、...）。
idescat://catalog/stats	統計の全カタログ。

リソーステンプレート（resources/templates/list）—パラメーター化された URI：

URI テンプレート	説明
idescat://stat/{stat}	統計に関する情報（例：.../censph）。
idescat://stat/{stat}/tables	統計のテーブル一覧。
idescat://table/{stat}/{table}	テーブルのメタデータ（例：.../censph/538）。
idescat://table/{stat}/{table}/data	テーブルの JSON-stat データ（最大 20,000 セル）。

トランスポートはステートレスであるため、subscribe と resources/list_changed の通知は提供されません（永続的な接続がないためです）。

サーバー側での計算

言語モデルは、長い数列の暗算が非常に苦手です。そのため、get_table_data と render_table では、サーバーが結果を決定的に計算し、モデル自身が返された値を加算、減算、除算する必要がないように、3つのオプションパラメーターを受け付けます。

{ "filters": { "AGE": ">=65", "SEX": "TOTAL" }, "last": 1 }
{ "sum": ["AGE"] }
{ "derive": { "share": "AGE", "percent_change": "previous" } }

• 年齢範囲フィルター。 Y000、Y005_009、Y_GE100 などのコードが割り当てられたディメンションでは、フィルター値に範囲式（">=65"、">65"、"<16"、"<=15"、"16-64"）を指定できます。サーバーはこれを正確なコードのリストに変換します。公表されている区分で境界を正確に表現できない場合は、range_not_representable を返します。
• sum は、指定したディメンションのカテゴリを合計してまとめます。結果は単一の SUM カテゴリになります。TOTAL は自動的に除外されます。
• derive は、導出指標を指標ディメンションに追加します。 share（<METRIC>_SHARE = 100 × 値 / 指定したディメンションの TOTAL における値）、difference（<METRIC>_DIFF = 前の期間または指定した期間との差）、percent_change（<METRIC>_PCT = 100 × (値 − 基準値) / 基準値）です。

計算エンジンは、Idescat の規約に基づいて動作します。加法性は指標ディメンションの extension["%"] で宣言します（加法性のある指標のみ、合計または比率の計算が可能です）。TOTAL は合計コードで、計算できないセルはステータス d とともに null として返されます。適用されたすべての処理は extension.derived（範囲、合計したコード、数式、警告）に記録され、render_table はテーブルの下に Calculations: ブロックとして表示します。

安全でないリクエストは拒否されます。該当するエラーは metric_not_additive、geo_not_summable（地域ディメンションは合計できません。集計値がすでに公表されている地域区分を geo パラメーターで指定してください）、range_not_representable、incomplete_data、total_not_available です。

エージェントスキル

Agent Skills のオープン形式（SKILL.md ファイルを含むディレクトリ。YAML フロントマターと Markdown の手順で構成）で提供される2つのスキルは、Idescat のデータを正しく利用する方法をエージェントに教えます。ウェブサイトで公開され、ARD マニフェストで案内されています。

スキル	URL	説明
jsonstat	https://www.idescat.cat/dev/api/taules/jsonstat/SKILL.md	JSON-stat 2.0 データセットの読み取り方：ディメンションのインデックス、行優先の順序、ストライド／オフセットの算術、null と status の処理。汎用的なスキルで、あらゆる JSON-stat プロデューサーで役立ちます。
workflow	https://www.idescat.cat/dev/api/taules/workflow/SKILL.md	Idescat のデータを確実にクエリする方法（この MCP サーバーまたは Tables API を使用）：統計と地域レベルの選択、メタデータを優先する手順、20,000 セルの上限とフィルター、必須の出典表記。

リポジトリのファイル

以下のファイルは、サーバーのガイダンスとリソースを定義しており、変更されずにMCPクライアントへ提供されます。

• instructions.md — ハンドシェイク中にサーバーがクライアントへ送信し、idescat://instructions リソースとして公開する利用ガイダンスです。統計の選び方、データ取得の流れ、JSON-stat の解釈方法、出典の明記に関するルールを説明しています。
• resources.json — サーバーが公開するMCP リソースとリソーステンプレート（上記の利用可能なリソースセクションの2つの表）の宣言です。各URI、タイトル、説明、MIMEタイプ、対応するファイルまたはツールが含まれています。
• resources/geo.md — geo パラメーターで使用される地域コード（cat、prov、at、com、mun、dis、sec）の用語集です。idescat://glossary/geo リソースとして公開されます。

リポジトリには、次のファイルも含まれています。

• server.json — 標準の server.json形式に準拠した、サーバーのメタデータマニフェストです。サーバーを公式の MCP Registryに公開するために使用されます。
• jsonstat/SKILL.md と workflow/SKILL.md — 2つの エージェントスキルです。ウェブサイトの https://www.idescat.cat/dev/api/taules/ にも公開されています。

検出（エージェントによるリソース検出）

このサーバーは Agentic Resource Discovery（ARD） 仕様（v0.91）に基づいて公開されているため、エージェントが自動的に検出できます。

• ARD マニフェストは https://www.idescat.cat/.well-known/ard.json と https://api.idescat.cat/.well-known/ard.json で公開されており、両方のホストで Access-Control-Allow-Origin: * を付けて配信されます。トップレベルの specVersion を含むため、同じドキュメントを ARD マニフェストと AI Catalog ファイルの両方として使用できます。 /.well-known/ai-catalog.json は、内部リライトによって ard.json をリダイレクトなしで application/ai-catalog+json として直接配信します。 これは、一部の MCP 検出フローで今も最初に要求される旧形式です。 マニフェストには 4 つのエントリーが記載されています。この MCP サーバー （application/mcp-server-card+json）、OpenAPI ドキュメント （application/openapi+json）で説明されている Idescat Tables API（URL： https://www.idescat.cat/dev/api/taules/openapi.json）、および 2 つの エージェントスキル （Markdown の SKILL.md ファイルとして公開されたスキル向けの AI Catalog メディアタイプ、 application/agent-skills+md）です。
• MCP サーバーカード（application/mcp-server-card+json）は、 実験的な Server Card 検出仕様 が <streamable-http-url>/server-card として予約している場所、 https://api.idescat.cat/mcp/server-card で配信されます。ベアエンドポイント https://api.idescat.cat/mcp への GET（または HEAD）は 405 を返します。このエンドポイントは POST 専用ですが、POST の応答では SSE を使用できます。カードと MCP ハンドシェイク（serverInfo）では、MCP Registry と同じ名前 cat.idescat/mcp を使用します。カードの応答は仕様のキャッシュ規約に準拠しています。 Cache-Control: public, max-age=3600、If-None-Match に 304 で応答する ETag、および CORS ヘッダー（Allow-Methods: GET、 Allow-Headers: Content-Type, If-None-Match、Expose-Headers: ETag）を備えています。
• 旧形式のカードの別名 /.well-known/mcp/server-card.json と /.well-known/mcp.json は、内部リライトにより api.idescat.cat で直接配信されます （内容は同一で、リダイレクトはありません。一部のクローラーはリダイレクトを たどらないためです）。www.idescat.cat では https://api.idescat.cat/mcp/server-card にリダイレクト（307）されます。
• ard.json 内の MCP エントリーはカードの URL を指し、 metadata.mcpEndpoint を介してトランスポートエンドポイント （https://api.idescat.cat/mcp）を公開します。メディアタイプには application/mcp-server-card+json を使用します。以前の application/mcp-server+json メディアタイプは、 ARD ADR-0008 で非推奨になりました。
• ウェブサイトのページには、マニフェストへのリンクも含まれています。 <link rel="ard" href="/.well-known/ard.json" type="application/json"> （ard リンク関係は、旧形式の ai-catalog 関係に代わるものです）。
• robots.txt には、マニフェストを指す Agentmap: ディレクティブが含まれています。
• MCP サーバーは、サイトの llms.txt ファイルでも公開されています。

MCP Registry

このサーバーは、公式の MCP Registry に cat.idescat/mcp という名前で登録されています（server.json を参照）。 MCP クライアントやアグリゲーターは、レジストリ API からメタデータを取得できます。

https://registry.modelcontextprotocol.io/v0.1/servers/cat.idescat%2Fmcp/versions/latest

MCP Inspector による対話型テスト

npx @modelcontextprotocol/[email protected]

特定のバージョン（例：@2.0.0）を指定すると、ツールを再現可能な状態に保ち、 予期しない変更を取り込まずに済みます。これには Node.js >= 22.19.0 が必要です。 npm warn deprecated ... / ERESOLVE のメッセージは Inspector 自体の依存関係に起因するもので、 問題はありません。この MCP サーバーには影響しません。

「Streamable HTTP」トランスポートを選択し、エンドポイント URL を入力してください。

Links

• Idescat: https://www.idescat.cat
• Model Context Protocol: https://modelcontextprotocol.io
• MCP specification (2026-07-28, Streamable HTTP transport): https://modelcontextprotocol.io/specification/2026-07-28
• MCP versioning (dual-era servers): https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning
• Agentic Resource Discovery (ARD): https://agenticresourcediscovery.org
• ARD specification (rendered): https://agenticresourcediscovery.org/spec/
• ARD specification repository (schemas, conformance tooling): https://github.com/ards-project/ard-spec