Jina AI Remote MCP Server

Instructions

Implementation Reference

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

  Handler function for the search_web MCP tool. Validates bearer token, executes the web search via executeWebSearch utility, formats results into content items, and 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/utils/search.ts:55-86 (helper)

  Core helper function that performs the actual web search API call to Jina AI's svip.jina.ai endpoint, constructs the request body from args, and returns structured results or error.
  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 defining the input arguments schema for the search_web tool, used in handler type annotation and Zod schema derivation.
  export interface SearchWebArgs { query: string; num?: number; tbs?: string; location?: string; gl?: string; hl?: string; }
• src/tools/jina-tools.ts:202-231 (registration)

  MCP server.tool registration for 'search_web', including tool name, description, Zod input schema, and reference to 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/utils/search.ts:224-233 (helper)

  Helper function used by the tool handler to convert search results (or error) into MCP-compliant content items as YAML-formatted text blocks.
  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); }