Tavily MCP Server: Complete Setup Guide for AI Agents

What Is the Tavily MCP Server?

The Tavily MCP Server is an official Model Context Protocol server maintained by Tavily that exposes Tavily's search and content extraction capabilities as MCP tools. This lets AI assistants and agents — such as Claude — call Tavily's web search API directly as structured tool calls, without any custom integration code.

In practical terms: you configure the Tavily MCP Server once, and Claude (or any MCP-compatible client) can search the web, retrieve current information, and extract page content on demand, in the middle of a conversation or agentic workflow.

The server is maintained in the official Tavily GitHub organization and published as the @tavily/mcp npm package. It is not a community fork — it is Tavily's own first-party MCP integration.

How It Connects AI Agents to the Web

Most LLMs have a training data cutoff. They can reason, code, and analyze — but they cannot retrieve information that didn't exist when they were trained, and they cannot browse the web.

Tavily is a search API built specifically for AI agents. Unlike a general-purpose search API, Tavily:

• Returns clean, structured results optimized for LLM consumption
• Provides full-text content extraction, not just snippets
• Supports deep research modes with higher-quality result aggregation
• Filters and scores results for AI relevance

The Tavily MCP Server bridges Tavily's capabilities into the MCP protocol, which means:

• Any MCP-compatible AI client (Claude Desktop, Cursor, Claude Code, etc.) can use Tavily search as a native tool
• The AI model decides when to invoke the tool based on the user's request
• Results flow directly back into the model's context
• No custom middleware, function-calling wrappers, or API client code required

When to Use Tavily MCP vs. Calling the Tavily API Directly

This is the first architectural decision you need to make. They solve different problems.

Tavily MCP Server vs Tavily API

Use the Tavily MCP Server when:

• You are building an AI agent that needs web search as a tool
• You want Claude or another LLM to autonomously decide when to search
• You are using Claude Desktop, Cursor, or another MCP-compatible client
• You want zero integration code — just configuration

Use the Tavily REST API directly when:

• Your application backend needs to call Tavily programmatically
• You need full control over request parameters, retries, and response handling
• You are building a RAG pipeline that preprocesses and indexes search results
• You need batch search across many queries in parallel
• You need the full JSON response with all metadata

Use both when:

• Your system has an AI agent front-end (MCP Server for tool calls) AND a backend pipeline that also processes search results (direct API for that part)
• You want an AI assistant with search capability while independently running scheduled search jobs

Architecture and Data Flow

Understanding the data flow helps you debug problems and make better deployment decisions.

┌─────────────────────────────────────────────────────────────────┐
│                         MCP Client                              │
│            (Claude Desktop / Cursor / Claude Code)              │
│                                                                 │
│   User message ──► LLM decides to call tavily-search tool       │
│                         │                                       │
│         MCP Tool Call (JSON-RPC over stdio)                     │
└─────────────────────────┼───────────────────────────────────────┘
                          │ stdin/stdout
┌─────────────────────────▼───────────────────────────────────────┐
│                   Tavily MCP Server                             │
│                  (Node.js subprocess)                           │
│                                                                 │
│  Receives tool call ──► Validates parameters                    │
│  Reads TAVILY_API_KEY from environment                          │
│  Constructs Tavily API request                                  │
│         │                                                       │
└─────────┼───────────────────────────────────────────────────────┘
          │ HTTPS
┌─────────▼───────────────────────────────────────────────────────┐
│                    Tavily API                                   │
│                 (api.tavily.com)                                │
│                                                                 │
│  Performs web search or content extraction                      │
│  Returns structured JSON results                                │
└─────────┬───────────────────────────────────────────────────────┘
          │ JSON response
┌─────────▼───────────────────────────────────────────────────────┐
│                   Tavily MCP Server                             │
│                                                                 │
│  Formats results as MCP tool response                           │
│  Returns via stdout to MCP client                               │
└─────────┬───────────────────────────────────────────────────────┘
          │ MCP tool result
