通过 MCP 连接

从MCP客户端使用相同的Narwhal密钥和公开API架构。

Narwhal 提供一个无状态、可流式传输的 HTTP MCP 端点，并与 REST 使用相同的六个数据 API、响应架构、身份验证和配额。

连接

将远程服务器 URL 和 Bearer 标头添加到支持经认证 Streamable HTTP 的 MCP 客户端。

与客户端无关的字段映射

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

这是字段映射，而不是可直接复制粘贴的文件。请替换 YOUR_NARWHAL_API_KEY 通过客户端的安全密钥设置。JSON 不会自行展开 shell 变量，MCP 客户端使用不同的环境变量语法。

不要将真实密钥粘贴到共享配置文件中。

可用工具

tools/list 返回 33 个只读工具：18 个 Economics 操作，以及 FX、Equities、SEC 申报、Palmoil 和 Calendars 各 3 个操作。

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_currencyequities_list_instrumentsequities_get_instrumentequities_get_barscompanies_searchcompanies_getcompanies_list_filingscommodities_discover_physical_seriescommodities_get_oil_palm_ffb_pricecommodities_get_oil_palm_ffb_price_observationscalendars_list_holidayscalendars_get_holidays_on_datecalendars_get_next_holiday

参数和结果

最新发布工具接受 country 以及可选项 period。历史数据工具接受 country，可选 start 和 end，另加 limit 和 cursor 用于分页。

工具参数

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

对于两个有方向的贸易工具，MCP 使用 "product": { "classification": "HS2022", "code": "27" }。REST 将相同的筛选条件表示为独立的 classification 和 product 查询参数。

工具	期间	其他参数
`economics_get_cpi`	`YYYY-MM`	无
`economics_get_inflation`	`YYYY-MM`	无
`economics_get_unemployment`	`YYYY, YYYY-MM, or YYYY-QN`	无
`economics_get_labour_force_participation`	`YYYY, YYYY-MM, or YYYY-QN`	无
`economics_get_gdp`	`YYYY-QN`	无
`economics_get_gdp_growth`	`YYYY-QN`	无
`economics_get_trade`	`YYYY or YYYY-MM`	无
`economics_get_trade_exports`	`YYYY or YYYY-MM`	`partner` 以及嵌套内容 `product` 可以接受，但筛选后的总数尚未发布。
`economics_get_trade_imports`	`YYYY or YYYY-MM`	`partner` 以及嵌套内容 `product` 可以接受，但筛选后的总数尚未发布。
`economics_get_cpi_history`	`YYYY-MM`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_inflation_history`	`YYYY-MM`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_unemployment_history`	`YYYY, YYYY-MM, or YYYY-QN`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_labour_force_participation_history`	`YYYY, YYYY-MM, or YYYY-QN`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_gdp_history`	`YYYY-QN`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_gdp_growth_history`	`YYYY-QN`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_trade_history`	`YYYY-MM`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_trade_exports_history`	`YYYY-MM`	`start`, `end`, `limit`，以及 `cursor`
`economics_get_trade_imports_history`	`YYYY-MM`	`start`, `end`, `limit`，以及 `cursor`

成功的工具调用返回符合架构的 structuredContent 以及为客户端兼容性而序列化为文本的相同 JSON。MCP 问题使用与 REST 相同的公开状态和代码词汇。

配额行为

初始化和工具发现不会消耗数据配额。每次成功的 tools/call 恰好消耗一次请求，与一次成功的 REST 调用相同。

首次 tools/call

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

免费测试版包括 3,000 每个 UTC 月的成功请求数，加上 30 每分钟请求数，突发容量为 5。额度状态返回于 X-RateLimit-Limit, X-RateLimit-Remaining，以及 X-RateLimit-Reset；短窗口状态在 X-RateLimit-Short-Limit, X-RateLimit-Short-Remaining，以及 X-RateLimit-Short-Reset。短时窗口限流会返回 429 rate_limit_exceeded；每月额度耗尽时返回 429 quota_exhausted.

故障排查

症状	检查
`401 invalid_api_key`	确认确切的 Bearer 标头，并确认密钥仍处于活动状态。
连接会跟随重定向	请准确使用 `https://api.narwhalapi.com/mcp` 不带结尾斜杠。
工具缺失	仅可使用上面列出的公共工具。
工具返回问题	读取结构化状态、代码、详情和请求 ID。参见错误与配额.