tavily MCP

The Tavily MCP server connects an agent to Tavily's web API. It offers search, extract, map and crawl tools, so the agent can look things up, read pages and explore a site. You can use Tavily's hosted endpoint or run it with npx. The code is MIT licensed, and the service has a free plan of 1,000 credits a month. We checked it on 31 October 2026.

Quick facts

What it does

The README lists four capabilities:

• Search. Real-time web search through the tavily-search tool.
• Extract. Data extraction from web pages through the tavily-extract tool.
• Map. A structured map of a website, so an agent can see what URLs exist.
• Crawl. A crawler that explores a site systematically.

That makes it close in scope to Firecrawl MCP, with a smaller surface. Where Firecrawl has 27 tools in its full profile, Tavily has four that map to Tavily's own API endpoints: search, extract, map and crawl. Tavily's site describes itself as a web access layer for AI agents and lists those endpoints plus a research agent.

A normal agent loop looks like this:

1. Search for a question to get ranked results.
2. Extract the pages worth reading, so the agent gets clean content, not HTML.
3. Map a docs site to find the right section.
4. Crawl a section when many pages matter.

Crawl is the one to be careful with, since it fans out across pages and draws on your credits..

Pricing

The server is free. The service uses credits. From Tavily's pricing page:

Some other facts from the page:

• Credits reset on the first day of each month, whatever your billing date.
• A credit is consumed by each request, and advanced or high-volume requests use more. The page sends you to the docs for the full table.
• If you run out, requests stop until the reset or until you upgrade.
• There is a startup program offering 100k free API credits, and a free offer for students.

Do the arithmetic before you commit. At the pay-as-you-go rate, Project's 4,000 credits for $30 works out to $0.0075 a credit, a touch cheaper than $0.008. So Project is worth it only if you will reliably use most of the 4,000. If your use is spiky, pay as you go avoids paying for credits you do not spend.

Planning your credits

Credits are the thing that turns a pleasant demo into a surprise bill, so it helps to plan. Start by deciding what one task is worth. A quick lookup may take one search and one extract. A research task may take five searches, eight extracts and a map. If you know your typical task, you can estimate how many tasks 1,000 free credits cover..

Three habits keep the number down.

• Search before extract. Read the result snippets, then extract only the two or three pages that matter.
• Map before crawl. A map lists URLs without fetching page text. Pick a section from the map, then crawl that section only.
• Cap the loop. Put a limit in your project instructions, such as "no more than ten searches per task", because an agent that is stuck will keep trying.

The free plan resets on the first of each month, so a heavy week early in the month leaves nothing for the rest of it. If that happens twice, move to pay as you go, which charges by use and has no monthly floor, then look at the Project plan once your steady use is clear.

Install it

Tavily gives you two routes, remote and local.

Remote

The README's remote server needs no local install. Pass your key in the URL:

https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Or send it in a header if your client allows:

Authorization: Bearer <your-api-key>

The remote server also reads a DEFAULT_PARAMETERS header holding a JSON object, so you can set defaults for every request:

{"include_images": true, "search_depth": "basic", "max_results": 10}

Remote with OAuth

You can add the server without a key and sign in instead:

https://mcp.tavily.com/mcp

The README says the server supports OAuth with metadata discovery, client registration and token exchange. It also explains key selection: after sign-in, a key named mcp_auth_default in your personal account is used first, then one on your team, then your default key, then the first available key. To clear stored OAuth credentials, the README says to remove ~/.mcp-auth.

Local

npx -y tavily-mcp@latest

You need a Tavily API key and Node.js 20 or higher. Set TAVILY_API_KEY in the environment. You can also set DEFAULT_PARAMETERS to change search defaults, for example:

export DEFAULT_PARAMETERS='{"include_images": true}'

An optional TAVILY_HUMAN_ID variable identifies the end user and is sent as an X-Human-Id header for per-user analytics. The README says Tavily hashes the value with SHA-256 before storing it, and advises opaque IDs over raw personal data.

Install it in each agent

The README documents Claude Code and Cursor, and the local entry for Claude Desktop. The rest is our adaptation. For how each agent names fields, see MCP clients.

Claude Code

From the README, with the key in the URL:

claude mcp add --transport http tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Or with OAuth:

claude mcp add --transport http tavily https://mcp.tavily.com/mcp

Then run claude, type /mcp, select Tavily and finish sign-in. Add --scope user to make it available across all projects.

Codex

Our adaptation. Codex can add a streamable HTTP server by URL, and for local use a TOML entry works:

[mcp_servers.tavily]
command = "npx"
args = ["-y", "tavily-mcp@latest"]

[mcp_servers.tavily.env]
TAVILY_API_KEY = "your-api-key"

Cursor

The README has an install button and a mcp.json entry that uses the mcp-remote helper:

{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
      "env": {}
    }
  }
}

For OAuth, drop the key from the URL: npx mcp-remote https://mcp.tavily.com/mcp.

Antigravity

Our adaptation. Add the local entry to ~/.gemini/config/mcp_config.json:

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

For the remote server, Antigravity's serverUrl field takes the URL.. Gemini CLI is now for Code Assist enterprise customers only.

OpenCode

Our adaptation, in opencode.json:

{
  "mcp": {
    "tavily": {
      "type": "local",
      "command": ["npx", "-y", "tavily-mcp@latest"],
      "environment": { "TAVILY_API_KEY": "your-api-key" }
    }
  }
}

OpenCode's remote type with a URL and headers fits the hosted endpoint.

Setting defaults

The DEFAULT_PARAMETERS setting is useful. The README shows a config with include_images, max_results and search_depth:

"env": {
  "TAVILY_API_KEY": "your-api-key-here",
  "DEFAULT_PARAMETERS": "{\"include_images\": true, \"max_results\": 15, \"search_depth\": \"advanced\"}"
}

Defaults save the agent from repeating options, and they also set a spending floor. An advanced search depth likely costs more than a basic one.. Choose basic as your default and let the agent ask for more when it needs it.

Example prompts and what to expect

We have not run these. They match what the tools are built for.

• "Search for the latest release notes for this framework and summarise the breaking changes." Search, then extract on the top result.
• "Map the docs site for this library and tell me which pages cover authentication." Map first, since it returns URLs without page text.
• "Crawl the migration guide section and make a checklist." Crawl with a clear scope.
• "Find three recent articles on this topic and compare their claims." Search, then extract each.

Give the agent a limit for every crawl and a maximum number of results. A plain instruction such as "no more than 10 results and one crawl per task" protects your credits.

Security notes

1. A key in a URL is a leak risk. The README's simplest remote form puts the key in the URL. URLs appear in config files, shell history and logs. Prefer a header or OAuth.
2. A key is a spending limit. Anyone who has it uses your credits. Revoke and replace it in the dashboard if it escapes.
3. Search queries leave your machine. Do not put private code, customer data or credentials in a query.
4. Extracted pages are untrusted input. A page can carry text meant to steer an agent. Keep write and shell tools behind confirmation when the agent reads the open web.
5. The npx package runs code on your machine. Pin a version in production instead of @latest, and review changes when you update.
6. OAuth credentials are cached locally. The README says they live under ~/.mcp-auth. Treat that folder as sensitive.
7. Opaque IDs only. If you set TAVILY_HUMAN_ID, use an internal ID, not an email.

Limits and known issues

• Four tools only. There are no browser actions or document parsing. For those, pair it with Playwright MCP or a scraping service.
• Credits end the session. When the monthly credits run out, requests stop until the reset.
• Latest tag in the command. The README's local command uses @latest, which can change under you.
• No release tags on GitHub. Track versions through npm.
• Open issues. The repo showed 64 open issues when we checked..
• Cursor config shape. The README's Cursor entry puts a full command string in command, which differs from the usual command and args split. If it fails, split it..

Alternatives

The MCP servers hub lists more.

Which agents it suits

• Claude Code has a documented one-line add and an OAuth path.
• Cursor has an install button.
• Codex, Antigravity and OpenCode use the local npx entry well.
• Research agents gain from search plus extract.
• Light users fit inside the free 1,000 credits.

Our take

We did not run Tavily for this page. This is from the README, the pricing page and repo data.

Tavily is a straightforward search server. Four tools, a hosted URL and a free plan are enough for most agent research. The DEFAULT_PARAMETERS setting is a thoughtful touch, because it lets you set a cheap default once.

The things to manage are keys and credits. The easiest remote setup puts a key in the URL, which is the wrong habit to start. Use the header or OAuth, set a default search depth of basic, and watch your credit count in the first week.

If you want a bigger toolbox with structured scraping, look at Firecrawl. If you want fewer tools and a simple search loop, Tavily and Exa are both fair places to start.

A short setup checklist

1. Sign up and note the 1,000 free monthly credits.
2. Add the remote server with OAuth, or the local entry with a key in the environment.
3. Set DEFAULT_PARAMETERS to a basic search depth and a small result count.
4. Ask for a search, then an extract on one result.
5. Check your credit use in the dashboard.
6. Limit crawls by scope and number of pages.
7. Keep private material out of queries.

Frequently asked questions

What does the Tavily MCP server do?

It gives an agent search, extract, map and crawl tools backed by Tavily's API.

Do I need an API key?

Yes, either in the URL, a header, the TAVILY_API_KEY variable, or through OAuth sign-in.

Is Tavily free?

The server is MIT licensed, and the free Researcher plan includes 1,000 API credits a month.

Remote or local, which should I use?

Remote needs no install. Local runs with npx tavily-mcp and needs Node.js 20 or higher.

Can I set default search options?

Yes, with DEFAULT_PARAMETERS, as an environment variable locally or a header remotely.