Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:202-231 (registration)

  Registers the 'search_web' MCP tool, providing name, description, Zod input schema, and inline handler function.

  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. 💡 Tip: Use `parallel_search_web` if you need to run multiple searches simultaneously.",
  	{
  		query: z.string().describe("Search terms or keywords to find relevant web content (e.g., 'climate change news 2024', 'best pizza recipe')"),
  		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 }: SearchWebArgs) => {
  		try {
  			const props = getProps();
  
  			const tokenError = checkBearerToken(props.bearerToken);
  			if (tokenError) {
  				return tokenError;
  			}
  
  			const searchResult = await executeWebSearch({ query, num, tbs, location, gl, hl }, props.bearerToken);
  
  			return {
  				content: formatSingleSearchResultToContentItems(searchResult),
  			};
  		} catch (error) {
  			return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  		}
  	},
  );

• src/tools/jina-tools.ts:213-230 (handler)

  MCP tool handler for 'search_web': validates bearer token, calls executeWebSearch utility, formats result with formatSingleSearchResultToContentItems, handles errors.

  async ({ query, num, tbs, location, gl, hl }: SearchWebArgs) => {
  	try {
  		const props = getProps();
  
  		const tokenError = checkBearerToken(props.bearerToken);
  		if (tokenError) {
  			return tokenError;
  		}
  
  		const searchResult = await executeWebSearch({ query, num, tbs, location, gl, hl }, props.bearerToken);
  
  		return {
  			content: formatSingleSearchResultToContentItems(searchResult),
  		};
  	} catch (error) {
  		return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  	}
  },

• src/tools/jina-tools.ts:205-212 (schema)

  Zod schema defining input parameters for the search_web tool.

  {
  	query: z.string().describe("Search terms or keywords to find relevant web content (e.g., 'climate change news 2024', 'best pizza recipe')"),
  	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")
  },

• src/utils/search.ts:55-86 (helper)

  Core helper function implementing the web search logic: sends POST request to Jina's search API (https://svip.jina.ai/) with query parameters and bearer token.

  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/utils/search.ts:7-14 (schema)

  TypeScript interface SearchWebArgs defining the structure of input arguments for web search, imported and used for typing the handler.

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

• src/utils/search.ts:224-233 (helper)

  Helper function to format a single search result (or error) into MCP-standard content items (YAML text blocks). Called by the tool handler.

  export function formatSingleSearchResultToContentItems(searchResult: SearchResultOrError): Array<{ type: 'text'; text: string }> {
      if ('error' in searchResult) {
          return [{
              type: "text" as const,
              text: `Error: ${searchResult.error}`,
          }];
      }
  
      return formatSearchResultsToContentItems(searchResult.results);
  }