Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:334-391 (registration)

  Full registration of the search_arxiv MCP tool, including name, description, Zod input schema (query, optional num), and the complete async handler function that calls Jina's search API with domain='arxiv' to fetch and return academic paper results in YAML format.

  server.tool(
  	"search_arxiv",
  	"Search academic papers and preprints on arXiv repository. Perfect for finding research papers, scientific studies, technical papers, and academic literature. Use this when researching scientific topics, looking for papers by specific authors, or finding the latest research in fields like AI, physics, mathematics, computer science, etc. Returns academic papers with URLs, titles, abstracts, and metadata.",
  	{
  		query: z.string().describe("Academic search terms, author names, or research topics (e.g., 'transformer neural networks', 'Einstein relativity', 'machine learning optimization')"),
  		num: z.number().optional().describe("Maximum number of academic papers to return, between 1-100 (default: 30)")
  	},
  	async ({ query, num = 30 }: { query: string; num?: number }) => {
  		try {
  			const props = getProps();
  
  			const tokenError = checkBearerToken(props.bearerToken);
  			if (tokenError) {
  				return tokenError;
  			}
  
  			const response = await fetch('https://svip.jina.ai/', {
  				method: 'POST',
  				headers: {
  					'Accept': 'application/json',
  					'Content-Type': 'application/json',
  					'Authorization': `Bearer ${props.bearerToken}`,
  				},
  				body: JSON.stringify({
  					q: query,
  					domain: 'arxiv',
  					num
  				}),
  			});
  
  			if (!response.ok) {
  				return handleApiError(response, "arXiv search");
  			}
  
  			const data = await response.json() as any;
  
  
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: yamlStringify(data.results),
  					},
  				],
  			};
  		} catch (error) {
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: `Error: ${error instanceof Error ? error.message : String(error)}`,
  					},
  				],
  				isError: true,
  			};
  		}
  	},
  );

• src/index.ts:21-22 (registration)

  Calls registerJinaTools to register all tools including search_arxiv on the MCP server during initialization.

  	registerJinaTools(this.server, () => this.props);
  }

• src/utils/api-error-handler.ts:5-51 (helper)

  handleApiError helper function used in search_arxiv handler to return standardized error responses for common API errors like 401, 402, 429.

  export function handleApiError(response: Response, context: string = "API request") {
  	if (response.status === 401) {
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: "Authentication failed. Please set your API key in the Jina AI MCP settings. You can get a free API key by visiting https://jina.ai and signing up for an account.",
  				},
  			],
  			isError: true,
  		};
  	}
  	if (response.status === 402) {
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: "This key is out of quota. Please top up this key at https://jina.ai",
  				},
  			],
  			isError: true,
  		};
  	}
  	
  	if (response.status === 429) {
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: "Rate limit exceeded. Please upgrade your API key to get higher rate limits. Visit https://jina.ai to manage your subscription and increase your usage limits.",
  				},
  			],
  			isError: true,
  		};
  	}
  	
  	// Default error message for other HTTP errors
  	return {
  		content: [
  			{
  				type: "text" as const,
  				text: `Error: ${context} failed - ${response.status} ${response.statusText}`,
  			},
  		],
  		isError: true,
  	};
  }

• src/utils/api-error-handler.ts:56-69 (helper)

  checkBearerToken helper function used in search_arxiv handler to validate the presence of Jina API key (bearer token) before making API calls.

  export function checkBearerToken(bearerToken: string | undefined) {
  	if (!bearerToken) {
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: "Please set your API key in the Jina AI MCP settings. You can get a free API key by visiting https://jina.ai and signing up for an account.",
  				},
  			],
  			isError: true,
  		};
  	}
  	return null; // No error, token is available
  }