Claude Agent SDK에서 Narwhal API 사용하기

설정할 내용

Claude Agent SDK로는 Python을 통해 에이전트에 질문을 전달할 수 있습니다. 여기서는 Narwhal MCP에 연결해 데이터 영역마다 질문을 보내는 스크립트를 만듭니다. 질문은 PROMPTS 딕셔너리에 담고, 서버 연결과 도구 권한은 ClaudeAgentOptions에 설정합니다. 스크립트는 각 영역의 이름과 에이전트가 돌려준 메시지를 출력합니다.

API 키 설정

1. 무료 Narwhal 키 만들기 narwhalapi.com/signup에서 키를 만드세요. Narwhal은 하나의 계정과 하나의 API 키로 여러 데이터 API를 사용하므로, 이 스크립트의 모든 데이터 영역에 같은 키가 쓰입니다.
2. 환경 변수에 키 저장하기 키를 NARWHAL_API_KEY라는 환경 변수에 넣으세요. Python 스크립트는 이 변수를 읽어 Bearer 헤더에 쓰고, Claude Code 설정도 이름으로 이 변수를 참조합니다. 에이전트를 시작하는 환경에서 이 변수를 사용할 수 있게 해 두세요. 환경 변수의 값에는 키만 넣고, 헤더 설정에는 Bearer 접두사를 그대로 둡니다.
   API 키 환경 변수

   export NARWHAL_API_KEY="YOUR_KEY"

Claude Code로 질문하기

Claude Code 사용자는 JSON 설정으로 Narwhal을 MCP 서버로 추가할 수 있습니다. Python 스크립트를 작성하지 않고 질문하려는 경우에 쓰는 방법입니다. 서버 주소는 SDK에서 쓰는 MCP 주소와 같고, 연결 유형은 http입니다. Claude Code에는 서버 설정을, Python SDK에는 ClaudeAgentOptions 설정을 사용하세요.

1. MCP 서버 설정 추가하기 서버 이름을 narwhal로 하여 JSON 설정을 추가하세요. Authorization 헤더에는 환경 변수 참조를 그대로 두어야 설정이 NARWHAL_API_KEY에서 키를 읽습니다.
   MCP 서버 설정

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

2. 평범한 문장으로 질문하기 “2026년 12월 25일은 미국 공휴일인가요?”라고 물어보세요. 에이전트가 질문을 보고 도구를 고릅니다. 영역별 예시에는 발표일, 경제 데이터, 원자재, 환율, 예측 시장에 대한 질문도 있습니다.

코드로 데이터 가져오기

claude-agent-sdk를 설치한 뒤, 환경에서 키를 사용할 수 있는 상태로 Python 스크립트를 실행하세요. mcp_servers 설정이 MCP URL과 Authorization 헤더를 제공합니다. allowed_tools의 와일드카드 덕분에 에이전트가 모든 Narwhal 도구를 쓸 수 있습니다. query를 호출할 때마다 질문과 공통 옵션이 전달됩니다. 코드는 asyncio와 os, 그리고 SDK의 ClaudeAgentOptions와 query를 가져옵니다.

pip install claude-agent-sdk

import asyncio
import os
from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    mcp_servers={
        "narwhal": {
            "type": "http",
            "url": "https://api.narwhalapi.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
        }
    },
    allowed_tools=["mcp__narwhal__*"],
)

PROMPTS = {
    "holidays": "Is 25 December 2026 a public holiday in the United States?",
    "release dates": "When is the US CPI release in November 2026?",
    "economics": "What is the latest US CPI index?",
    "commodities": "What is the Brent spot price in dollars a barrel?",
    "FX": "What are the USD/EUR and USD/IDR rates?",
    "predictions": "What are the Fed rate odds for its next meeting?",
}

async def main():
    for area, question in PROMPTS.items():
        print("##", area)
        async for message in query(prompt=question, options=options):
            print(message)

asyncio.run(main())

PROMPTS의 항목은 자연어 질문으로 유지하세요. 원하는 정보를 말로 설명하면 에이전트가 도구를 고릅니다. 루프는 질문을 하나씩 보내고 해당 영역의 메시지를 출력합니다. 특정 영역만 물어보려면 이어지는 예시처럼 그 영역의 질문을 같은 options와 함께 쓰세요. main 안에서는 async for가 query의 각 메시지를 출력한 뒤에야 바깥 루프가 다음 영역으로 넘어갑니다. 개별 예시는 전체 스크립트의 import와 options를 재사용하며, 해당 영역의 질문만 담은 더 작은 PROMPTS 딕셔너리를 씁니다.

일정에 맞춰 실행하기

cron이나 작업 실행기에서 스크립트를 실행하고, 예약 실행되는 스크립트에서 NARWHAL_API_KEY를 사용할 수 있게 하세요. 도구 호출이 성공할 때마다 키의 크레딧에서 호출 1회가 차감됩니다. 스크립트는 PROMPTS의 질문을 차례로 처리하므로, 예약 실행 한 번에 그 딕셔너리에 있는 모든 영역을 묻습니다. 예약된 에이전트가 물어봐야 할 질문은 그 딕셔너리에 넣어 두세요.

Claude Agent SDK로 공휴일 조회하기

특정 날짜가 공휴일인지 물어보세요. 이 질문은 날짜와 국가를 모두 지정합니다. 대응하는 REST는 https://api.narwhalapi.com/v1/calendars/holidays/USA/2026이며 holidays를 읽으면 됩니다. 각 항목에는 date와 name이 있습니다. 예시에서는 options에 이미 정의한 MCP 연결을 사용합니다.

PROMPTS = {
    "holidays": "Is 25 December 2026 a public holiday in the United States?",
}
async def main():
    async for message in query(prompt=PROMPTS["holidays"], options=options):
        print(message)  # REST counterpart field: holidays

asyncio.run(main())

Claude Agent SDK로 발표일 조회하기

발표일을 알고 싶다면 지표 이름과 월을 지정해 물어보세요. 발표일은 경제 캘린더에서 가져옵니다. 대응하는 REST는 https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-11-01&end_date=2026-11-30&limit=100입니다. releases를 읽으면 되고, 각 항목에는 at, period, topic, status가 있습니다. CPI 지수 값은 경제 데이터 질문을 사용하세요.

PROMPTS = {
    "release dates": "When is the US CPI release in November 2026?",
}
async def main():
    async for message in query(prompt=PROMPTS["release dates"], options=options):
        print(message)  # REST counterpart field: releases

asyncio.run(main())

Claude Agent SDK로 경제 데이터 조회하기

경제 데이터 도구를 통해 미국 CPI 지수를 물어보세요. Narwhal 경제 데이터에는 인플레이션, GDP, 수익률도 포함됩니다. CPI의 REST는 https://api.narwhalapi.com/v1/economics/USA/cpi/observations?start=2025-09이며, observations에 period와 value가 담긴 항목이 들어 있습니다. 프롬프트는 에이전트에게 지수를 묻고, REST URL은 관측값의 시작 기간을 지정합니다.

PROMPTS = {
    "economics": "What is the latest US CPI index?",
}
async def main():
    async for message in query(prompt=PROMPTS["economics"], options=options):
        print(message)  # REST counterpart field: observations

asyncio.run(main())

Claude Agent SDK로 원자재 조회하기

Brent 프롬프트처럼 질문에 원자재 이름과 단위를 넣으세요. 대응하는 REST는 https://api.narwhalapi.com/v1/commodities/spot/BRENT/USD이며 price 필드를 읽습니다. Narwhal은 현물 코드를 사용하며, 예를 들면 XAU, XAG, XPT, XPD, XCU, BRENT, WTI가 있습니다. 이 예시는 전체 스크립트의 Brent 질문을 그대로 씁니다.

PROMPTS = {
    "commodities": "What is the Brent spot price in dollars a barrel?",
}
async def main():
    async for message in query(prompt=PROMPTS["commodities"], options=options):
        print(message)  # REST counterpart field: price

asyncio.run(main())

Claude Agent SDK로 환율 조회하기

필요한 통화쌍을 같은 질문에 함께 넣어 물어보세요. 이 프롬프트는 USD/EUR과 USD/IDR을 요청합니다. 대응하는 REST는 https://api.narwhalapi.com/v1/fx/rates/USD?currencies=EUR,IDR이며, 각 항목에 currency와 rate가 있는 rates를 반환합니다. 프롬프트와 URL 모두 통화를 지정하며, MCP 에이전트는 프롬프트에 맞춰 도구를 선택합니다.

PROMPTS = {
    "FX": "What are the USD/EUR and USD/IDR rates?",
}
async def main():
    async for message in query(prompt=PROMPTS["FX"], options=options):
        print(message)  # REST counterpart field: rates

asyncio.run(main())

Claude Agent SDK로 예측 시장 조회하기

예측 시장 도구를 통해 Fed 금리 확률을 물어보세요. 대응하는 REST는 https://api.narwhalapi.com/v1/predictions/policy-paths/federal-reserve입니다. meetings를 읽으면 각 항목에 resolves_at, p_cut, p_hold, p_hike가 있습니다. 이 필드들은 결과 확정 시각과 인하, 동결, 인상 확률을 나타냅니다. 예시는 전체 스크립트와 같은 예측 시장 질문을 합니다.

PROMPTS = {
    "predictions": "What are the Fed rate odds for its next meeting?",
}
async def main():
    async for message in query(prompt=PROMPTS["predictions"], options=options):
        print(message)  # REST counterpart field: meetings

asyncio.run(main())

에이전트가 호출할 수 있는 도구를 제한하려면 어떻게 하나요?

allowed_tools의 와일드카드를 허용할 도구 이름으로 바꾸세요. CPI라면 mcp__narwhal__economics_get_cpi를 쓰면 됩니다. 이 도구를 명시하려면 ClaudeAgentOptions에 allowed_tools=["mcp__narwhal__economics_get_cpi"]를 설정하세요. 전체 스크립트는 질문이 모든 데이터 영역에 걸쳐 있어서 mcp__narwhal__*를 사용합니다.

별도의 Claude 이용 권한이 필요한가요?

네. 에이전트를 쓰려면 Narwhal API 키와 별도로 본인의 Claude 이용 권한이 필요합니다. Narwhal 키는 Narwhal로 가는 요청을 인증하며, REST와 MCP가 이 키를 함께 씁니다. 영역별 URL로 보내는 REST 요청에는 Authorization: Bearer YOUR_KEY를 보내세요. SDK 설정도 MCP 주소에 같은 헤더를 보냅니다.