┌─────────▼───────────────────────────────────────────────────────┐
│                         MCP Client                              │
│                                                                 │
│  Injects results into LLM context                               │
│  LLM synthesizes final response to user                         │
└─────────────────────────────────────────────────────────────────┘

Key architecture notes:

• The MCP Server runs as a local subprocess managed by the MCP client
• Communication is stdio (stdin/stdout), not HTTP
• The Tavily API key never touches the AI client — it lives in the server process environment
• Each tool call is synchronous from the client's perspective: it waits for the search result before continuing
• The subprocess is started when the MCP client starts and kept alive for the session

Prerequisites

Before installing the Tavily MCP Server, make sure you have:

Node.js 18 or later

node --version
# Should output v18.x.x or higher

npm and npx (included with Node.js)

npx --version

A Tavily API key

• Create a free account at app.tavily.com
• Navigate to your dashboard to find your API key
• It will look like tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

An MCP-compatible client, at least one of:

• Claude Desktop (macOS or Windows)
• Cursor IDE
• Claude Code (Anthropic's CLI)
• Any other MCP-compatible client

Getting Your Tavily API Key

1. Go to app.tavily.com and sign up or log in
2. From the dashboard, copy your API key from the API Keys section
3. Keep this key secure — treat it like a password

Free tier limits as of early 2025:

• 1,000 API credits per month
• Each basic search consumes 1 credit
• Each advanced search consumes more credits
• Content extraction has its own credit cost

For development and testing, the free tier is sufficient. For production agent workflows with frequent searches, check Tavily's current pricing at tavily.com/pricing.

Installation

The Tavily MCP Server is distributed as the @tavily/mcp npm package. You do not need to install it globally — MCP clients use npx to run it on demand.

Option 1: Run via npx (recommended for most setups)

No installation needed. Your MCP client config will use:

npx -y @tavily/mcp

This fetches and runs the latest version automatically.

Option 2: Install globally

npm install -g @tavily/mcp

Then reference tavily-mcp as the command in your config. This is faster at startup since it skips the npx resolution step.

Option 3: Install locally in a project

npm install @tavily/mcp

Useful if you want pinned versions in a project that includes MCP tooling.

Verify the package exists:

npx @tavily/mcp --version

Configuring Claude Desktop

Claude Desktop reads MCP server configurations from a JSON file. The location depends on your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist, create it.

Basic Configuration

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@tavily/mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-your-api-key-here"
      }
    }
  }
}

Replace tvly-your-api-key-here with your actual Tavily API key.

If You Installed Globally

{
  "mcpServers": {
    "tavily": {
      "command": "tavily-mcp",
      "args": [],
      "env": {
        "TAVILY_API_KEY": "tvly-your-api-key-here"
      }
    }
  }
}

After saving the config file, restart Claude Desktop completely (quit from the menu bar, not just close the window). Claude Desktop will spawn the Tavily MCP Server subprocess on the next launch.

You should see a hammer icon (🔨) in the Claude chat interface indicating MCP tools are available. Hover over it to confirm tavily-search and other tools are listed.

Configuring Cursor IDE

Cursor supports MCP servers through its settings panel.

Via Cursor Settings UI:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Features > MCP Servers
3. Click Add Server
4. Enter the configuration:

{
  "tavily": {
    "command": "npx",
    "args": ["-y", "@tavily/mcp"],
    "env": {
      "TAVILY_API_KEY": "tvly-your-api-key-here"
    }
  }
}

Via .cursor/mcp.json in your project:

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@tavily/mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-your-api-key-here"
      }
    }
  }
}

This project-level config is useful for team projects where everyone needs Tavily search in their AI coding sessions.

Configuring Claude Code

