Meridian Documentation

Everything you need to integrate macroeconomic data into your applications and AI agents.

Quickstart

Connect an API-key-capable MCP client or run a standard HTTP request.

1Get an API Key

2Connect via MCP

Add this remote MCP server config. The sample key is a placeholder, so replace mrd_your_key_here with a real key from Account in your local MCP client.

MCP activation

Connect Meridian over MCP

For clients supporting remote MCP with Authorization headers. Configuration format varies by client. Use a real key from Account in your local client; Free includes snapshots and ask_meridian. Clients requiring OAuth cannot use this API-key configuration.

Account keys

Transport

{
  "mcpServers": {
    "meridian": {
      "url": "https://api.meridianapi.io/mcp",
      "headers": {
        "Authorization": "Bearer mrd_your_key_here"
      }
    }
  }
}

1. Replace placeholder

2. Restart your MCP client

3. Ask “How is inflation?”

Reconnect your compatible MCP client and check its tool list. If connection fails, verify its transport and Authorization-header support or use REST.

3Try It

In your connected compatible client, try a question below. Historical change and comparison tools require Pro or Enterprise:

"How's the US economy doing right now?"
"What happened to inflation in the last 3 months?"
"Compare current conditions to 2008"

4Or Use the REST API

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.meridianapi.io/v1/snapshot

Data trust

Freshness is visible, not hidden

Meridian separates actionable data issues from normal source publication lag so agents can decide what to trust.

Series monitored

—

Healthy series

—

Actionable issues

—

Last ingestion: unknown · Updated: unknown

Interfaces

MCP and REST access, with dependency-free Python and JavaScript examples.

🤖

MCP Tools

For remote MCP clients supporting API-key Authorization headers. Setup varies by client.

🌐

REST API

Standard HTTP endpoints for any language or framework. JSON responses.

🐍

Python

Standard-library HTTP example. No Meridian package required.

📦

JavaScript

Native fetch example for Node.js 20+. No Meridian package required.

Implementation guides

These focused pages connect the reference docs to common data, MCP, agent, and fintech integration paths.

Inflation API

Query CPI, core CPI, PCE, and related macro context through Meridian's inflation API for dashboards, agents, and fintech workflows.

Unemployment API

Use Meridian's unemployment API to track the headline jobless rate, payrolls, claims, and labor-market context across apps, dashboards, and AI agents.

Macro data server

Connect Meridian as a remote MCP server so Claude, Cursor, and other MCP clients can call macro snapshot, compare, and explanation tools with your API key.

AI agent macro data

Give Claude, Cursor, or your own AI agent freshness-aware macro data over MCP or REST so answers can reference inflation, jobs, rates, and history instead of stale prompt context.

Macro data API for AI agents

Evaluate Meridian as a macro data API for AI agents with honest fit criteria, tradeoffs, MCP and REST integration notes, and links to docs, pricing, and data APIs.

Fintech macro API

Use Meridian's macro API to power dashboards, alerts, commentary, and underwriting context with deterministic access to inflation, labor, rates, and market data.

MCP Tools Reference

All 11 tools are listed below. Free permits get_macro_snapshot and ask_meridian only. Examples are MCP tool arguments, not REST request bodies. Inspect tools/list in your connected client for the deployed schema.

get_macro_snapshot — Free

indicators?: string[] (core six); as_of_date?: YYYY-MM-DD; include_history?: boolean (false); history_periods?: integer 1–120 (12)

{
  "indicators": [
    "UNRATE"
  ]
}

indicators, snapshot_date, regime and metadata. Inspect per-indicator errors. Observation cutoff applies to regime inputs too; latest stored revisions are not historical vintages.

ask_meridian — Free

question: non-empty string; include_chart?: boolean (false)

{
  "question": "What is the current unemployment rate?",
  "include_chart": false
}

Answer and supporting data. Missing observations are not zero.

explain_macro_change — Pro / Enterprise

indicator: string; period?: 1m | 3m | 6m | 1y | ytd | custom (1m); start_date?, end_date?: YYYY-MM-DD for custom; depth?: summary | detailed | full (detailed)

{
  "indicator": "UNRATE",
  "period": "1y"
}

