Tavily MCP · 운영 노트

2026. 5. 11. 10:17ㆍAI/Claude ai

Tavily MCP · 운영 노트

MCP SERVER · USER SCOPE · CONNECTED

검색이 아니라
에이전트를 위한 리서치.

Tavily MCP는 LLM 에이전트가 웹에서 정보를 검색·추출·크롤·매핑할 수 있도록 설계된 통합 리서치 도구다. 일반 검색 API와 달리 응답이 LLM 컨텍스트에 곧바로 주입할 수 있는 형태로 정제되며, RAG와 자동화 에이전트의 1차 정보 소스로 자리잡았다.

Servertavily

Status✓ Connected

ScopeUser

Transportstdio

Quota1,000 credits / mo · Free

Installed2026-05-11

— 01

정의WHAT TAVILY IS

Tavily는 LLM/AI 에이전트 전용으로 설계된 리서치 API다. 일반 검색 엔진이 사용자에게 보여줄 결과 페이지를 반환한다면, Tavily는 모델이 그대로 토큰화해 추론에 사용할 수 있는 정제된 컨텍스트를 반환한다. tavily-mcp 는 이 API를 MCP 프로토콜로 노출하는 npm 기반 stdio 서버다.

일반 검색 vs Tavily

일반 검색 API (Brave, Google CSE)

제목·설명·URL 메타 위주
본문은 별도 fetcher 필요
인간 사용자 SERP를 모방
관련성 정렬은 검색 엔진 기준
요약·신뢰도 점수 없음

Tavily Search API

본문 발췌(content) 기본 포함
LLM 친화 응답 — 노이즈 제거
관련성 점수(score) 포함
AI 생성 답변(answer) 옵션 제공
이미지·뉴스·도메인 필터 내장

구조

01 / Host

Claude Code

MCP host. stdio로 tavily-mcp 자식 프로세스를 spawn 한다.

02 / Server

tavily-mcp

4개 도구를 MCP로 노출. 호출을 Tavily REST API로 위임한다.

03 / Backend

Tavily Research API

검색·추출·크롤·매핑. credit 기반 미터링.

핵심 가치

AI-native 응답 — 모델이 추가 파싱 없이 바로 사용할 수 있는 정돈된 결과
4-in-1 도구셋 — Search / Extract / Crawl / Map 을 하나의 MCP로 통합
관대한 무료 한도 — 카드 등록 없이 월 1,000 credit, 신청 즉시 사용
도메인 필터링 — include_domains / exclude_domains 로 신뢰 출처만 선별 가능
탑픽 답변 — include_answer 활성화 시 결과를 종합한 짧은 답변까지 반환

— 02

사용 방법FOUR TOOLS

설치되면 Claude Code의 도구 목록에 네 개의 도구가 노출된다. 자연어로 요청하면 에이전트가 의도에 맞는 도구를 선택해 호출한다.

도구 개요

tool · search

tavily-search CORE

주어진 쿼리에 대해 AI 친화적 검색 결과를 반환. 가장 자주 사용된다.

tool · extract

tavily-extract URL → TEXT

특정 URL의 본문을 마크다운/텍스트로 깨끗하게 추출.

tool · crawl

tavily-crawl SITE SWEEP

시작 URL에서 출발해 사이트를 순회하며 콘텐츠 수집.

tool · map

tavily-map STRUCTURE

본문 다운로드 없이 사이트 URL 트리만 빠르게 매핑.

tavily-search · 상세

가장 많이 쓰는 도구. search_depth 가 basic(1 credit) 또는 advanced(2 credits)이며, advanced는 본문 발췌 품질과 결과 다양성이 개선된다.

query: 필수. 자연어 검색어
search_depth: basic | advanced · 기본 basic
topic: general | news · 뉴스는 최신성 가중치 강화
days: 뉴스 모드에서 최근 N일 결과만 필터링
max_results: 1–20 · 기본 5
include_answer: boolean — 결과 종합 요약 동봉 여부
include_raw_content: boolean — 페이지 원문 포함 (RAG에 유용)
include_images: boolean — 이미지 URL 회수
include_domains: string[] — 신뢰 도메인만 검색
exclude_domains: string[] — 특정 도메인 제외

tavily-extract · 상세

크롤러가 아닌 단일/소수 URL의 본문 추출 전용. 모델이 회수한 검색 결과 URL을 더 깊이 읽고 싶을 때 보조 도구로 사용.

urls: 필수. string[] — 추출할 URL 목록
extract_depth: basic | advanced
format: markdown | text
include_images: boolean — 본문 이미지 URL 회수

크레딧 — basic: URL 5개당 1 credit, advanced: URL 5개당 2 credits

tavily-crawl · 상세

시작 URL에서 링크를 따라 사이트를 자동 순회. 도큐먼트 사이트 전체를 RAG 코퍼스로 만들거나 정책 페이지를 한 번에 수집할 때.

