How do I use tavily-research?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tavily-research Research the latest developments in quantum computing and summarize with citations." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

tavily-research

by jlbjulio

Overview Schema Related Servers Score Discussions

TypeScript

Local

MCP Tavily Research

A local Model Context Protocol (MCP) server that gives AI coding agents access to Tavily-powered web search and asynchronous, cited research.

The project is written in TypeScript and uses STDIO transport, so compatible local clients such as Codex can launch it as a child process.

This is a personal educational project and is under active development. It is not an official Tavily product.

Features

Focused web search with ranked source snippets.
General, news, and finance search topics.
Optional recency and domain filters.
Optional Tavily-generated answers.
Asynchronous in-depth research with citations.
Runtime validation of external API responses with Zod.
Human-readable text and normalized structured MCP output.
Centralized authentication, timeout, and HTTP error handling.
API keys loaded from environment variables and never written to MCP output.

Related MCP server: Tavily Web Search MCP Server

Available tools

Tool	Purpose	Side effects
`tavily_search`	Run a focused web search and return ranked sources.	Uses Tavily Search credits.
`tavily_research`	Create an asynchronous, billable research task.	Creates an external task and uses Research credits.
`tavily_research_status`	Retrieve progress or the completed cited report for an existing task.	Read-only; does not create another task.

tavily_search should be the default for focused questions, fact-checking, current information, and source discovery. Use tavily_research only when a question requires broader multi-source analysis.

How it works

