tavily-mcp: four web tools Tavily serves over MCP

Two ways in: Tavily's hosted endpoint or a local Node process

The README leads with a choice that does not require you to install anything. Tavily hosts the server itself, and you point a client at a fixed URL with your API key attached:

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

If your client supports headers, the same server accepts the key in an Authorization header instead, which keeps the credential out of URLs that end up in shell history and config files:

Authorization: Bearer <your-api-key>

The hosted route is the faster one to try, and it is also the one with a moving part you cannot inspect: Tavily runs the process. The local route is a small TypeScript server you start yourself. The repository is ten entries at the top level, with `src/` holding the tool implementations, `tests/` the test files, a `Dockerfile`, a `smithery.yaml` for directory listings, and `package.json` pinning the MCP SDK to 1.30.0 alongside axios, dotenv and yargs. Nothing about that layout suggests a heavy service. The package publishes only `build/`, and the binary entry is `build/index.js`.

Either way you need a Tavily API key before anything else, and the README points at tavily.com for it rather than describing a signup flow.

Registering the server in Claude Code with a key or with OAuth

Claude Code is the client the README documents most carefully, and it offers two authentication paths. The short one puts the key straight into the URL:

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

The longer one registers the server without a key and defers the credential to an OAuth flow, which you finish by running `claude`, typing `/mcp`, selecting the Tavily entry and completing the browser authorization. The register step is:

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

Both commands accept `--scope user`, which makes the server available across every project instead of just the one you are sitting in:

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

Cursor is handled through a `mcp.json` file rather than a one-line command. The README shows the shape it expects, and the same file works for any client that shells out to `mcp-remote`:

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

Once registered, the four tools appear in the client: search, extract, map and crawl.

Four tools, and what each one is actually for

The feature list at the top of the README is short enough to be useful rather than decorative. `tavily-search` handles real-time web search. `tavily-extract` pulls structured content out of a page rather than returning raw HTML. `tavily-map` builds a structured map of a website, which is the tool that lets an assistant discover a site's structure before deciding which pages to fetch. `tavily-crawl` walks a site systematically, following it outward from an entry point.

The distinction between map and crawl is the part worth internalising, because it changes how you delegate work. Mapping is a cheap reconnaissance step that returns a tree of URLs. Crawling is the expensive step that actually retrieves many of them. A workflow that maps first and then crawls only the branches that matter is a materially cheaper workflow than one that crawls from the start, and the README presents both tools as separate for exactly that reason.

Default parameters are settable per client through a `DEFAULT_PARAMETERS` header carrying a JSON object, which the README illustrates with search depth, result count and image inclusion:

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

Setting defaults at the transport layer rather than in every prompt is the more useful of the two designs here, since it applies to all four tools at once. The README does not enumerate every parameter the four tools accept, so the exact vocabulary of `search_depth` beyond `basic` is something the tool schemas will show you in your client rather than something the README settles.

How OAuth decides which Tavily key gets charged

This is the sharpest piece of behaviour logic in the repository, and it is easy to miss because it sits at the bottom of a long README. After an OAuth flow completes, the server picks which of your Tavily keys to bill by looking for a key named `mcp_auth_default`. The precedence is explicit, and worth reading as a debugging checklist: a personal-account key named `mcp_auth_default` wins over a team key with the same name, a team key of that name is used if no personal one exists, a personal key named `default` is the fallback, and if neither exists the first available key is used.

That ordering has a practical consequence. If you belong to a team that already defines `mcp_auth_default`, you can end up billing that team's key without intending to, unless you create your own personal key with the same name. The README states the rule but does not call out this trap.

Clearing stored OAuth credentials takes one command, which is the fastest way to re-authenticate when the wrong key is being selected:

rm -rf ~/.mcp-auth

The README also states that OAuth is optional throughout, and that API key authentication works at any time through either the query parameter or the Authorization header. So the OAuth path is a convenience for clients that prefer it, not a requirement.

Running locally with npx, or building the container image

The local path needs Node.js 20 or higher, Claude Desktop or Cursor, and a Tavily API key. Git is only needed for the git installation method. The README's local section is brief and its last line is the npx invocation, so there is not much to walk through:

npx -y tavily-mcp

The `Dockerfile` in the repository shows what a real deployment looks like. It is a two-stage Alpine build: a `node:22.12-alpine` builder that runs `npm install`, and a `node:22-alpine` release stage that copies only `build/`, `package.json` and `package-lock.json`, then installs production dependencies with `--ignore-scripts --omit-dev`. The key is supplied as an environment variable rather than baked in:

ENV TAVILY_API_KEY=your-api-key-here
ENTRYPOINT ["node", "build/index.js"]

Two details in that file are worth noting. The release stage sets `NODE_ENV=production`, so anything the server does at startup that expects dev dependencies will not find it. And the entrypoint runs `node build/index.js` directly, not a wrapper binary, which means the container depends on the build output already existing in the image, the way the two-stage copy arranges.

The npm scripts in `package.json` describe the developer loop: `npm run build` compiles with `tsc` and then chmods the output to 755, `npm run watch` runs `tsc --watch`, and `npm run inspector` launches the MCP Inspector against `build/index.js`, which is the fastest way to inspect the tool schemas by hand.

What the version number, the licence file and the release history do and do not tell you

`package.json` reports version 0.2.23, and the repository publishes no GitHub releases at all. So the only version signal available is the npm manifest, which means upgrade notes have to come from the registry or the changelog history in the repository rather than from a release page. For an adapter whose job is to wrap someone else's API, that is less costly than it would be for a project with real behaviour changes, but it does mean you have no per-version migration notes to read.

The licence is a small inconsistency worth flagging. GitHub reports MIT, `package.json` says MIT, and the repository root contains a file named `LICENCE` rather than `LICENSE`. Both facts are true at once: the declared licence is MIT and the file carrying the text uses British spelling. If licence compliance matters to your organisation, read `LICENCE` in the repository rather than trusting the field alone, and check whether any dependency in `package-lock.json` carries terms that reach your distribution model.

The last push to the repository was on 2026-09-16, so the code is moving. What the README does not cover is the request surface itself: how the four tools map to Tavily's underlying REST endpoints, how errors and rate limits surface to the model, and what the per-call cost of a crawl is. For the first question, `src/` is where the answers are. For the second, Tavily's own documentation, not this repository, is the only place the numbers exist.

Editorial conclusion

tavily-mcp is a thin adapter, and that is its main appeal and its main limit. It is good at getting search, extraction, mapping and crawling in front of an MCP client in one command, with no local daemon to babysit when you use the hosted endpoint. It is the wrong tool if you need to audit what the search layer does with your traffic, change the ranking, or run without a Tavily key, because none of that lives in this repository. Start with the hosted URL and the API key query parameter, confirm which key the `mcp_auth_default` rule selects on your account, then read the `src/` directory if you plan to fork it.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. tavily-ai/tavily-mcp on GitHub