Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:276-318 (handler)

  Primary handler function for the 'search_web' MCP tool. Processes input parameters, supports single or multiple queries (parallel execution), validates bearer token, delegates to executeWebSearch utility, and formats results as MCP content items.

  async ({ query, num, tbs, location, gl, hl }: { query: string | string[]; num: number; tbs?: string; location?: string; gl?: string; hl?: string }) => {
  	try {
  		const props = getProps();
  
  		const tokenError = checkBearerToken(props.bearerToken);
  		if (tokenError) {
  			return tokenError;
  		}
  
  		// Handle single query or single-element array
  		if (typeof query === 'string' || (Array.isArray(query) && query.length === 1)) {
  			const singleQuery = typeof query === 'string' ? query : query[0];
  			const searchResult = await executeWebSearch({ query: singleQuery, num, tbs, location, gl, hl }, props.bearerToken);
  
  			return {
  				content: formatSingleSearchResultToContentItems(searchResult),
  			};
  		}
  
  		// Handle multiple queries with parallel search
  		if (Array.isArray(query) && query.length > 1) {
  			const searches = query.map(q => ({ query: q, num, tbs, location, gl, hl }));
  
  			const uniqueSearches = searches.filter((search, index, self) =>
  				index === self.findIndex(s => s.query === search.query)
  			);
  
  			const webSearchFunction = async (searchArgs: SearchWebArgs) => {
  				return executeWebSearch(searchArgs, props.bearerToken);
  			};
  
  			const results = await executeParallelSearches(uniqueSearches, webSearchFunction, { timeout: 30000 });
  
  			return {
  				content: formatParallelSearchResultsToContentItems(results),
  			};
  		}
  
  		return createErrorResponse("Invalid query format");
  	} catch (error) {
  		return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  	}
  },

• src/tools/jina-tools.ts:264-320 (registration)

  Registers the 'search_web' tool with the MCP server using server.tool(), including name, description, Zod input schema, and handler function, conditional on tool being enabled.

  if (isToolEnabled("search_web")) {
  	server.tool(
  		"search_web",
  		"Search the entire web for current information, news, articles, and websites. Use this when you need up-to-date information, want to find specific websites, research topics, or get the latest news. Ideal for answering questions about recent events, finding resources, or discovering relevant content.",
  		{
  			query: z.union([z.string(), z.array(z.string())]).describe("Search terms or keywords to find relevant web content (e.g., 'climate change news 2024', 'best pizza recipe'). Can be a single query string or an array of queries for parallel search."),
  			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, can be qdr:h, qdr:d, qdr:w, qdr:m, qdr:y"),
  			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")
  		},
  		async ({ query, num, tbs, location, gl, hl }: { query: string | string[]; num: number; tbs?: string; location?: string; gl?: string; hl?: string }) => {
  			try {
  				const props = getProps();
  
  				const tokenError = checkBearerToken(props.bearerToken);
  				if (tokenError) {
  					return tokenError;
  				}
  
  				// Handle single query or single-element array
  				if (typeof query === 'string' || (Array.isArray(query) && query.length === 1)) {
  					const singleQuery = typeof query === 'string' ? query : query[0];
  					const searchResult = await executeWebSearch({ query: singleQuery, num, tbs, location, gl, hl }, props.bearerToken);
  
  					return {
  						content: formatSingleSearchResultToContentItems(searchResult),
  					};
  				}
  
  				// Handle multiple queries with parallel search
  				if (Array.isArray(query) && query.length > 1) {
  					const searches = query.map(q => ({ query: q, num, tbs, location, gl, hl }));
  
  					const uniqueSearches = searches.filter((search, index, self) =>
  						index === self.findIndex(s => s.query === search.query)
  					);
  
  					const webSearchFunction = async (searchArgs: SearchWebArgs) => {
  						return executeWebSearch(searchArgs, props.bearerToken);
  					};
  
  					const results = await executeParallelSearches(uniqueSearches, webSearchFunction, { timeout: 30000 });
  
  					return {
  						content: formatParallelSearchResultsToContentItems(results),
  					};
  				}
  
  				return createErrorResponse("Invalid query format");
  			} catch (error) {
  				return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  			}
  		},
  	);
  }

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

  TypeScript interface SearchWebArgs defining the input parameters for web search operations, used for typing in handlers and utilities.

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

• src/utils/search.ts:67-98 (helper)

  Core utility function that executes the actual web search API call to Jina's svip.jina.ai endpoint, handles parameters, authentication, and returns formatted results or errors.

  export async function executeWebSearch(
      searchArgs: SearchWebArgs,
      bearerToken: string
  ): Promise<SearchResultOrError> {
      try {
          const response = await fetch('https://svip.jina.ai/', {
              method: 'POST',
              headers: {
                  'Accept': 'application/json',
                  'Content-Type': 'application/json',
                  'Authorization': `Bearer ${bearerToken}`,
              },
              body: JSON.stringify({
                  q: searchArgs.query,
                  num: searchArgs.num || 30,
                  ...(searchArgs.tbs && { tbs: searchArgs.tbs }),
                  ...(searchArgs.location && { location: searchArgs.location }),
                  ...(searchArgs.gl && { gl: searchArgs.gl }),
                  ...(searchArgs.hl && { hl: searchArgs.hl })
              }),
          });
  
          if (!response.ok) {
              return { error: `Search failed for query "${searchArgs.query}": ${response.statusText}` };
          }
  
          const data = await response.json() as any;
          return { query: searchArgs.query, results: data.results || [] };
      } catch (error) {
          return { error: `Search failed for query "${searchArgs.query}": ${error instanceof Error ? error.message : String(error)}` };
      }
  }

• src/index.ts:99-102 (registration)

  Calls registerJinaTools to register all tools including 'search_web' on the MCP server instance, passing props getter and enabled tools filter.

  // Register all Jina AI tools with optional filtering
  registerJinaTools(server, () => currentProps, enabledTools);
  
  return server;