Period changes and context. end_date is honoured; depth is accepted but does not currently change the response shape. Distinguish relative percentages from percentage points.

compare_macro_regimes — Pro / Enterprise

current_date?: YYYY-MM-DD; compare_to?: string[] (auto expands to 2008_crisis and 2020_covid); indicators?: string[]

{
  "compare_to": [
    "2008_crisis"
  ],
  "indicators": [
    "UNRATE",
    "FEDFUNDS"
  ]
}

current, comparisons and classification. Comparisons may contain individual errors; similarity is not a probability.

search_series — Pro / Enterprise

query?: string; category?: exact slug; tags?: string[] (all match); limit?: integer 1–50 (10)

{
  "query": "unemployment",
  "limit": 5
}

Matching stored series. Empty results differ from errors; public catalogue discovery is also available.

get_series_history — Pro / Enterprise

series_id: string; start_date?, end_date?: YYYY-MM-DD; limit?: integer 1–1000 (120)

{
  "series_id": "UNRATE",
  "limit": 24
}

Stored observations, bounded by availability. Not a historical-vintage service.

compare_indicators — Pro / Enterprise

indicators: 2–8 IDs; start_date?, end_date?: YYYY-MM-DD; limit?: integer 1–1000 per indicator (120)

{
  "indicators": [
    "UNRATE",
    "FEDFUNDS"
  ],
  "limit": 12
}

Multiple series; units and cadences need not match.

get_dashboard_summary — Pro / Enterprise

No parameters.

{}

Dashboard summary. Response time is not observation date; scores are heuristic.

get_data_health — Pro / Enterprise

No parameters.

{}

Ingestion/data health, not SLA or economic-risk certification.

get_series_metadata — Pro / Enterprise

series_id: string

{
  "series_id": "UNRATE"
}

Stored metadata. Missing fields do not imply rights or certainty.

build_chart_spec — Pro / Enterprise

series_id: string; title?: string; start_date?, end_date?: YYYY-MM-DD; limit?: integer 1–1000 (240)

{
  "series_id": "UNRATE",
  "limit": 12
}

Chart specification. Preserve gaps, units and any classification supplied by the source.

Use an API-key-capable remote MCP client. Generic JSON is not a universal Claude Desktop configuration; OAuth-only connections are not supported by this recipe. Start with REST if your client cannot set Authorization headers. HTTP 401 needs valid credentials, 403 needs permission and 429 requires bounded backoff. Keep authentication and partial-data errors distinct from empty results. Never paste keys into public chats, source control or analytics.

Response walkthroughs

`get_macro_snapshot`

Returns current values of key macro indicators with historical context.

Parameter	Type	Default	Description
indicators	string[]	Core 6	FRED series IDs
as_of_date	string	today	Observation-date cutoff applies to indicators and regime inputs. Uses latest stored revisions, not historical vintages; does not reconstruct what was known on that date.
include_history	boolean	false	Include trailing data
history_periods	number	12	Periods of history

Example response:

{
  "snapshot_date": "2026-03-09",
  "regime": {
    "label": "expansion",
    "confidence": 0.7,
    "signals": ["Strong growth", "Normal yield curve"]
  },
  "indicators": [
    {
      "id": "UNRATE",
      "title": "Unemployment Rate",
      "latest": { "date": "2026-02-01", "value": 4.4, "units": "Percent" },
      "changes": { "yoy": 4.76 },
      "context": {
        "percentile_10y": 66.4,
        "z_score_10y": -0.1,
        "direction": "rising"
      }
    }
  ]
}

`explain_macro_change`

Analyzes what changed in a specific indicator.

Parameter	Type	Default	Description
indicator	string	required	FRED series ID
period	string	"1m"	1m, 3m, 6m, 1y, ytd

`compare_macro_regimes`

Compares current conditions to historical periods.

Parameter	Type	Default	Description
compare_to	string[]	auto	Dates or named regimes, e.g. ["2008_crisis"]. The auto default compares 2008_crisis and 2020_covid.
indicators	string[]	Core 5	Indicators to compare

Named regimes: 2008_crisis, 2020_covid, 1970s_stagflation, 2001_dotcom, 1990s_expansion, volcker_era

REST API Reference

Base URL: https://api.meridianapi.io

GET/v1/snapshot

