# Tavily Search MCP

A cost-aware stdio MCP server for the official Tavily Search API.

## Tool

`tavily_search` supports:

- Basic, Fast, and Ultra Fast Search at 1 API credit.
- Advanced Search at 2 API credits, only when explicitly selected.
- General, news, and finance topics.
- Domain and date filters.
- Up to 20 ranked results with source URLs and relevance scores.
- Reported credit usage, response time, and request ID.

The server always sends `auto_parameters: false`, `include_usage: true`, and excludes generated answers, raw pages, and images. This keeps cost and response size predictable while leaving synthesis to the MCP client.

## Configuration

Required at call time:

```text
TAVILY_API_KEY
```

On Windows, run `npm run setup` for the first-install configuration window. Enter multiple API keys separated by semicolons. It saves the API URL as a non-secret setting and stores the key array as a current-user DPAPI ciphertext under `%APPDATA%\tavily-search-mcp\api-key.dpapi`. Environment variables (`TAVILY_API_KEYS` or `TAVILY_API_KEY`) still take precedence for CI or temporary sessions.

Requests rotate across configured keys. Authentication, rate-limit, and quota responses (`401`, `429`, `432`, `433`) can switch to the next distinct key, with a hard maximum of three attempts per MCP call. Server failures and ambiguous errors are not retried.

Optional:

```text
TAVILY_API_URL=https://api.tavily.com/search
```

The server starts and lists tools without a key, then fails closed with a clear error if a search is attempted before `TAVILY_API_KEY` is configured. Secrets are never accepted as tool arguments or printed.

Each installation must use its own Tavily credentials. Do not share `.env` files, DPAPI ciphertext, setup screenshots, or API keys with other users.

## Development

```bash
npm install
npm run check
```

## Codex configuration

After building, register the compiled entry point and forward only the required environment variable:

```toml
[mcp_servers.tavily_search]
command = "node"
args = ["D:/path/to/tavily-search-mcp/dist/index.js"]
env_vars = ["TAVILY_API_KEYS", "TAVILY_API_KEY", "TAVILY_API_URL"]
startup_timeout_sec = 20
tool_timeout_sec = 60
```

No request is retried automatically. HTTP redirects are rejected so the API key cannot be forwarded to another origin.