透過 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` ，結尾不可加上斜線。
工具缺失	僅可使用上面列出的公共工具。
工具回傳問題	讀取其結構化的 status、code、detail 及請求 ID。請參閱錯誤與配額。