LLM エージェントに Narwhal へのアクセスを与える

MCP でエージェントを接続する

Narwhal の MCP は Streamable HTTP を使います。REST と MCP は1つのアカウント、1つの API キー、1つのクレジット残高を共有するため、REST で使うキーがそのままエージェントの認証にも使えます。REST のベース URL は https://api.narwhalapi.com、MCP 接続は https://api.narwhalapi.com/mcp です。MCP クライアントにエンドポイント URL を渡し、キーは Authorization ヘッダーで送ります。

1. API キーを保管する サインアップで無料キーを取得し、環境変数 NARWHAL_API_KEY に保存します。エンドポイントはキーをヘッダーでのみ受け付け、形式は Authorization: Bearer <key> です。
2. Claude Code に Narwhal を追加する コマンドでは HTTP トランスポートと Authorization ヘッダーを使います。このコマンドはサーバーを narwhal という名前で追加し、キーを NARWHAL_API_KEY から読み取ります。Claude Code では、claude mcp list または /mcp でサーバーの接続状況を確認できます。
   MCP サーバーを追加する

   claude mcp add --transport http narwhal https://api.narwhalapi.com/mcp \
     --header "Authorization: Bearer ${NARWHAL_API_KEY}"

3. 代わりにプロジェクト設定を使う プロジェクトの .mcp.json には、URL とヘッダーに加えて "type": "http" を入れます。Narwhal の設定は mcpServers の下に置き、サーバー名は narwhal にします。headers エントリに Authorization ヘッダーを入れます。これは Claude Code のプロジェクト設定による方法で、上のコマンドはコマンドラインによる方法です。
   プロジェクト用の .mcp.json

   {
     "mcpServers": {
       "narwhal": {
         "type": "http",
         "url": "https://api.narwhalapi.com/mcp",
         "headers": { "Authorization": "Bearer ${NARWHAL_API_KEY}" }
       }
     }
   }

4. Cursor または Codex で接続を設定する Cursor では、プロジェクトなら .cursor/mcp.json、ユーザー全体なら ~/.cursor/mcp.json を使い、url と headers を指定します。Cursor はヘッダー内の ${env:NAME} を展開するので、環境変数名には NARWHAL_API_KEY を使います。Codex では ~/.codex/config.toml を開き、セクション [mcp_servers.narwhal] を使います。url = "https://api.narwhalapi.com/mcp" と bearer_token_env_var = "NARWHAL_API_KEY" を設定すると、後者がキーを含む環境変数の名前になります。
5. ツール一覧を読む tools/list で利用可能なツールを取得します。初期化ではサーバーが Narwhal API と名乗ります。下のリクエストは、クライアント設定と同じ Authorization ヘッダーを送ります。ツール呼び出しの結果は構造化 JSON で、エラーにはステータス、コード、詳細、リクエスト ID が含まれます。
   ツール一覧をリクエストする

   curl -s -X POST https://api.narwhalapi.com/mcp \
     -H "Authorization: Bearer $NARWHAL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

経済指標では、ツール一覧に CPI 用の economics_get_cpi、インフレ用の economics_get_inflation、GDP 成長率用の economics_get_gdp_growth、利回り用の economics_get_yield_curve があります。コモディティのツールは commodities_get_spot_price と commodities_get_price_history です。為替レートでは、レート、通貨換算、レート履歴のどれが必要かに応じて fx_get_rates、fx_convert_currency、fx_get_rate_history を使います。接続の詳細はMCP ガイドを参照してください。

独自のエージェントコードでは、MCP クライアントライブラリでエンドポイントに接続するか、REST 呼び出しをツールとして使います。REST でも同じ Authorization ヘッダーと API キーを使います。どちらの方法でも、エージェントは Narwhal のデータ API から祝日、経済カレンダー、経済指標、コモディティのスポット価格、為替レート、予測市場のオッズを取得できます。

コードなしでチャットアプリから接続する

Claude アプリには、一部の組織向けにベータ版でリクエストヘッダー付きのカスタムコネクタがあります。この接続方法については、Claude アプリの MCP ページを参照してください。Narwhal のエンドポイントは API キーを Authorization ヘッダーで受け取るため、ここではリクエストヘッダーへの対応が重要です。チャットアプリには、MCP 接続でそのヘッダーを送る手段が必要です。

ChatGPT アプリは、サインイン不要のサーバーか OAuth のサーバーに接続します。Narwhal の API キーヘッダーによる接続は使えません。ChatGPT でデータについて質問したい場合に使える選択肢は、AI エージェント向け Narwhal を参照してください。

どの接続を使うか

エージェントは自分のクレジットを使いますか？

はい。成功した tools/call は、REST と同じキーで1コールとして数えられ、対応する REST 呼び出しと同じ料金です。初期化と tools/list は無料です。エージェントのデータ呼び出しと REST 呼び出しは同じクレジットを使います。ツール一覧の読み取りは、ツールにデータを求めることとは別なので、データリクエストを使わずに利用可能なツールを確認できます。

エージェントはデータを変更できますか？

いいえ。Narwhal の MCP ツールは読み取り専用です。エージェントは calendars_list_holidays または calendars_get_next_holiday で祝日を、economics_list_releases で公表日を読めます。ツール一覧には、予測市場データ用の predictions_list_topics、predictions_get_policy_path、events_list も含まれます。

エージェントが接続できない場合は？

末尾にスラッシュを付けない URL と、Authorization: Bearer <key> 形式のヘッダーを使ってください。URL は https://api.narwhalapi.com/mcp、ヘッダーには NARWHAL_API_KEY のキーを入れます。Claude Code では claude mcp list で接続の有無を確認でき、/mcp も使えます。誤ったキーでは 401 invalid_api_key が返ります。このエラーのレスポンスには、ステータスとコードに加えて詳細とリクエスト ID が含まれます。

実例：次の米国 CPI 公表日を尋ねる

2026年10月24日時点で、次の米国 CPI 公表日は2026年11月10日 13:30 UTC です。Claude Code にサーバーを追加したら、「次の米国 CPI 公表日はいつですか？」と尋ねます。エージェントは米国を対象に economics_list_releases を呼び出し、公表日と時刻を答えます。

まず公表日についての質問から始めます。Claude Code はカレンダーの答えを得るために米国向けに economics_list_releases を使い、この2026年10月24日の例では2026年11月10日 13:30 UTC になります。ツール呼び出しは1リクエストを使います。CPI の値について知りたい場合は、そのデータ用の別ツールである economics_get_cpi を使います。公表日はリリースカレンダーから得られます。