Tavily MCP Server

Common errors

• Tavily API Key is missing or invalid

  cause The Tavily API key was not provided or is incorrect, preventing access to Tavily services.
  fix Ensure `TAVILY_API_KEY` is set in your environment variables, passed correctly in the URL (`?tavilyApiKey=...`), or included in the `Authorization: Bearer <key>` header when interacting with the server.

• connect ECONNREFUSED 127.0.0.1:8080

  cause The local Tavily MCP server is not running or is listening on a different port than expected.
  fix Verify that `McpServer.start()` was called successfully and the server is actively listening on the configured port (default 8080) before making requests. Check logs for startup errors.

• Failed to parse JSON in DEFAULT_PARAMETERS header

  cause The `DEFAULT_PARAMETERS` HTTP header contained a value that could not be parsed as valid JSON.
  fix Ensure the `DEFAULT_PARAMETERS` header value is a properly stringified JSON object, for example, `{"search_depth":"basic"}` should be sent as the string `"{\"search_depth\":\"basic\"}"`.

Warnings

• gotcha When connecting to the remote MCP server, ensure your Tavily API key is either passed directly in the URL (`?tavilyApiKey=...`) or via an `Authorization: Bearer <your-api-key>` header. Mixing methods or providing an invalid key will lead to authentication failures.
  Fix: Always use a single, correct method for API key authentication. For programmatic access, using an Authorization header or environment variable for the API key is recommended.
• gotcha The `DEFAULT_PARAMETERS` header, used for setting global defaults on remote MCP requests, must contain a valid JSON string. Malformed JSON will lead to parsing errors on the server side and ignored parameters.
  Fix: Ensure the `DEFAULT_PARAMETERS` header value is a `stringified` JSON object, e.g., `JSON.stringify({"include_images":true})`.
• breaking Older versions might have used different CLI commands or authentication flows for integration with client tools like Claude Code or Cursor. Always refer to the latest documentation for correct integration steps.
  Fix: Upgrade to the latest `tavily-mcp` version and consult the current README or documentation for updated client integration instructions.
• gotcha When running the server locally, ensure that the specified port is not already in use by another application. Port conflicts will prevent the server from starting.
  Fix: Check for available ports or explicitly configure a different port for the `McpServer` instance if the default `DEFAULT_MCP_SERVER_PORT` (8080) is occupied.

Install

• npm install tavily-mcp npm
• yarn add tavily-mcp yarn
• pnpm add tavily-mcp pnpm

Imports

• McpServer
  wrong:

  const McpServer = require('tavily-mcp').McpServer;

  correct:

  import { McpServer } from 'tavily-mcp';

  Used for programmatic instantiation and management of the local MCP server in TypeScript/ESM projects.
• TavilySearchTool
  wrong:

  import TavilySearchTool from 'tavily-mcp/search';

  correct:

  import { TavilySearchTool } from 'tavily-mcp';

  Imports the specific web search tool, often used when integrating individual tools into a custom MCP setup.
• TavilyExtractTool
  wrong:

  import { extract } from 'tavily-mcp';

  correct:

  import { TavilyExtractTool } from 'tavily-mcp';

  Imports the data extraction tool for programmatic use, enabling intelligent parsing of web content.

Quickstart

Demonstrates how to programmatically start the Tavily MCP server locally and then make a basic search request to it, showcasing the server's core functionality.

import { McpServer, DEFAULT_MCP_SERVER_PORT } from 'tavily-mcp';
import axios from 'axios';

const TAVILY_API_KEY = process.env.TAVILY_API_KEY ?? '';

async function startAndTestServer() {
  if (!TAVILY_API_KEY) {
    console.error('TAVILY_API_KEY is not set. Please set it as an environment variable.');
    process.exit(1);
  }

  const server = new McpServer({
    port: DEFAULT_MCP_SERVER_PORT,
    tavilyApiKey: TAVILY_API_KEY,
  });

  await server.start();
  console.log(`Tavily MCP Server started on port ${DEFAULT_MCP_SERVER_PORT}`);

  try {
    // Example: Making a search request to the local server
    const response = await axios.post(
      `http://localhost:${DEFAULT_MCP_SERVER_PORT}/mcp/`, 
      {
        tool: 'tavily-search',
        query: 'latest advancements in AI models'
      },
      {
        headers: { 'Content-Type': 'application/json' }
      }
    );
    console.log('Search Results:', JSON.stringify(response.data, null, 2));
  } catch (error: any) {
    console.error('Failed to make request to MCP server:', error.message);
    if (error.response) {
      console.error('Server response data:', error.response.data);
    }
  } finally {
    await server.stop();
    console.log('Tavily MCP Server stopped.');
  }
}

startAndTestServer();