LLM 에이전트 금융 데이터 접근 권한을 Narwhal로 부여하기

MCP로 에이전트 연결하기

Narwhal은 MCP에 Streamable HTTP를 사용합니다. REST와 MCP는 하나의 계정, 하나의 API 키, 하나의 크레딧 잔액을 공유하므로 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를 쓰며, 발표일은 발표 캘린더에서 가져옵니다.