url: 필수. 시작 URL
max_depth: 링크 깊이 (기본 1)
max_breadth: 각 깊이의 최대 페이지 수 (기본 20)
limit: 총 페이지 상한
instructions: 자연어 가이드 — "프라이싱 페이지만 모아줘" 식
allow_external: boolean — 외부 도메인으로의 이탈 허용 여부
categories: string[] — Tavily 측 사전정의 카테고리 필터

tavily-map · 상세

본문은 가져오지 않고 사이트의 URL 구조만 빠르게 트리로 회수. 크롤 전 사전 조사에 유용.

url: 필수. 시작 URL
max_depth: 구조 탐색 깊이
max_breadth: 각 노드 최대 자식 수
limit: 총 URL 상한
instructions: 자연어 가이드

자연어 호출 예시

# Search
"FastAPI 0.115 마이그레이션 가이드 찾아줘, 공식 도메인 위주로"

# Extract
"이 URL 본문을 마크다운으로 정리해줘: https://example.com/post"

# Crawl
"docs.anthropic.com 의 가이드 섹션 전체를 크롤해서 요약해줘"

# Map
"nextjs.org 의 docs 사이드맵을 먼저 보여줘, 그다음 어떤 페이지를 크롤할지 정하자"

— 03

설치 내역WHAT WAS DEPLOYED

현재 호스트(C:\Users\sangk)에 user 스코프로 설치되어 있다. 이 PC의 모든 Claude Code 프로젝트에서 자동 적용된다.

실행된 설치 명령

claude mcp add tavily -s user \
  -e TAVILY_API_KEY=tvly-dev-loD5************************ \
  -- npx.cmd -y tavily-mcp

⚑ Windows 주의점

Brave MCP와 동일하게, Git Bash 환경에서 command: "npx" 로 등록하면 /c → C:/ 자동 경로 변환으로 실행이 실패한다. 반드시 npx.cmd 를 명시한다.

등록된 설정 (요약)

// C:\Users\sangk\.claude.json (user-scope mcpServers)
{
  "tavily": {
    "type": "stdio",
    "command": "npx.cmd",
    "args": ["-y", "tavily-mcp"],
    "env": {
      "TAVILY_API_KEY": "tvly-dev-loD5************************"
    }
  }
}

경로	역할
C:\Users\sangk\.claude.json	user 스코프 MCP 등록부 (정식 설정)
C:\projects\claude\mcp\mcp-servers.json	동작 중 MCP의 백업 사본
C:\projects\claude\mcp\tavily-mcp.html	본 운영 노트

상태 확인 명령

# 단일 서버 상태
claude mcp get tavily

# 전체 MCP 헬스체크
claude mcp list

# 제거가 필요할 때
claude mcp remove tavily -s user

ℹ Sibling MCP

현재 같은 user 스코프에 brave-search MCP도 함께 설치돼 있다. 일반 SERP가 필요하면 Brave, AI 컨텍스트가 필요하면 Tavily — 역할 분담을 유지하면 크레딧 소비를 줄일 수 있다.

— 04

주의사항OPERATIONAL CAUTIONS

⚠ 보안 — API 키 평문 노출

.claude.json 과 mcp-servers.json 양쪽에 TAVILY_API_KEY 가 평문으로 저장돼 있다.

git 추적에 잡히면 즉시 유출이므로 다음 조치를 권장한다 — .gitignore 에 mcp-servers.json 추가 · 평문 백업은 비공개 폴더로 이동 또는 삭제. 유출 의심 시 Tavily 대시보드의 Revoke 후 신규 키 발급.

크레딧 소비 메커니즘

도구 호출	소비	비고
search (basic)	1 credit	일반 쿼리 기본
search (advanced)	2 credits	응답 품질 ↑
extract (basic)	1 credit / 5 URLs	URL 5개 단위 과금
extract (advanced)	2 credits / 5 URLs	본문 정제 강화
crawl / map	방문 URL 수에 비례	대량 호출 시 폭주 주의

플랜

플랜	월 한도	특징	비용
Free (Dev)	1,000 credits	카드 등록 불요, 키 prefix `tvly-dev-`	$0
Pay-as-you-go	무제한	오버유즈는 청구	~$0.008 / credit (기준)
Business	맞춤	SLA, 우선순위 큐, 감사 로그	문의

알아두면 좋을 함정