Claude Code (Anthropic's CLI tool for agentic coding) supports MCP servers via its configuration file.

Add the Tavily server to your Claude Code MCP configuration:

claude mcp add tavily --command npx -- -y @tavily/mcp

Then set the environment variable:

export TAVILY_API_KEY="tvly-your-api-key-here"

Or reference it in the Claude Code config file to persist the setting. Consult the Claude Code documentation for the exact config file location on your system.

Available MCP Tools

The Tavily MCP Server exposes two tools based on the official @tavily/mcp package:

1. tavily-search

Performs a web search using the Tavily Search API and returns relevant results.

Input parameters:

What it returns:

• Query and search metadata
• List of results with: title, url, content (snippet), score (relevance), published_date
• Optional: direct answer, raw content, images

2. tavily-extract

Extracts full content from one or more specific URLs.

Input parameters:

What it returns:

• Full page content for each URL
• Extracted text, cleaned for LLM consumption
• Success/failure status per URL

The difference in practice:

• Use tavily-search when you need to find relevant pages for a topic
• Use tavily-extract when you already know which URL(s) you need and want the full content

A common pattern: search first, get URLs, then extract specific pages for deeper analysis.

Environment Variable Configuration

The only required environment variable is:

TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Security Best Practice

Never hardcode your API key directly in config files that are committed to version control. Instead:

macOS/Linux — use your shell profile:

export TAVILY_API_KEY="tvly-your-key"

Then reference the system environment in your Claude Desktop config:

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@tavily/mcp"],
      "env": {
        "TAVILY_API_KEY": "${TAVILY_API_KEY}"
      }
    }
  }
}

Note: Claude Desktop's env variable interpolation support varies by version. Check current behavior — if interpolation doesn't work, you may need to write the key directly in the config file and exclude it from version control via .gitignore.

For team environments: Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password CLI) to inject the API key at runtime rather than storing it in any config file.

Real-World Tavily MCP Workflows

This is where the Tavily MCP Server proves its value. Here are production-realistic workflows you can implement today.

1. Autonomous Web Research Agent

The classic use case. The agent receives a research question, searches for relevant information, follows up with extracted content, and synthesizes a comprehensive answer.

Claude conversation example:

User: Research the current state of WebAssembly adoption in production 
      backend systems. I need a summary with specific examples of 
      companies using it and their use cases.