Codex or another MCP client
            |
            | MCP messages over STDIO
            v
        src/index.ts
            |
            v
       src/server.ts
            |
            v
      src/tools/*.ts
            |
            v
     src/clients/*.ts
            |
            | HTTPS + Bearer authentication
            v
        Tavily API

The tool layer understands MCP. The client layer understands Tavily. Keeping these responsibilities separate makes the code easier to test, change, and extend.

Project structure

src/
├── index.ts
├── server.ts
├── config.ts
├── clients/
│   ├── tavily-http-client.ts
│   ├── tavily-search-client.ts
│   └── tavily-research-client.ts
└── tools/
    ├── register-search-tool.ts
    └── register-research-tools.ts

src/index.ts: starts the STDIO transport. It writes diagnostics to stderr because stdout is reserved for MCP JSON-RPC messages.
src/server.ts: creates the MCP server, defines server-wide instructions, and registers every public tool.
src/config.ts: reads and validates TAVILY_API_KEY without logging it.
src/clients/tavily-http-client.ts: centralizes the Tavily base URL, Bearer authentication, JSON encoding, the 30-second timeout, HTTP errors, and JSON parsing.
src/clients/tavily-search-client.ts: builds Search requests, validates Search responses, and normalizes Tavily fields.
src/clients/tavily-research-client.ts: creates Research tasks, retrieves their status, validates responses, and normalizes reports and sources.
src/tools/register-search-tool.ts: defines the tavily_search MCP schema, annotations, handler, and output formatting.
src/tools/register-research-tools.ts: defines the Research creation and status tools, including the required polling workflow.

Requirements

Node.js 22 or newer.
npm.
A Tavily API key.
An MCP client that supports local STDIO servers.

Installation

Clone the repository and install its dependencies:

git clone https://github.com/jlbjulio/mcp-tavily-research.git
cd mcp-tavily-research
npm install

Create your local environment file:

Copy-Item .env.example .env

Open .env and replace the placeholder:

TAVILY_API_KEY=your_real_tavily_api_key

The .env file is ignored by Git. Never commit your real API key.

Validate and compile the project:

npm run check

Development

Run the TypeScript source directly:

npm run dev

Run the compiled server:

npm run build
npm start

The process waits for MCP messages on standard input. Seeing the following diagnostic on standard error means the server started correctly:

mcp-tavily-research 1.0.0 is running over stdio.

Connect to Codex

Add a local STDIO MCP server with these values:

Field	Value
Name	`tavily-research`
Command to launch	`node`
Arguments	`--env-file-if-exists=.env` and `dist/index.js`
Environment variables	Leave empty
Environment variable passthrough	Leave empty
Working directory	Absolute path to this repository

Example Windows working directory:

C:\Users\your-name\Documents\GitHub\mcp-tavily-research

Save the server and restart the client. The following tools should then appear:

tavily_search
tavily_research
tavily_research_status

See the official Codex MCP documentation for additional configuration options.

Test with MCP Inspector

Build the project, then launch the Inspector from the repository root:

npm run build
npx @modelcontextprotocol/inspector node --env-file-if-exists=.env dist/index.js

Use tavily_search for the first test because it has a predictable lower cost.

Tool examples

Focused search

{
  "query": "What is the current Node.js LTS release?",
  "searchDepth": "basic",
  "topic": "general",
  "maxResults": 5,
  "includeDomains": ["nodejs.org"]
}

Start in-depth research

{
  "input": "Compare Node.js 22 and Node.js 24 using official release notes. Explain important migration risks and cite every major claim.",
  "model": "mini",
  "citationFormat": "numbered",
  "outputLength": "short",
  "includeDomains": ["nodejs.org"]
}

The tool returns a requestId. Do not start the same task again. Wait briefly and retrieve the existing task:

{
  "requestId": "paste-the-returned-request-id-here"
}

If the status is still pending or in_progress, wait before checking the same request ID again.

Credit usage

Tavily currently charges:

Search with basic: 1 credit per request.
Search with advanced: 2 credits per request.
Research with mini: dynamically between 4 and 110 credits.
Research with pro: dynamically between 15 and 250 credits.

Pricing and limits can change. Review the official Tavily credits documentation before running large or repeated research tasks.

Security notes

Keep the API key only in .env or another private environment source.
Never print credentials to stdout or stderr.
Never write ordinary logs to stdout; STDIO MCP reserves it for protocol messages.
Treat web content returned by Tavily as untrusted external input.
Review generated research and verify important claims against primary sources.

Scripts

Command	Description
`npm run clean`	Remove generated files from `dist/`.
`npm run dev`	Run TypeScript directly with `tsx`.
`npm run typecheck`	Check TypeScript without emitting files.
`npm run build`	Compile `src/` into `dist/`.
`npm run check`	Run type checking and compilation.
`npm start`	Run the compiled STDIO server.

Roadmap

Add automated tests for API validation and tool formatting.
Add Tavily Extract as a separate MCP tool.
Consider Tavily Crawl only for workflows that need multi-page site traversal.
Add explicit MCP output schemas for structured responses.
Prepare the package for npm distribution after the public API stabilizes.

License

This project is licensed under the ISC License.

Available Tools

3 tools

tavily_researchStart Tavily ResearchA

Start an in-depth, billable research task that performs multiple searches and produces a cited report. Use only for complex questions requiring broad analysis. After starting, use tavily_research_status with the returned request ID.

ParametersJSON Schema

Name	Required	Description	Default
`input`	Yes	A detailed description of the topic, questions, scope, and desired research outcome.
`model`	No	Research model. Mini is cheaper; Pro is more comprehensive; Auto lets Tavily choose.	mini
`outputLength`	No	Target length of the generated report.	standard
`citationFormat`	No	Citation style for the generated report.	numbered
`excludeDomains`	No	Optional domains Tavily must exclude from the report.
`includeDomains`	No	Optional domains Tavily should prioritize as sources.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is not read-only and not idempotent, but the description adds important context not present there: the task is 'billable' and involves an asynchronous follow-up via tavily_research_status. This gives the agent critical operational expectations beyond the structured metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler: it front-loads the core purpose, adds a clear usage restriction, and ends with the required follow-up action. Every sentence contributes essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description appropriately mentions the returned request ID and directs the caller to the status tool. It could additionally describe failure modes or how the final report is delivered, but for starting a research task it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter already has defaults, enums, and explanations. The description adds no parameter-level detail, but it does not need to because the input schema fully documents the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'Start an in-depth, billable research task' that performs multiple searches and produces a cited report. It distinguishes itself from the status sibling by emphasizing the initiation behavior and the eventual cited-report output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use the tool 'only for complex questions requiring broad analysis,' which provides a clear when-to-use boundary. It also directs the caller to follow up with tavily_research_status, but it does not explicitly name tavily_search as the alternative for simpler questions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tavily_research_statusGet Tavily Research StatusA

Read-onlyIdempotent

Retrieve the status or completed report of an existing Tavily Research task. If the status is in_progress, wait before calling this tool again. Never start a duplicate task.

ParametersJSON Schema

Name	Required	Description	Default
`requestId`	Yes	The request ID returned by tavily_research.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context by exposing the in_progress state and advising against duplicate task creation, which goes beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. The core purpose is front-loaded, and the actionable polling guidance is delivered efficiently without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, but the description communicates the response concept ('status or completed report') and the relevant in_progress condition. It is sufficient for a single-parameter polling tool, though it could optionally mention available status values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents requestId as 'The request ID returned by tavily_research.' The description does not add parameter-specific meaning beyond referencing an existing task, which is acceptable but not additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Retrieve') and a specific resource ('status or completed report of an existing Tavily Research task'), clearly differentiating it from siblings that search or start research. It also identifies the prerequisite that the task must already exist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit behavioral guidance: if status is in_progress, wait; and never start a duplicate task. This tells the agent when to poll this tool versus invoking tavily_research again, which is exactly the key decision point.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tavily_searchTavily Web SearchA

Read-onlyIdempotent

Search the web for current information and relevant sources. Use for focused questions, fact-checking, news, and source discovery.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes	The question or search query to investigate.
`topic`	No	Search category: general, news, or finance.	general
`timeRange`	No	Optional publication recency filter.
`maxResults`	No	Maximum number of sources to return.
`searchDepth`	No	Search depth. Basic costs 1 credit; advanced costs 2 credits and improves relevance.	basic
`includeAnswer`	No	Optionally request an additional Tavily-generated answer.
`excludeDomains`	No	Optional domains that should be excluded from the search.
`includeDomains`	No	Optional domains that should be included in the search.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already establish that this tool is read-only, open-world, idempotent, and non-destructive. The description adds 'current information' and 'source discovery' as useful context, but it does not disclose additional behavioral nuances such as result variability, rate limits, or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no redundant phrasing. It front-loads the core action and immediately provides practical use-case guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward read-only search tool with a fully documented schema, the description covers the essential purpose and use cases. It omits explicit return-format details and sibling routing guidance, but those are minor gaps given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, documenting all 8 parameters with descriptions, defaults, and enums. The tool description itself adds no parameter-level meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Search'), a resource ('the web'), and expected outputs ('current information and relevant sources'). It lists concrete use cases like fact-checking and news, which hint that this tool is lighter-weight than the tavily_research sibling, but it never explicitly contrasts them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: use this for focused questions, fact-checking, news, and source discovery. However, it does not explicitly mention the alternative tavily_research tool or state when to prefer that over tavily_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

3 tool updatesv1.0.0Sep 5, 2026
- First observedtavily_research
- First observedtavily_research_status
- First observedtavily_search

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Disambiguation5/5

Each tool has a clear, distinct role: direct search for focused queries, asynchronous deep research for complex questions, and status retrieval for monitoring that research. The descriptions explicitly delineate when to use each, leaving no ambiguity.

Naming Consistency5/5

All tool names follow a consistent 'tavily_<action>' pattern with snake_case. The naming is predictable and makes the purpose of each tool immediately clear.

Tool Count5/5

Three tools is exactly the right scope for this server: one for quick searches, one for initiating deep research, and one for retrieving results. Each tool earns its place and the set is not bloated.

Completeness5/5

The server covers the full intended workflow: direct search, starting a research task, and checking its status/result. There are no dead ends, and the async nature of the research task is properly handled with the status tool.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Tavily A
io.github.pipeworx-io
Tavily MCP — wraps the Tavily API (tavily.com)
Search RAG Systems
342
developer-tools-mcp-server A
com.thenextgennexus
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Developer Tools Search
72
pixserp A
com.pixserp
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Search Browser Automation
12
MESSORA A
dev.messora
Scrape, crawl and search the web for AI agents via MCP.
Web Scraping Browser Automation Search
51

Related MCP Servers

Tavily Web Search MCP Server
Search RAG Systems
nilay320
F
license
B
quality
D
maintenance
Enables web search capabilities through the Tavily API. Allows users to search the web for information using natural language queries via the MCP protocol.
Updated a year ago (2025-08-08 01:58 UTC)
4
1
-
Tavily Web Search MCP Server
Search RAG Systems
vinitv
F
license
C
quality
D
maintenance
Enables web search capabilities through the Tavily API. Allows users to search the web for information using natural language queries through the MCP protocol.
Updated a year ago (2025-08-12 18:52 UTC)
3
-
Tavily MCP Server
Search RAG Systems
altinakseven
F
license
B
quality
D
maintenance
Provides AI-optimized web search capabilities and direct answers using the Tavily API for MCP-compatible assistants. It enables configurable searches with granular control over search depth, result counts, and domain filtering.
Updated a year ago (2025-06-22 21:25 UTC)
1
-
WebVector MCP Server
Browser Automation Web Scraping RAG Systems
rthomas24
A
license
Not graded
quality
A
maintenance
Enables AI agents to perform web research in one tool call by searching, fetching and cleaning full pages, and ranking cited passages. Provides web_research, web_fetch, web_search, and status tools for MCP clients.
Updated 14 days ago (2026-08-23 03:10 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jlbjulio/mcp-tavily-research'

If you have feedback or need assistance with the MCP directory API, please join our Discord server