크롤 폭주 — tavily-crawl 은 한 번에 수십~수백 페이지를 회수할 수 있다. limit·max_depth·max_breadth 를 반드시 지정하지 않으면 크레딧이 빠르게 소모된다.
advanced 남발 금지 — basic 으로 충분한 쿼리에 advanced 를 쓰면 크레딧이 두 배. 본문 발췌 품질이 정말 필요한 경우에만 advanced.
도메인 화이트리스트 — 신뢰 출처만 사용하는 워크플로(예: 공식 문서, 학술)에선 include_domains 로 노이즈 결과 사전 차단.
뉴스 모드 freshness — topic: "news" 일 때만 days 가 의미를 갖는다. general 토픽에선 무시된다.
이미지 회수 비용 — include_images=true 와 image description 옵션은 응답 토큰 사용량을 크게 늘린다. 모델 입력 토큰 한도와 함께 고려.
robots/접근 제한 — 크롤은 robots.txt 와 사이트 접근 제어를 따른다. 보호된 콘텐츠는 회수 불가.
QPS 한도 — 짧은 시간에 병렬로 다수 호출 시 일부 요청이 throttle 될 수 있다. 다중 에이전트 시나리오에서는 큐잉 권장.

Brave 와 함께 쓰는 패턴

저비용 디스커버리 → 고품질 확장 — Brave 로 자유 검색 → 흥미로운 URL 만 Tavily Extract.
지역/현지 정보 — 지역 비즈니스 질의는 Brave 의 brave_local_search, 그 외 사실 조사는 Tavily.
RAG 코퍼스 구축 — Tavily Map 으로 사이트맵 → 필요한 섹션만 Crawl → 모델에 주입.
크레딧 보호 — 단순 한 줄 답변을 얻기 위해 Tavily 를 쓰지 말 것. Brave 가 더 저렴하다 (Tavily 는 무료라도 1,000 한도).

롤백·재설치 시나리오

# 1) 제거
claude mcp remove tavily -s user

# 2) 캐시 정리(선택)
npm cache clean --force

# 3) 새 키로 재설치
claude mcp add tavily -s user \
  -e TAVILY_API_KEY=<NEW_KEY> \
  -- npx.cmd -y tavily-mcp

# 4) 연결 확인
claude mcp get tavily   # → Status: ✓ Connected

체크리스트

설치 직후 — claude mcp get tavily 로 ✓ Connected 확인
도구 4종 워밍업 — search · extract · map · crawl 을 각 1회씩 호출해 정상 회수 확인
키 보호 — 평문이 들어간 파일들의 git 추적 차단 또는 비공개 폴더로 이동
월별 사용량 — Tavily 대시보드에서 잔여 credit 모니터링 (1,000 한도 도달 시 다음 달 1일까지 호출 실패)
도구 선택 기본기 — "검색이면 search, URL 정독이면 extract, 사이트 통째면 crawl, 지도 먼저면 map"

'AI > Claude ai' 카테고리의 다른 글

Brave Search MCP는 Brave Search API를 Model Context Protocol(MCP) 스펙으로 감싼 stdio 서버다. Claude Code 같은 호환 에이전트가 별도의 SDK 호출 없이 웹 검색과 지역 검색을 네이티브 도구처럼 호출하도록 만든다. (0)	2026.05.11
Playwright MCP(Model Context Protocol) (0)	2025.07.03

whylite

whylite

태그

최근글

댓글

공지사항

아카이브

검색이 아니라
에이전트를 위한 리서치.

정의WHAT TAVILY IS

일반 검색 vs Tavily

일반 검색 API (Brave, Google CSE)

Tavily Search API

구조

핵심 가치

사용 방법FOUR TOOLS

도구 개요

tavily-search · 상세

tavily-extract · 상세

tavily-crawl · 상세

tavily-map · 상세

자연어 호출 예시

설치 내역WHAT WAS DEPLOYED

실행된 설치 명령

등록된 설정 (요약)

관련 파일

상태 확인 명령

주의사항OPERATIONAL CAUTIONS

크레딧 소비 메커니즘

플랜

알아두면 좋을 함정

Brave 와 함께 쓰는 패턴

롤백·재설치 시나리오

체크리스트

'AI > Claude ai' 카테고리의 다른 글

관련글

티스토리툴바

whylite

태그

최근글

댓글

공지사항

아카이브

검색이 아니라에이전트를 위한 리서치.

정의WHAT TAVILY IS

일반 검색 vs Tavily

일반 검색 API (Brave, Google CSE)

Tavily Search API

구조

핵심 가치

사용 방법FOUR TOOLS

도구 개요

tavily-search · 상세

tavily-extract · 상세

tavily-crawl · 상세

tavily-map · 상세

자연어 호출 예시

설치 내역WHAT WAS DEPLOYED

실행된 설치 명령

등록된 설정 (요약)

관련 파일

상태 확인 명령

주의사항OPERATIONAL CAUTIONS

크레딧 소비 메커니즘

플랜

알아두면 좋을 함정

Brave 와 함께 쓰는 패턴

롤백·재설치 시나리오

체크리스트

'AI > Claude ai' 카테고리의 다른 글

관련글

티스토리툴바

검색이 아니라
에이전트를 위한 리서치.