Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:417-444 (handler)

  The main handler function for the parallel_search_web tool. It validates the bearer token, deduplicates search queries, defines a web search wrapper, executes parallel searches using executeParallelSearches, and formats the results.

  async ({ searches, timeout }: { searches: SearchWebArgs[]; timeout: number }) => {
  	try {
  		const props = getProps();
  
  		const tokenError = checkBearerToken(props.bearerToken);
  		if (tokenError) {
  			return tokenError;
  		}
  
  		const uniqueSearches = searches.filter((search, index, self) =>
  			index === self.findIndex(s => s.query === search.query)
  		);
  
  		// Use the common web search function
  		const webSearchFunction = async (searchArgs: SearchWebArgs) => {
  			return executeWebSearch(searchArgs, props.bearerToken);
  		};
  
  		// Execute parallel searches using utility
  		const results = await executeParallelSearches(uniqueSearches, webSearchFunction, { timeout });
  
  		return {
  			content: formatParallelSearchResultsToContentItems(results),
  		};
  	} catch (error) {
  		return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  	}
  },

• src/tools/jina-tools.ts:406-416 (schema)

  Zod input schema for parallel_search_web tool defining the array of web search configurations (max 5) and timeout.

  {
  	searches: z.array(z.object({
  		query: z.string().describe("Search terms or keywords to find relevant web content"),
  		num: z.number().default(30).describe("Maximum number of search results to return, between 1-100"),
  		tbs: z.string().optional().describe("Time-based search parameter, e.g., 'qdr:h' for past hour"),
  		location: z.string().optional().describe("Location for search results, e.g., 'London', 'New York', 'Tokyo'"),
  		gl: z.string().optional().describe("Country code, e.g., 'dz' for Algeria"),
  		hl: z.string().optional().describe("Language code, e.g., 'zh-cn' for Simplified Chinese")
  	})).max(5).describe("Array of search configurations to execute in parallel (maximum 5 searches for optimal performance)"),
  	timeout: z.number().default(30000).describe("Timeout in milliseconds for all searches")
  },

• src/tools/jina-tools.ts:403-445 (registration)

  Registration of the parallel_search_web tool using server.tool() in registerJinaTools function.

  server.tool(
  	"parallel_search_web",
  	"Run multiple web searches in parallel for comprehensive topic coverage and diverse perspectives. For best results, provide multiple search queries that explore different aspects of your topic. You can use expand_query to help generate diverse queries, or create them yourself. 💡 Use this when you need to gather information from multiple search angles at once for efficiency.",
  	{
  		searches: z.array(z.object({
  			query: z.string().describe("Search terms or keywords to find relevant web content"),
  			num: z.number().default(30).describe("Maximum number of search results to return, between 1-100"),
  			tbs: z.string().optional().describe("Time-based search parameter, e.g., 'qdr:h' for past hour"),
  			location: z.string().optional().describe("Location for search results, e.g., 'London', 'New York', 'Tokyo'"),
  			gl: z.string().optional().describe("Country code, e.g., 'dz' for Algeria"),
  			hl: z.string().optional().describe("Language code, e.g., 'zh-cn' for Simplified Chinese")
  		})).max(5).describe("Array of search configurations to execute in parallel (maximum 5 searches for optimal performance)"),
  		timeout: z.number().default(30000).describe("Timeout in milliseconds for all searches")
  	},
  	async ({ searches, timeout }: { searches: SearchWebArgs[]; timeout: number }) => {
  		try {
  			const props = getProps();
  
  			const tokenError = checkBearerToken(props.bearerToken);
  			if (tokenError) {
  				return tokenError;
  			}
  
  			const uniqueSearches = searches.filter((search, index, self) =>
  				index === self.findIndex(s => s.query === search.query)
  			);
  
  			// Use the common web search function
  			const webSearchFunction = async (searchArgs: SearchWebArgs) => {
  				return executeWebSearch(searchArgs, props.bearerToken);
  			};
  
  			// Execute parallel searches using utility
  			const results = await executeParallelSearches(uniqueSearches, webSearchFunction, { timeout });
  
  			return {
  				content: formatParallelSearchResultsToContentItems(results),
  			};
  		} catch (error) {
  			return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  		}
  	},
  );

• src/utils/search.ts:165-197 (helper)

  Core helper function that executes multiple searches in parallel with timeout handling, used by the parallel_search_web handler.

  export async function executeParallelSearches<T>(
      searches: T[],
      searchFunction: (searchArgs: T) => Promise<SearchResultOrError>,
      options: ParallelSearchOptions = {}
  ): Promise<ParallelSearchResult[]> {
      const { timeout = 30000 } = options;
  
      // Execute all searches in parallel
      const searchPromises = searches.map(async (searchArgs) => {
          try {
              return await searchFunction(searchArgs);
          } catch (error) {
              return { error: `Search failed: ${error instanceof Error ? error.message : String(error)}` };
          }
      });
  
      // Wait for all searches with timeout
      const results = await Promise.allSettled(searchPromises);
      const timeoutPromise = new Promise(resolve => setTimeout(() => resolve('timeout'), timeout));
  
      const completedResults = await Promise.race([
          Promise.all(results.map(result =>
              result.status === 'fulfilled' ? result.value : { error: 'Promise rejected' }
          )),
          timeoutPromise
      ]);
  
      if (completedResults === 'timeout') {
          throw new Error(`Parallel search timed out after ${timeout}ms`);
      }
  
      return completedResults as ParallelSearchResult[];
  }

• src/utils/search.ts:7-14 (schema)

  Type definition for individual web search arguments used in parallel_search_web searches array.

  export interface SearchWebArgs {
      query: string;
      num?: number;
      tbs?: string;
      location?: string;
      gl?: string;
      hl?: string;
  }