Connect through MCP

Use the same Narwhal key and public API schemas from an MCP client.

Narwhal exposes one stateless Streamable HTTP MCP endpoint. It uses the same enabled data APIs, response schemas, authentication, and quota as REST.

Connect

Add the remote server URL and Bearer header to an MCP client that supports authenticated Streamable HTTP.

Client-neutral field map

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

This is a field map, not a copy-paste file. Replace YOUR_NARWHAL_API_KEY through your client's secure secret setting. JSON does not expand shell variables by itself, and MCP clients use different environment-variable syntax.

Do not paste a real key into a shared configuration file.

Available tools

tools/list returns the public read-only tools enabled for this release profile. The catalogue below is the public tool set, not a promise that every source has a value for every input.

economics_get_cpieconomics_get_inflationeconomics_get_unemploymenteconomics_get_labour_force_participationeconomics_get_gdpeconomics_get_gdp_growtheconomics_get_tradeeconomics_get_trade_exportseconomics_get_trade_importseconomics_get_cpi_historyeconomics_get_inflation_historyeconomics_get_unemployment_historyeconomics_get_labour_force_participation_historyeconomics_get_gdp_historyeconomics_get_gdp_growth_historyeconomics_get_trade_historyeconomics_get_trade_exports_historyeconomics_get_trade_imports_historyfx_get_ratesfx_get_rate_historyfx_convert_currencyfx_get_rate_barscommodities_get_spot_pricecommodities_get_price_historycommodities_list_palmoil_physical_seriescommodities_get_palmoil_physical_pricecommodities_get_palmoil_physical_observationscommodities_list_physical_seriescommodities_get_physical_seriescommodities_get_physical_latestcommodities_get_physical_observationseconomics_list_releaseseconomics_get_releaseevents_listevents_getpredictions_list_topicspredictions_get_topicpredictions_list_eventspredictions_get_scalarpredictions_get_extremepredictions_get_timingpredictions_get_binarypredictions_get_scalar_historypredictions_get_extreme_historypredictions_get_timing_historypredictions_get_binary_historypredictions_get_policy_pathpredictions_get_policy_path_historycalendars_list_holidayscalendars_get_holidays_on_datecalendars_get_next_holidayeconomics_get_yield_curveeconomics_get_yield_curve_history

Arguments and results

Latest-release tools accept country and optional period. History tools accept country, optional start and end, plus limit and cursor for pagination.

Tool arguments

{
  "country": "USA",
  "period": "2026-07"
}

For the two directional trade tools, MCP uses "product": { "classification": "HS2022", "code": "27" }. REST represents the same filter as separate classification and product query parameters.

Tool	Period	Other arguments
`economics_get_cpi`	`YYYY-MM`	None
`economics_get_inflation`	`YYYY-MM`	None
`economics_get_unemployment`	`YYYY, YYYY-MM, or YYYY-QN`	None
`economics_get_labour_force_participation`	`YYYY, YYYY-MM, or YYYY-QN`	None
`economics_get_gdp`	`YYYY-QN`	None
`economics_get_gdp_growth`	`YYYY-QN`	None
`economics_get_trade`	`YYYY or YYYY-MM`	None
`economics_get_trade_exports`	`YYYY or YYYY-MM`	`partner` and nested `product` are accepted, but filtered totals are not yet published.
`economics_get_trade_imports`	`YYYY or YYYY-MM`	`partner` and nested `product` are accepted, but filtered totals are not yet published.
`economics_get_cpi_history`	`YYYY-MM`	`start`, `end`, `limit`, and `cursor`
`economics_get_inflation_history`	`YYYY-MM`	`start`, `end`, `limit`, and `cursor`
`economics_get_unemployment_history`	`YYYY, YYYY-MM, or YYYY-QN`	`start`, `end`, `limit`, and `cursor`
`economics_get_labour_force_participation_history`	`YYYY, YYYY-MM, or YYYY-QN`	`start`, `end`, `limit`, and `cursor`
`economics_get_gdp_history`	`YYYY-QN`	`start`, `end`, `limit`, and `cursor`
`economics_get_gdp_growth_history`	`YYYY-QN`	`start`, `end`, `limit`, and `cursor`
`economics_get_trade_history`	`YYYY-MM`	`start`, `end`, `limit`, and `cursor`
`economics_get_trade_exports_history`	`YYYY-MM`	`start`, `end`, `limit`, and `cursor`
`economics_get_trade_imports_history`	`YYYY-MM`	`start`, `end`, `limit`, and `cursor`

Successful tool calls return schema-valid structuredContent plus the same JSON serialized as text for client compatibility. MCP problems use the same public status and code vocabulary as REST.

Quota behavior

Initialization and tool discovery do not consume data quota. Each successful tools/call consumes exactly one request, just like one successful REST call.

First tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

The Free beta includes 3,000 successful requests per UTC month, plus 30 requests per minute. Quota state is returned in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; short-window state is returned in X-RateLimit-Short-Limit, X-RateLimit-Short-Remaining, and X-RateLimit-Short-Reset. Short-window throttling returns 429 rate_limit_exceeded; monthly exhaustion returns 429 quota_exhausted.

Troubleshooting

Symptom	Check
`401 invalid_api_key`	Confirm the exact Bearer header and that the key is still active.
Connection follows a redirect	Use exactly `https://api.narwhalapi.com/mcp` without a trailing slash.
Tool is missing	Only the public tools listed above are available.
Tool returns a problem	Read its structured status, code, detail, and request ID. See Errors and quota.