.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/oecd-mcp-server</h1> <p><b>Search, explore, and query 1,500+ OECD statistical datasets (national accounts, employment, trade, PISA, health) via SDMX via MCP. STDIO or Streamable HTTP.</b> <div>7 Tools • 1 Resource</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

Tools

Five discovery and data tools plus two SQL analytics tools for large query results:

oecd_list_agencies

Entry point for discovery — enumerate OECD's statistical departments before searching.

• Returns agency IDs (e.g. OECD.SDD.NAD, OECD.ELS, OECD.EDU) and dataflow counts
• Useful for scoping oecd_search_datasets by department (national accounts, labour, education, etc.)

oecd_search_datasets

Search the full catalog of 1,500+ OECD dataflows by keyword or department.

• Token-matching across dataflow names — finds GDP, PISA, trade, inflation, and other datasets by description
• Optional agency_id filter scopes results to a specific statistical department
• Returns flow_ref values (e.g. OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I) — pass directly to oecd_get_dataset_info or oecd_query_dataset
• Fetches and filters in-memory; the full catalog is ~800 KB and bounded (OECD adds datasets weekly, not continuously)

oecd_get_dataset_info

Inspect a dataflow's structure before querying.

• Returns all dimensions in key order (position 1, 2, 3 …) — dimension order is required to construct the dot-delimited key for oecd_query_dataset
• Shows codelist references for each dimension — pass to oecd_get_dimension_values to resolve human-readable names to SDMX codes
• Surfaces NonProductionDataflow flag — marks experimental or deprecated dataflows
• Required before calling oecd_query_dataset on an unfamiliar dataflow

oecd_get_dimension_values

Resolve human-readable names (countries, measures) to SDMX codes.

• Returns all valid code + label pairs for a single dimension (e.g. REF_AREA → USA/United States, DEU/Germany)
• The REF_AREA codelist has 570+ entries and is returned in full
• Use substring matching on the returned list to find the right code before building a key

oecd_query_dataset

Fetch observations from an OECD dataflow filtered by dimension key and time range.

• Accepts a dot-delimited key (e.g. A.USA+DEU.B1GQ_R.PC.) where empty segments are wildcards and + separates multiple values
• Optional start_period / end_period bound the time range (ISO format: 2010, 2010-Q1)
• Decodes SDMX-JSON index notation (0:0:2:3:0) into human-readable row objects with dimension labels
• Every response row includes source: "OECD" per OECD terms of use
• Small results (few countries, narrow time range): all observations returned inline
• Large results (multi-country, multi-year time-series): returns a canvas_id + truncated: true — use oecd_dataframe_describe to list tables, then oecd_dataframe_query for SQL analytics

oecd_dataframe_describe / oecd_dataframe_query

SQL analytics over observation data staged by oecd_query_dataset.

When oecd_query_dataset returns truncated: true, the full result is staged on a DuckDB-backed DataCanvas. Pass the canvas_id to:

• `oecd_dataframe_describe` — list staged table names and their columns. Run this first to discover the schema before writing SQL.
• `oecd_dataframe_query` — run a single-statement SQL SELECT. Supports aggregates, window functions, GROUP BY, ORDER BY, and standard DuckDB SQL.

Requires CANVAS_PROVIDER_TYPE=duckdb. Read-only: writes, DDL, and system catalog access are rejected.

Typical workflow for a large query:

oecd_query_dataset → { canvas_id, truncated: true, rows: [preview...] }
  → oecd_dataframe_describe(canvas_id) → table/column names
  → oecd_dataframe_query(canvas_id, "SELECT ref_area, AVG(obs_value) FROM df_... GROUP BY ref_area")

Resources

{flow_id} is the combined {dsd_id}@{df_id} string with @ percent-encoded as %40. Example: oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I.

All resource data is also reachable via tools. Use oecd_get_dataset_info for the same content.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

OECD-specific:

• Keyless access — no API key required; OECD SDMX 2.1 REST API is fully public
• Covers 1,500+ dataflows across 20+ OECD statistical departments (national accounts, employment, inflation, trade, education, health, environment, taxation, inequality)
• AllDimensions observation mode — one-pass SDMX-JSON decoding into flat row objects; no nested series key reconstruction
• oecd_query_dataset materializes large observation sets (multi-country time-series) on a DuckDB DataCanvas for in-conversation SQL analytics
• OECD source attribution (source: "OECD") on every observation row per OECD terms of use

Agent-friendly output:

• Workflow-aware tool surface — flow_ref from search flows directly into info, values, and query tools without reconstruction
• Spill signaling — truncated: true + canvas_id tells the agent to switch to SQL instead of parsing a truncated inline list
• Full SDMX decoding server-side — agents see { ref_area: "United States", measure: "Gross domestic product", obs_value: 26054 }, not raw index arrays

Getting started

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/oecd-mcp-server:latest"
      ]
    }
  }
}

To enable DataCanvas SQL analytics for large query results, add CANVAS_PROVIDER_TYPE=duckdb:

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "CANVAS_PROVIDER_TYPE": "duckdb"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.11 or higher (or Node.js v24+).
• No API key required — OECD SDMX is a free, public API.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/oecd-mcp-server.git

1. Navigate into the directory:

cd oecd-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env — most vars are optional; no API key required

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t oecd-mcp-server .
docker run --rm -p 3010:3010 oecd-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/oecd-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/index.ts
• Wrap external API calls: validate raw SDMX-JSON → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.