Claude: [calls tavily-search with query "WebAssembly production backend 
        adoption 2024 2025 companies"]
        [calls tavily-search with query "Wasm backend use cases enterprise"]
        [calls tavily-extract on 2-3 most relevant URLs]
        [synthesizes results into structured report]

The AI model autonomously decides how many searches to perform, which results to extract, and how to structure the final answer.

2. Documentation Research

Useful when working in Cursor — the AI can search for documentation on libraries, APIs, or frameworks that postdate its training data.

User: How do I configure custom headers in the new Fetch API streaming 
      response handling in Node.js 22?

Cursor AI: [calls tavily-search with query "Node.js 22 Fetch API 
           streaming response custom headers"]
           [extracts content from the Node.js 22 release notes page]
           [provides accurate, current documentation-based answer]

3. Competitor and Market Monitoring

An agent-based workflow where Claude periodically searches for competitor announcements:

User: What have Vercel, Netlify, and Cloudflare announced in the last week?

Claude: [calls tavily-search with topic "news", days: 7, 
        query "Vercel product announcements"]
        [calls tavily-search with topic "news", days: 7,
        query "Netlify product announcements"]
        [calls tavily-search with topic "news", days: 7,
        query "Cloudflare Workers announcements"]
        [synthesizes into a competitive intelligence brief]

The topic: "news" and days parameters are what make this work — without them, you might get results from months ago.

4. Technical Research for Code Generation

Before writing code that integrates with an external service, have Claude research the current API:

User: Write a Python function to call the Stripe Payment Intents API 
      to create a payment with automatic payment methods enabled.

Claude: [calls tavily-search "Stripe Payment Intents API Python 
        automatic payment methods 2024"]
        [calls tavily-extract on the Stripe official docs URL]
        [writes accurate, current Python code based on retrieved docs]

This dramatically reduces hallucinated API calls and outdated code patterns.

5. RAG Pipeline Enhancement

In a RAG architecture, Tavily MCP can supplement vector database retrieval with live web search for time-sensitive queries:

System: You are a technical support agent. You have access to our 
        knowledge base AND the ability to search the web for recent 
        information when needed.

User: Is there a known issue with Prisma and PostgreSQL connection 
      pooling in version 5.9?

Claude: [searches internal knowledge base — no results]
        [calls tavily-search "Prisma 5.9 PostgreSQL connection pooling 
        issue bug"]
        [finds relevant GitHub issue]
        [calls tavily-extract on the GitHub issue URL]
        [provides accurate current support answer]

6. Multi-Step Deep Research

For complex research tasks, Claude chains multiple searches and extractions:

User: Give me a thorough analysis of the energy consumption of 
      different proof-of-work vs proof-of-stake blockchains, 
      with current data.

Claude: [tavily-search, search_depth: "advanced", 
        "proof of work energy consumption current data 2025"]
        [tavily-search, search_depth: "advanced",
        "proof of stake energy consumption comparison 2025"]
        [tavily-extract on 3-4 authoritative source URLs]
        [cross-references results, identifies contradictions]
        [synthesizes structured comparative analysis]

With search_depth: "advanced", Tavily performs deeper crawling and returns higher-quality, more comprehensive results — worth the extra credits for research-heavy workflows.

7. Domain-Restricted Research

For security-conscious or compliance-restricted environments, use include_domains to limit search scope:

{
  "query": "GDPR data retention requirements for SaaS",
  "include_domains": ["gdpr.eu", "edpb.europa.eu", "ico.org.uk"],
  "search_depth": "advanced"
}

This ensures Claude only searches authoritative regulatory sources.

Common Errors and How to Fix Them

Error: TAVILY_API_KEY not set or invalid

Symptom: Tool call fails with an authentication error, or the MCP server fails to start.

Cause: The API key is missing from the env block, misspelled, or has extra whitespace.

Fix:

1. Verify your key at app.tavily.com
2. Check your Claude Desktop config — the key must be in the env block:

"env": {
  "TAVILY_API_KEY": "tvly-your-actual-key"
}

1. Make sure there are no quotes, spaces, or newlines accidentally included in the key value.

Error: npx not found or fails to resolve @tavily/mcp

Symptom: Claude Desktop shows the MCP server as failed, logs show command not found: npx.

Cause: Node.js is installed but not on the PATH that GUI applications see, or Node.js is not installed at all.

Fix:

# Verify Node.js is installed
node --version
which node
which npx

If the PATH is wrong, use the full absolute path in your config:

{
  "command": "/usr/local/bin/npx",
  "args": ["-y", "@tavily/mcp"]
}

On macOS with nvm or fnm, GUI applications often don't inherit shell PATH. Use the absolute path returned by which npx.

Error: Tool call returns empty results

Symptom: tavily-search runs but returns no results.

Cause: Query too specific, domain filters too restrictive, or time range too narrow.

Fix:

• Broaden the query
• Remove include_domains or exclude_domains restrictions
• Try search_depth: "advanced"
• If using topic: "news" with days, try increasing the days value

Error: Rate limit exceeded

Symptom: Tool call fails with a 429 error or a rate limit message.

Cause: You've exceeded your Tavily API plan's request limit, or you're hitting the per-minute rate limit.

Fix:

• Check your current usage at app.tavily.com
• If on the free tier and running heavy workflows, upgrade to a paid plan
• For agent loops, ensure your prompt doesn't cause Claude to make excessive search calls
• Add system-level instructions limiting search calls per query: "Use at most 3 search calls per research task"

Error: tavily-extract fails on specific URLs

Symptom: Extract returns empty content or error for certain URLs.

Cause: The target website blocks automated access, requires JavaScript rendering, or is behind authentication.

Fix:

• Tavily extract works best on publicly accessible, crawlable pages
• For JavaScript-heavy SPAs, results may be limited
• If extraction fails on a domain, fall back to search and use the snippet content instead

Error: MCP server not appearing in Claude Desktop

Symptom: No hammer icon, no tools listed.

Cause: Config file has invalid JSON syntax, wrong file location, or server failed to start silently.

Fix:

1. Validate your JSON: paste the config into a JSON linter
2. Check the correct file path for your OS
3. Check Claude Desktop logs:
   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\
4. Restart Claude Desktop completely after any config change

Troubleshooting Guide

Check if the MCP Server is Running

On macOS, after starting Claude Desktop:

ps aux | grep tavily

You should see a Node.js process running @tavily/mcp. If you don't, the server failed to start.

Test the Tool Directly

You can test the Tavily MCP Server from the command line before connecting a client:

TAVILY_API_KEY="tvly-your-key" npx @tavily/mcp

If it starts without errors, the package and API key are working correctly. The process will wait for input since it's expecting MCP protocol messages over stdio.

Validate the API Key

curl -X POST https://api.tavily.com/search \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tvly-your-key",
    "query": "test",
    "max_results": 1
  }'

If you get a valid JSON response, your API key works. If you get an authentication error, generate a new key from your Tavily dashboard.

Check MCP Tool Availability in Claude

In Claude Desktop, try asking:

What MCP tools do you have available?

Claude should list tavily-search and tavily-extract if the server is connected.

Performance Optimization

Search Depth Strategy

Use search_depth: "basic" for:

• High-frequency queries where speed matters
• Simple factual lookups
• News monitoring where recency matters more than depth
• Queries where 5 good results are sufficient

Use search_depth: "advanced" for:

• Research tasks where quality matters
• Complex technical topics
• When you need comprehensive coverage
• When you'll extract content from results anyway

Result Count Optimization

Default max_results is 5. Consider:

• For simple questions, 3 results is often enough
• For research, 8-10 results gives better coverage
• Don't request 20 results by default — it inflates context usage without proportional value

Avoiding Unnecessary Extractions

tavily-extract is powerful but has a cost. Instruct Claude in your system prompt:

Use tavily-search first. Only use tavily-extract if the search snippets 
don't provide enough detail to answer the question. Never extract more 
than 3 URLs per query.

This prevents runaway extraction loops in complex research tasks.

Context Window Consideration

Full page extraction via tavily-extract can return thousands of tokens. For long research sessions, this can fill Claude's context window quickly. Strategies:

• Extract only the most relevant URL(s), not all search results
• Use tavily-search with include_answer: true for summarized results when deep extraction isn't needed

Production Deployment Considerations

The Tavily MCP Server is designed as a development tool for AI assistant workflows, but if you're deploying it in a more formal production context (e.g., a backend AI agent system), here's what to consider.

Secret Management

Never store TAVILY_API_KEY in:

• Version-controlled config files
• Docker images
• CI/CD pipeline logs

Instead:

• Use environment variables injected at runtime
• Use cloud secret managers (AWS SSM, GCP Secret Manager, Azure Key Vault)
• Rotate API keys periodically from your Tavily dashboard

Rate Limit Handling

Tavily enforces rate limits based on your plan. For agent systems that may make many concurrent or rapid searches:

1. Monitor your credit usage in the Tavily dashboard
2. Implement request throttling in your orchestration layer
3. Use search_depth: "basic" where possible to conserve credits
4. Cache search results for identical queries within a session

Subprocess Reliability

Since the MCP Server runs as a subprocess, the parent process (Claude Desktop or your agent host) is responsible for its lifecycle. If the subprocess crashes:

• Claude Desktop will show the server as disconnected
• Restart Claude Desktop to re-spawn the subprocess
• For programmatic agent systems, implement subprocess health monitoring and restart logic

Validating Remote MCP Deployments

If you're exposing an MCP server at a network endpoint (not the default stdio configuration), you should validate it works correctly before connecting production agents. MCPForge's Verify tool lets you check that your MCP server responds correctly to protocol handshakes and tool discovery, which is useful for catching misconfiguration before it affects your agents. For discovering other validated MCP servers including alternatives to Tavily, the MCPForge verified directory is a good reference.

Monitoring Search Quality

In production agent systems, log:

• Which queries are being made (for debugging agent reasoning)
• Search result counts and scores
• Which URLs are being extracted
• Any API errors or empty results

This helps you identify when an agent is making low-quality search decisions.

Security Considerations

API Key Exposure

The Tavily API key is the primary security concern. It sits in the MCP client config file in plaintext by default. Mitigations:

• Use OS-level file permissions to restrict config file access
• Consider using a secrets manager to inject the key at runtime
• Rotate keys regularly
• Use separate API keys for development, staging, and production

Search Query Privacy

Every tool call sends the search query to Tavily's API. Be aware that:

• Search queries may be logged by Tavily per their privacy policy
• Sensitive internal business questions should not be sent through Tavily search
• For confidential research, consider whether the query itself reveals sensitive information

Domain Filtering for Trust

In environments where result quality and trustworthiness matter, use include_domains to restrict searches to verified sources:

{
  "include_domains": ["arxiv.org", "pubmed.ncbi.nlm.nih.gov", "nature.com"]
}

This prevents the AI from acting on results from low-quality or adversarial websites.

Agent Loop Safety

In autonomous agent workflows, Claude could theoretically make many search calls in a single session. Guard against this in your system prompt and consider setting max_results conservatively to limit token consumption per search.

Limitations

Being clear about limitations prevents debugging the wrong thing.

Best Practices Summary

API Key Security

• Store API key in env variables, not committed config files
• Use separate keys per environment
• Rotate keys periodically

Search Quality

• Use search_depth: "advanced" for research tasks
• Use topic: "news" with days for current-events queries
• Use include_domains for trust-sensitive research
• Tune max_results to match the actual need (not always 5 or 20)

Agent Workflow Design

• Provide Claude with clear instructions on when to search vs. when to use existing knowledge
• Limit search calls per task in your system prompt
• Use tavily-extract selectively, not on every search result
• Chain search + extract for deep research: find pages first, then extract the best ones

Performance

• Prefer search_depth: "basic" for latency-sensitive workflows
• Don't extract content you won't actually use in the response
• Cache results at the application level if you're calling MCP tools programmatically

Monitoring

• Log all tool calls and results in production agent systems
• Monitor Tavily API credit consumption against your plan
• Set up alerts before you hit your credit limit

For deeper guidance on running MCP servers reliably in production environments, including health checks, subprocess monitoring, and deployment patterns, see MCPForge's guide to running MCP in production.

Recent Ecosystem Updates

The @tavily/mcp package has been actively updated alongside Tavily's expanding API capabilities. Key developments to be aware of:

• The package is published under the @tavily npm organization, confirming first-party maintenance
• Tavily has added tavily-extract as a first-class tool alongside tavily-search, reflecting demand for full-page content extraction in agent workflows
• The MCP Server tracks the Model Context Protocol specification updates as Anthropic publishes them
• Tavily's underlying search quality improvements (better answer synthesis, improved news search) automatically benefit MCP Server users without requiring server updates

Always check the official GitHub repository for the latest release notes before deploying to production.

Quick Reference

Minimum Working Configuration (Claude Desktop)

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "@tavily/mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-your-key-here"
      }
    }
  }
}

Tool Quick Reference

Diagnostic Checklist

• Node.js 18+ installed and on PATH
• TAVILY_API_KEY set correctly in config env block
• API key verified at app.tavily.com
• Config file is valid JSON
• Config file is at correct OS path
• Claude Desktop fully restarted after config change
• MCP tools visible via hammer icon in Claude

Official Sources

• Official Tavily MCP Server repository: github.com/tavily-ai/tavily-mcp
• npm package: npmjs.com/package/@tavily/mcp
• Tavily API documentation: docs.tavily.com
• Tavily dashboard: app.tavily.com
• Model Context Protocol specification: modelcontextprotocol.io