Tavily MCP Setup: OAuth Search with Bounded Crawl Scope
Connect Tavily's hosted MCP server through OAuth, verify one narrow search with source URLs, and set limits before allowing crawling. The goal is a traceable research step, not an assistant that can browse indefinitely without showing what it read.
Connect Tavily's hosted MCP server through OAuth, verify one narrow search with source URLs, and set limits before allowing crawling. The goal is a traceable research step, not an assistant that can browse indefinitely without showing what it read.
Table of contents
- What should you connect first?
- How do you configure OAuth without a key in the URL?
- Which tool matches your research task?
- How do you verify a useful search result?
- How do you keep requests bounded?
- How do you troubleshoot connection failures?
What should you connect first?
Start with the official remote server and one small search. Tavily documents a hosted MCP endpoint, OAuth authentication, and a local package for clients that need local execution. The server exposes Search, Extract, Map, and Crawl capabilities. Source: official repository.
The Tavily listing is a starting point for identifying the implementation and its connection model. Check the publisher before copying configuration from a directory: a community wrapper can have different tool names, argument handling, or authentication requirements.
Decide what your assistant needs to accomplish. Finding official documentation for an unfamiliar API is a search task. Reading the content of a URL you already know is an extraction task. Collecting many pages from a site is a larger operation that deserves a separate scope decision.
Our recommendation is to make the smallest useful request first. You should be able to explain what evidence came back, which URLs support it, and why another request would help. A long answer with many links is not evidence that the integration retrieved the right material.
How do you configure OAuth without a key in the URL?
Add the clean remote endpoint, then complete authorization through the client's OAuth interface. For Claude Code, Tavily documents this command:
claude mcp add --transport http tavily https://mcp.tavily.com/mcp
Start Claude Code, open /mcp, select Tavily, and complete sign-in. The official setup instructions also describe API-key authentication, but a clean OAuth URL avoids manually embedding a key in a copied address.
Check the selected Tavily account during authorization. A personal account and a team account can lead to different usage attribution, even though both return valid search results. Record which account the workflow should use and inspect that account's usage controls before enabling repeated research.
For JSON-based clients, use the client's documented remote configuration or bridge method. The Cursor guide helps locate its settings. Check syntax with Config Validator before troubleshooting the network. A parser failure occurs before authentication and should not send you looking for a new key.
If you choose a local server, establish its runtime and credential requirements separately. Remote OAuth and local process configuration solve the same access problem through different mechanisms; combining fragments from both can produce a configuration that does neither correctly.
Which tool matches your research task?
Use Search to discover relevant URLs, Extract to read known URLs, Map to discover a site's structure, and Crawl to collect content across a bounded site area. Choose the operation from the task rather than asking the assistant to “use the web” and accepting whichever tool it selects.
| Need | Starting tool | Boundary to specify |
|---|---|---|
| Find relevant pages | Search | Query, domains, result limit |
| Read named pages | Extract | Explicit URLs |
| Discover paths on a site | Map | Site and traversal limits |
| Collect content across pages | Crawl | Domain, depth, page limit |
Tavily's Search reference documents controls such as search depth and maximum results. Its Extract reference instead starts from supplied URLs. That input difference matters: extraction should not be expected to discover missing sources for you.
A sensible sequence is Search → inspect URLs → Extract selected pages. This keeps source selection visible. Use Map or Crawl only when you actually need multiple pages from a defined site, such as an API documentation section. Do not broaden to a crawl simply because the first search result did not answer the question.
How do you verify a useful search result?
Request a small result set, require source URLs, and check at least one primary source yourself. A successful tool call proves that a response arrived; it does not prove the assistant's summary follows from the pages returned.
For a first test, ask: “Find three official pages explaining Tavily Search parameters. Return each title, URL, and the parameter it documents. Do not crawl a site or make additional requests without explaining the missing evidence.” Then compare the URLs and claims with the documentation.
The Search API reference describes returned result data. Keep that tool output distinct from the assistant's interpretation. If the result excerpt says little about a parameter, the assistant should retrieve the relevant page rather than turn a search snippet into a confident technical conclusion.
When using Extract, review both successful and failed URLs. The Extract reference describes a response that can include failures. One failed page does not mean every page failed, and an omitted page should not quietly disappear from a supposedly complete research summary.
Save a compact verification record with the query, selected URLs, and date. Leave out credentials and sensitive internal search terms when sharing the record externally.
How do you keep requests bounded?
Specify a result limit and stop condition before the first call, then inspect the actual arguments. For a small documentation question, our starting recommendation is three results and a basic search. That is a workflow choice, not a universal quality threshold or a guarantee of low account usage.
Make the next step explicit: “If these pages do not answer the question, explain the gap before expanding.” Avoid instructions like “research until complete,” which leave the assistant to decide both the scope and the number of calls.
For site exploration, Tavily's Map documentation describes controls for discovery, while the Crawl documentation covers collecting content across a site. Set the intended domain, traversal boundary, and result cap using the parameters supported by the current tool schema.
A tool limit and a billing limit are different protections. OAuth does not remove the service's account usage rules. Review the account dashboard and approved spending settings before leaving a workflow unattended. This setup guide makes no claim about what your particular account can use for free.
For confidential work, strip private customer names, secrets, and internal identifiers from search queries unless your organization's policy explicitly permits sending them to the service.
How do you troubleshoot connection failures?
Separate authentication, account selection, quota, runtime, and content retrieval errors. A missing executable is a local setup issue; an authorization failure is not fixed by increasing the result limit; an unreadable website is not proof that the MCP connection is broken.
Use this sequence:
- Confirm the client can load the server entry.
- Confirm the remote connection is authenticated under the intended account.
- Inspect the exact tool name and arguments that failed.
- Check the service response for authentication, quota, or retrieval errors.
- Repeat one bounded read only after correcting the relevant cause.
Tavily documents how OAuth can choose an account API key, including a named mcp_auth_default key. Source: OAuth setup. If usage appears under an unexpected account or key, verify that selection rather than assuming a search result proves correct attribution.
Use Config Doctor when the problem is the local configuration. Reauthenticate through the client for stale sessions, preserving unrelated server settings. Keep a sanitized error record and avoid posting a key-bearing URL in screenshots or issue reports. Once the narrow search works, add one capability at a time so a new failure has a clear cause.