通过 MCP 连接

通过 MCP 客户端使用同一个 Narwhal 密钥和公开 API 数据结构。

Narwhal 提供一个无状态的 Streamable 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 返回此发布配置启用的公开只读工具。以下目录是公开工具集，不承诺每个来源都会为每个输入提供值。

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_currencycommodities_list_palmoil_physical_seriescommodities_get_palmoil_physical_pricecommodities_get_palmoil_physical_observationscalendars_list_holidayscalendars_get_holidays_on_datecalendars_get_next_holidayeconomics_get_yield_curveeconomics_get_yield_curve_history

参数和结果

最新发布工具接受 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"] }
  }
}

Free 测试版包含 3,000 次成功请求（按 UTC 自然月计算），另有频率限制：每分钟 30 次请求。配额状态返回于 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。参见错误与配额。