Tavily MCP Server

Instructions

Implementation Reference

• src/index.ts:121-188 (handler)

  The handleWebSearch method executes the web search tool logic. It validates input arguments, makes an API call to Tavily search service, formats the response into readable markdown, and returns the results as MCP content.

  public async handleWebSearch(args: any) {
    try {
      const searchRequest: TavilySearchRequest = {
        query: args.query,
        search_depth: args.search_depth || "basic",
        include_answer: args.include_answer !== false,
        include_raw_content: false,
        max_results: args.max_results || 5,
        include_domains: args.include_domains,
        exclude_domains: args.exclude_domains,
      };
  
      const response = await axios.post<TavilyResponse>(
        "https://api.tavily.com/search",
        searchRequest,
        {
          headers: {
            "Content-Type": "application/json",
            "Authorization": `Bearer ${this.apiKey}`,
          },
        }
      );
  
      const data = response.data;
      
      // Format the response for better readability
      let formattedResponse = `# Search Results for: "${data.query}"\n\n`;
      
      if (data.answer) {
        formattedResponse += `## Direct Answer\n${data.answer}\n\n`;
      }
      
      formattedResponse += `## Search Results\n\n`;
      
      data.results.forEach((result, index) => {
        formattedResponse += `### ${index + 1}. ${result.title}\n`;
        formattedResponse += `**URL:** ${result.url}\n`;
        if (result.published_date) {
          formattedResponse += `**Published:** ${result.published_date}\n`;
        }
        formattedResponse += `**Score:** ${result.score}\n\n`;
        formattedResponse += `${result.content}\n\n`;
        formattedResponse += `---\n\n`;
      });
  
      if (data.follow_up_questions && data.follow_up_questions.length > 0) {
        formattedResponse += `## Follow-up Questions\n`;
        data.follow_up_questions.forEach((question, index) => {
          formattedResponse += `${index + 1}. ${question}\n`;
        });
      }
  
      return {
        content: [
          {
            type: "text",
            text: formattedResponse,
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        const errorMessage = error.response?.data?.error || error.message;
        throw new Error(`Tavily API error: ${errorMessage}`);
      }
      throw new Error(`Search failed: ${error}`);
    }
  }

• src/index.ts:11-36 (schema)

  TypeScript interfaces defining the structure for TavilySearchRequest, TavilySearchResult, and TavilyResponse. These provide type safety and validation for the API request and response data.

  interface TavilySearchRequest {
    query: string;
    search_depth?: "basic" | "advanced";
    include_answer?: boolean;
    include_raw_content?: boolean;
    max_results?: number;
    include_domains?: string[];
    exclude_domains?: string[];
  }
  
  interface TavilySearchResult {
    title: string;
    url: string;
    content: string;
    score: number;
    published_date?: string;
  }
  
  interface TavilyResponse {
    answer?: string;
    query: string;
    response_time: number;
    images?: string[];
    follow_up_questions?: string[];
    results: TavilySearchResult[];
  }

• src/index.ts:64-111 (registration)

  Registers the web_search tool with the MCP server using ListToolsRequestSchema. Defines the tool name, description, and complete inputSchema with parameters like query, search_depth, max_results, and domain filters.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "web_search",
          description: "Search the web using Tavily API. Returns relevant search results with content snippets.",
          inputSchema: {
            type: "object",
            properties: {
              query: {
                type: "string",
                description: "The search query to execute",
              },
              search_depth: {
                type: "string",
                enum: ["basic", "advanced"],
                description: "The depth of the search (basic or advanced)",
                default: "basic",
              },
              include_answer: {
                type: "boolean",
                description: "Whether to include a direct answer to the query",
                default: true,
              },
              max_results: {
                type: "number",
                description: "Maximum number of search results to return",
                default: 5,
                minimum: 1,
                maximum: 20,
              },
              include_domains: {
                type: "array",
                items: { type: "string" },
                description: "List of domains to include in search",
              },
              exclude_domains: {
                type: "array",
                items: { type: "string" },
                description: "List of domains to exclude from search",
              },
            },
            required: ["query"],
          },
        },
      ],
    };
  });

• src/index.ts:113-118 (registration)

  Routes tool execution requests to the appropriate handler. When a CallToolRequestSchema request comes in for 'web_search', it invokes the handleWebSearch method.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name === "web_search") {
      return await this.handleWebSearch(request.params.arguments);
    }
    throw new Error(`Unknown tool: ${request.params.name}`);
  });

• src/index.ts:70-107 (schema)

  JSON Schema definition for the web_search tool input parameters. Specifies required fields (query), optional fields with defaults (search_depth, include_answer, max_results), and array fields for domain filtering.

  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "The search query to execute",
      },
      search_depth: {
        type: "string",
        enum: ["basic", "advanced"],
        description: "The depth of the search (basic or advanced)",
        default: "basic",
      },
      include_answer: {
        type: "boolean",
        description: "Whether to include a direct answer to the query",
        default: true,
      },
      max_results: {
        type: "number",
        description: "Maximum number of search results to return",
        default: 5,
        minimum: 1,
        maximum: 20,
      },
      include_domains: {
        type: "array",
        items: { type: "string" },
        description: "List of domains to include in search",
      },
      exclude_domains: {
        type: "array",
        items: { type: "string" },
        description: "List of domains to exclude from search",
      },
    },
    required: ["query"],
  },