oecd-mcp-server

Oecd Query Dataset

oecd_query_dataset

Read-onlyIdempotent

Fetch observations from an OECD dataflow filtered by a dimension key and optional time range. Returns decoded rows (one per observation) with dimension and attribute labels, and values already scaled by the observation unit multiplier. Large multi-country time-series spill to a DataCanvas table — inspect columns with oecd_dataframe_describe, then query the full table with SQL using oecd_dataframe_query; without DataCanvas every row still comes back, but the rendered table stops at a preview slice. Call oecd_get_dataset_info first to learn the dimension order for constructing the key.

Input Schema

Name	Required	Description
`key`	Yes	Dot-delimited dimension key matching the dimension order from oecd_get_dataset_info. Empty segments are wildcards; "+" separates multiple values per segment. Example: "A.USA+DEU.B1GQ.." — Annual, USA or Germany, GDP, all remaining dimensions.
`flow_ref`	Yes	Full flow reference — e.g. "OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I", or the bare "OECD.TAD.ARP,DF_AEI2024_DASHBOARD" form for a dataflow published without a datastructure prefix. Obtain from oecd_search_datasets and pass it through unchanged.
`canvas_id`	No	Canvas ID from a prior oecd_query_dataset call — exactly 10 characters of letters, digits, hyphens, and underscores — to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one; a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline.
`end_period`	No	End of the time range — ISO period code such as "2023" or "2023-Q4". Omit to include up to the latest available period.
`start_period`	No	Start of the time range — ISO period code such as "2010", "2010-Q1", or "2010-01". Omit to include all history (may produce very large results).

Output Schema

Name	Required	Description
`rows`	No	Observation rows. Every row of the result when truncated is absent; the leading preview slice when truncated is true — query the canvas table for the rest.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	How to inspect and query the staged result, including its canvas_id and table name; present only after a spill.
`source`	No	Data source attribution — always "OECD".
`canvas_id`	No	Canvas handle for the staged result. Present only when DataCanvas is configured and the result exceeded the inline budget; absent when DataCanvas is off, and absent when it is on but the result fit inline. Pass to oecd_dataframe_query or oecd_dataframe_describe.
`query_key`	No	Dimension key used in this query.
`row_count`	No	Total rows in the result (or on the canvas when truncated).
`truncated`	No	True when rows is a preview slice and the full result was staged on DataCanvas; omitted entirely (never false) when rows holds the complete result. Use oecd_dataframe_query with the canvas_id for analytics over the full set. A complete rows never means a complete rendered table — content_table_capped reports that separately.
`table_name`	No	Canvas table name holding the full result — present when canvas_id is set. Inspect columns with oecd_dataframe_describe, then query this table with SQL using oecd_dataframe_query.
`query_flow_ref`	No	Flow reference used in this query.
`query_end_period`	No	End period filter applied in this query, if any.
`content_table_rows`	No	Rows the rendered table shows when content_table_capped is true.
`query_start_period`	No	Start period filter applied in this query, if any.
`content_table_capped`	No	True when the rendered table shows only the leading rows of the result. Distinct from truncated: nothing was staged anywhere, and structuredContent.rows still holds every row. To shrink the result itself, name fewer values per key segment or set a narrower start_period / end_period; to reach the full set as a queryable table instead, run with CANVAS_PROVIDER_TYPE=duckdb and follow up with oecd_dataframe_query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 24, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "How to inspect and query the staged result, including its canvas_id and table name; present only after a spill.",
+  "type": "string"
+}

changedOutput schema / properties / table_name / description

Previous value: -"Canvas table name holding the full result — present when canvas_id is set."New value: +"Canvas table name holding the full result — present when canvas_id is set. Inspect columns with oecd_dataframe_describe, then query this table with SQL using oecd_dataframe_query."

Changed2 schema fields changedSep 20, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas ID from a prior oecd_query_dataset call, to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one — a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline."New value: +"Canvas ID from a prior oecd_query_dataset call — exactly 10 characters of letters, digits, hyphens, and underscores — to stage this result alongside that one. Omit to let the server mint a canvas if this result needs one; a canvas_id comes back only when the result was large enough to spill, never on a result that fits inline."

addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

First observedSep 1, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover read-only/idempotent/open-world safety, yet the description adds substantial context beyond them: values arrive pre-scaled by the unit multiplier, large multi-country series spill to a DataCanvas table, and without DataCanvas rendering stops at a preview slice even though all rows return.

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?

The purpose and key-filter statement is front-loaded, followed by the sibling routing and spill behavior. Every sentence carries information, though the canvas/spill sentence is long and could be split for easier scanning.

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?

Given an output schema exists, return-value explanation is optional, yet the description still characterizes rows and value scaling. Combined with the DataCanvas workflow and prerequisite tool call, an agent has everything needed to invoke and follow up correctly.

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%, so key syntax, empty-segment wildcards, '+' separators, period formats, and canvas_id constraints are already documented in the schema. The description reinforces the key/dimension-order relationship but adds little parameter meaning beyond structured fields, so the baseline 3 applies.

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 ('Fetch observations from an OECD dataflow') plus the filter inputs (dimension key, optional time range) and the return shape (decoded rows). This is clearly distinguishable from siblings that search datasets or inspect dimensions.

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?

Explicitly routes the agent: call oecd_get_dataset_info first to learn dimension order, use oecd_dataframe_describe then oecd_dataframe_query after a spill, and it notes the fallback when DataCanvas is unavailable. When-and-how guidance is fully specified.

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

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