Tavily MCP Server for Windsurf: Setup & Config

What you can do with Tavily in Windsurf

Use it for search plus page collection, with either local execution or authenticated hosted access.

• Extract page content as Markdown or plain text.
• Crawl websites or assemble research from multiple sources.

Before you start: Tavily in Windsurf

• Node.js 20 or newer for local execution
• A Tavily API key for the local server
• An MCP-compatible client

The command launches the local server. The hosted endpoint is an alternative with API-key or OAuth authentication. DEFAULT_PARAMETERS can set local search defaults.

Tavily Windsurf configuration

1. Choose Windsurf configuration scope

   For Tavily MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Tavily MCP Server to Windsurf

   Use the tavily-mcp entry below in mcpServers. Keep Tavily MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Tavily MCP Server in Windsurf

   Tavily MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "tavily-mcp@latest"
      ],
      "env": {
        "TAVILY_API_KEY": "<Tavily API key>"
      }
    }
  }
}

Tavily tools available to Windsurf

Tavily's stored tool list documents 5 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

tavily_search

After refreshing Tavily in Windsurf settings, check Cascade's tool list for tavily_search.

Find current web information and return source links with excerpts.

tavily_extract

After refreshing Tavily in Windsurf settings, check Cascade's tool list for tavily_extract.

Retrieve page content from URLs as Markdown or text.

tavily_crawl

After refreshing Tavily in Windsurf settings, check Cascade's tool list for tavily_crawl.

tavily_map

After refreshing Tavily in Windsurf settings, check Cascade's tool list for tavily_map.

tavily_research

After refreshing Tavily in Windsurf settings, check Cascade's tool list for tavily_research.

Combine multiple sources into a detailed research response; limited to 20 requests per minute.

Tavily: full stored tool descriptions

Troubleshooting Tavily in Windsurf

• Check npx tavily-mcp@latest (Node.js/npm) on the machine running Windsurf's MCP integration for Tavily MCP Server; refresh MCP and inspect Cascade's tools.
• Check TAVILY_API_KEY for Tavily MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Tavily MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Local execution requires Node.js 20 or newer and a Tavily API key.
• Known limitation: The research tool is limited to 20 requests per minute in the supplied data.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions