web_search_exa
Perform real-time web searches and scrape content from URLs to find relevant information for research tasks. Supports configurable result counts and search modes.
Instructions
Search the web using Exa AI - performs real-time web searches and can scrape content from specific URLs. Supports configurable result counts and returns the content from the most relevant websites.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Websearch query | |
| numResults | No | Number of search results to return (default: 8) | |
| livecrawl | No | Live crawl mode - 'fallback': use live crawling as backup if cached content unavailable, 'preferred': prioritize live crawling (default: 'fallback') | |
| type | No | Search type - 'auto': balanced search (default), 'fast': quick results, 'deep': comprehensive search | |
| contextMaxCharacters | No | Maximum characters for context string optimized for LLMs (default: 10000) |
Implementation Reference
- src/tools/webSearch.ts:16-104 (handler)The asynchronous handler function that implements the core logic of the web_search_exa tool. It creates an axios instance, sends a POST request to the Exa API search endpoint with the query and configuration, processes the results or handles errors, and returns markdown-formatted content.async ({ query, numResults }) => { const requestId = `web_search_exa-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`; const logger = createRequestLogger(requestId, 'web_search_exa'); logger.start(query); try { // Create a fresh axios instance for each request const axiosInstance = axios.create({ baseURL: API_CONFIG.BASE_URL, headers: { 'accept': 'application/json', 'content-type': 'application/json', 'x-api-key': config?.exaApiKey || process.env.EXA_API_KEY || '' }, timeout: 25000 }); const searchRequest: ExaSearchRequest = { query, type: "auto", numResults: numResults || API_CONFIG.DEFAULT_NUM_RESULTS, contents: { text: { maxCharacters: API_CONFIG.DEFAULT_MAX_CHARACTERS }, livecrawl: 'preferred' } }; logger.log("Sending request to Exa API"); const response = await axiosInstance.post<ExaSearchResponse>( API_CONFIG.ENDPOINTS.SEARCH, searchRequest, { timeout: 25000 } ); logger.log("Received response from Exa API"); if (!response.data || !response.data.results) { logger.log("Warning: Empty or invalid response from Exa API"); return { content: [{ type: "text" as const, text: "No search results found. Please try a different query." }] }; } logger.log(`Found ${response.data.results.length} results`); const result = { content: [{ type: "text" as const, text: JSON.stringify(response.data, null, 2) }] }; logger.complete(); return result; } catch (error) { logger.error(error); if (axios.isAxiosError(error)) { // Handle Axios errors specifically const statusCode = error.response?.status || 'unknown'; const errorMessage = error.response?.data?.message || error.message; logger.log(`Axios error (${statusCode}): ${errorMessage}`); return { content: [{ type: "text" as const, text: `Search error (${statusCode}): ${errorMessage}` }], isError: true, }; } // Handle generic errors return { content: [{ type: "text" as const, text: `Search error: ${error instanceof Error ? error.message : String(error)}` }], isError: true, }; } }
- src/tools/webSearch.ts:12-15 (schema)Zod input schema defining parameters: required 'query' (string) and optional 'numResults' (number, default 5).{ query: z.string().describe("Search query"), numResults: z.number().optional().describe("Number of search results to return (default: 5)") },
- src/tools/webSearch.ts:8-105 (registration)The registerWebSearchTool export function that registers the web_search_exa tool on the McpServer instance using server.tool(), providing name, description, input schema, and the handler function.export function registerWebSearchTool(server: McpServer, config?: { exaApiKey?: string }): void { server.tool( "web_search_exa", "Search the web using Exa AI - performs real-time web searches and can scrape content from specific URLs. Supports configurable result counts and returns the content from the most relevant websites.", { query: z.string().describe("Search query"), numResults: z.number().optional().describe("Number of search results to return (default: 5)") }, async ({ query, numResults }) => { const requestId = `web_search_exa-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`; const logger = createRequestLogger(requestId, 'web_search_exa'); logger.start(query); try { // Create a fresh axios instance for each request const axiosInstance = axios.create({ baseURL: API_CONFIG.BASE_URL, headers: { 'accept': 'application/json', 'content-type': 'application/json', 'x-api-key': config?.exaApiKey || process.env.EXA_API_KEY || '' }, timeout: 25000 }); const searchRequest: ExaSearchRequest = { query, type: "auto", numResults: numResults || API_CONFIG.DEFAULT_NUM_RESULTS, contents: { text: { maxCharacters: API_CONFIG.DEFAULT_MAX_CHARACTERS }, livecrawl: 'preferred' } }; logger.log("Sending request to Exa API"); const response = await axiosInstance.post<ExaSearchResponse>( API_CONFIG.ENDPOINTS.SEARCH, searchRequest, { timeout: 25000 } ); logger.log("Received response from Exa API"); if (!response.data || !response.data.results) { logger.log("Warning: Empty or invalid response from Exa API"); return { content: [{ type: "text" as const, text: "No search results found. Please try a different query." }] }; } logger.log(`Found ${response.data.results.length} results`); const result = { content: [{ type: "text" as const, text: JSON.stringify(response.data, null, 2) }] }; logger.complete(); return result; } catch (error) { logger.error(error); if (axios.isAxiosError(error)) { // Handle Axios errors specifically const statusCode = error.response?.status || 'unknown'; const errorMessage = error.response?.data?.message || error.message; logger.log(`Axios error (${statusCode}): ${errorMessage}`); return { content: [{ type: "text" as const, text: `Search error (${statusCode}): ${errorMessage}` }], isError: true, }; } // Handle generic errors return { content: [{ type: "text" as const, text: `Search error: ${error instanceof Error ? error.message : String(error)}` }], isError: true, }; } } );
- src/index.ts:86-88 (registration)Higher-level conditional registration: calls registerWebSearchTool if the tool is enabled via configuration.if (shouldRegisterTool('web_search_exa')) { registerWebSearchTool(server, config); registeredTools.push('web_search_exa');