Get current macro indicator values with historical context. Same data as the get_macro_snapshot MCP tool.

🔐 Bearer token required

Parameters

indicators · string — Comma-separated series IDs (e.g. UNRATE,CPIAUCSL)

as_of_date · string — Observation-date cutoff (YYYY-MM-DD), not vintage-aware historical reconstruction

include_history · boolean — Include trailing historical data

curl -H "Authorization: Bearer mrd_xxx" \
  "https://api.meridianapi.io/v1/snapshot?indicators=UNRATE,CPIAUCSL"

GET/v1/explain

Analyze what changed in a specific indicator over a period. Same data as the explain_macro_change MCP tool.

🔐 Bearer token required

Parameters

indicator · string — Series ID (required)

period · string — 1m, 3m, 6m, 1y, or ytd

GET/v1/compare

Compare current conditions to historical periods. Same data as the compare_macro_regimes MCP tool.

🔐 Bearer token required

Parameters

compare_to · string — Comma-separated dates or named regimes

indicators · string — Comma-separated series IDs

GET/v1/seriesPublic

Search the complete stored catalogue with source, category, frequency, freshness, observation count, and health metadata.

Parameters

source · string — Filter by source, such as Eurostat or EIA

category · string — Filter by normalized category

frequency · string — Filter by DAILY, WEEKLY, MONTHLY, QUARTERLY, or ANNUAL

q · string — Search title or series ID

limit · number — Page size: default 100, maximum 500.

offset · number — Non-negative integer, default 0. Follow pagination.nextOffset until null, preserving filters. Results can change between requests; deduplicate by series ID.

GET/v1/catalog/coveragePublic

Live catalogue counts by source, category, frequency, usefulness bucket, freshness, and operational health.

GET/v1/series/:idPublic

Get details and up to 20 recent observations for a specific series.

Parameters

:id · path — Series ID (e.g. UNRATE, GDP, BTC-USD)

GET/v1/dashboardPublic

Full economy dashboard — regime classification, 8 categories, 33 key indicators with values, percentiles, and direction.

POST/v1/queryPublic

Natural language query — ask a question about the economy in plain English.

Parameters

question · string — Your question (in request body as JSON)

curl -X POST https://api.meridianapi.io/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "How is inflation trending?"}'

GET/v1/health/dataPublic

Data quality health check — stale series, out-of-range values, reconciliation status.

Data Coverage

500+ stored series across 9 sources, spanning official macro data and curated market context. Use the live Data Catalog for exact counts, dates, and health.

🇺🇸 U.S. Macro (FRED) — 64 curated series

GDP & Growth

GDPGDPC1A191RL1Q225SBEA

Inflation

CPIAUCSLCPILFESLPCEPIPCEPILFEPPIFISMICH

Employment

UNRATEPAYEMSICSACCSAJTSJOLAWHAETPCES0500000003

Interest Rates

FEDFUNDSDFFDPRIME

Yield Curves

DGS1MODGS3MODGS6MODGS1DGS2DGS5DGS10DGS20DGS30T10Y2YT10Y3MT10YIET5YIE

Housing

MORTGAGE30USHOUSTPERMITCSUSHPINSAMSPUS

Markets

SP500DEXUSEUDTWEXBGSVIXCLS

Commodities

DCOILWTICOGOLDAMGBD228NLBM

Money Supply

M2SLWALCL

Trade & Fiscal

BOPGSTBFYFSDGFDEBTN

Consumer & Production

UMCSENTRSAFSINDPROTCUDGORDER

Credit

DRTSCILMTOTCI

🇪🇺 European Macro — ECB and Eurostat

Inflation

HICPCore HICP

Interest Rates

MRO RateDeposit Facility

Money & Growth

M3GDP GrowthUnemployment

FX & Bonds

EUR/USDEUR/GBPEUR/JPYDE 10Y Yield

Cross-country and institutional macro

OECD

Leading indicatorsBusiness confidenceConsumer confidenceLabourProductivity

IMF

GDPInflationCurrent accountReservesFiscal balanceDebt

US Treasury

Daily debt amountsMonthly average interest rates

EIA

Oil inventoriesGas inventoriesOil production

🌍 Global Development (World Bank)

Development

GDP per capitaLife expectancyPopulation growthCO2 emissions...

Trade & Finance

Trade % GDPFDIRemittancesExternal debt...

📈 Markets (Yahoo Finance) — 46 assets

Stocks (20)

AAPLMSFTGOOGAMZNNVDAMETATSLABRK-BJPMVUNHHDPGMAJNJXOMAVGOCOSTLLYWMT

Crypto (10)

BTC-USDETH-USDSOL-USDBNB-USDXRP-USDADA-USDDOGE-USDDOT-USDAVAX-USDMATIC-USD

ETFs (10)

SPYQQQIWMGLDTLTEFAVWOHYGXLFXLE

Indices (6)

^GSPC^DJI^IXIC^RUT^VIX^TNX

Live coverage: 500+ stored series across FRED, ECB, Eurostat, OECD, IMF, World Bank, US Treasury, EIA, and Yahoo Finance. Each source follows its own publication cadence.

Python and JavaScript

These examples use standard-library HTTP clients. Meridian packages are not currently published on PyPI or npm. Recent observations are public; use an API key for authenticated tools.

Python 3

import json
from urllib.request import urlopen

with urlopen(
    "https://api.meridianapi.io/v1/series/UNRATE",
    timeout=15,
) as response:
    series = json.load(response)
print(series["observations"][-1])

Node.js 20+

const response = await fetch(
  "https://api.meridianapi.io/v1/series/UNRATE",
  { signal: AbortSignal.timeout(15000) },
);
if (!response.ok) throw new Error("HTTP " + response.status);
const series = await response.json();
console.log(series.observations.at(-1));

Authentication

API keys start with mrd_ and are passed as Bearer tokens:

Authorization: Bearer mrd_your_api_key_here

Authenticated endpoints

/v1/snapshot, /v1/explain, /v1/compare and historical tools require a Bearer token

Public endpoints

/v1/series, /v1/series/:id, /v1/catalog/coverage, /v1/dashboard, /v1/query and /v1/health/data need no authentication

Get account access through /signup or /login, then create and rotate real API keys in Account. Docs examples use placeholder keys only.

Rate Limits

Plan	Requests / month	Price
Free	1,000	$0
Pro	50,000	$49/mo
Enterprise	500,000 fair-use	$299/mo

Limits depend on the route and plan. Public responses do not consistently include rate-limit headers. Handle HTTP 429 and honour Retry-After when present; otherwise use bounded backoff. For key creation, send an Idempotency-Key (16–128 ASCII letters, digits, underscores or hyphens) and reuse it on every retry of that action. A 409 KEY_CREATION_ALREADY_COMPLETED identifies the created key but cannot recover its secret; review and revoke that key before explicitly creating a replacement. Never retry with a new identifier automatically. Do not automatically retry checkout after an ambiguous network failure. A successful HTTP response can still contain per-indicator errors; inspect the response body.

Meridian Documentation

Quickstart

1Get an API Key

2Connect via MCP

Connect Meridian over MCP

3Try It

4Or Use the REST API

Freshness is visible, not hidden

Interfaces

MCP Tools

REST API

Python

JavaScript

Implementation guides

Inflation API

Unemployment API

Macro data server

AI agent macro data

Macro data API for AI agents

Fintech macro API

MCP Tools Reference

Response walkthroughs

get_macro_snapshot

explain_macro_change

compare_macro_regimes

REST API Reference

Data Coverage

🇺🇸 U.S. Macro (FRED) — 64 curated series

GDP & Growth

Inflation

Employment

Interest Rates

Yield Curves

Housing

Markets

Commodities

Money Supply

Trade & Fiscal

Consumer & Production

Credit

🇪🇺 European Macro — ECB and Eurostat

Inflation

Interest Rates

Money & Growth

FX & Bonds

Cross-country and institutional macro

OECD

IMF

US Treasury

EIA

🌍 Global Development (World Bank)

Development

Trade & Finance

📈 Markets (Yahoo Finance) — 46 assets

Stocks (20)

Crypto (10)

ETFs (10)

Indices (6)

Python and JavaScript

Python 3

Node.js 20+

Authentication

Rate Limits

Ready to get started?

`get_macro_snapshot`

`explain_macro_change`

`compare_macro_regimes`