Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:46-136 (handler)

  The core handler function that implements capture_screenshot_url tool logic: calls r.jina.ai API with URL, handles response to get screenshot URL, downloads the image, encodes as base64 PNG, and returns as MCP image content with error handling.

  async ({ url, firstScreenOnly }: { url: string; firstScreenOnly?: boolean }) => {
  	try {
  		const props = getProps();
  		const headers: Record<string, string> = {
  			'Accept': 'application/json',
  			'Content-Type': 'application/json',
  			'X-Return-Format': firstScreenOnly === true ? 'screenshot' : 'pageshot',
  		};
  
  		// Add Authorization header if bearer token is available
  		if (props.bearerToken) {
  			headers['Authorization'] = `Bearer ${props.bearerToken}`;
  		}
  
  		const response = await fetch('https://r.jina.ai/', {
  			method: 'POST',
  			headers,
  			body: JSON.stringify({ url }),
  		});
  
  		if (!response.ok) {
  			return handleApiError(response, "Screenshot capture");
  		}
  
  		const data = await response.json() as any;
  
  		// Fetch and return the screenshot as base64-encoded image
  		const imageUrl = data.data.screenshotUrl || data.data.pageshotUrl;
  		if (imageUrl) {
  			try {
  				// Download the image from the URL
  				const imageResponse = await fetch(imageUrl);
  				if (!imageResponse.ok) {
  					return {
  						content: [
  							{
  								type: "text" as const,
  								text: `Error: Failed to download screenshot from ${imageUrl}`,
  							},
  						],
  						isError: true,
  					};
  				}
  
  				// Convert to base64
  				const imageBuffer = await imageResponse.arrayBuffer();
  				const base64Image = Buffer.from(imageBuffer).toString('base64');
  
  				return {
  					content: [
  						{
  							type: "image" as const,
  							data: base64Image,
  							mimeType: "image/png",
  						},
  					],
  				};
  			} catch (downloadError) {
  				return {
  					content: [
  						{
  							type: "text" as const,
  							text: `Error downloading screenshot: ${downloadError instanceof Error ? downloadError.message : String(downloadError)}`,
  						},
  					],
  					isError: true,
  				};
  			}
  		} else {
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: "Error: No screenshot URL received from API",
  					},
  				],
  				isError: true,
  			};
  		}
  	} catch (error) {
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: `Error: ${error instanceof Error ? error.message : String(error)}`,
  				},
  			],
  			isError: true,
  		};
  	}
  },

• src/tools/jina-tools.ts:42-45 (schema)

  Zod schema defining input parameters for the tool: required 'url' (string URL) and optional 'firstScreenOnly' (boolean).

  {
  	url: z.string().url().describe("The complete HTTP/HTTPS URL of the webpage to capture (e.g., 'https://example.com')"),
  	firstScreenOnly: z.boolean().optional().describe("Set to true for a single screen capture (faster), false for full page capture including content below the fold (default: false)")
  },

• src/tools/jina-tools.ts:39-137 (registration)

  Registers the 'capture_screenshot_url' tool on the MCP server using server.tool(), providing name, description, input schema, and handler function.

  server.tool(
  	"capture_screenshot_url",
  	"Capture high-quality screenshots of web pages. Use this tool when you need to visually inspect a website, take a snapshot for analysis, or show users what a webpage looks like. Returns the screenshot as a base64-encoded PNG image that can be displayed directly.",
  	{
  		url: z.string().url().describe("The complete HTTP/HTTPS URL of the webpage to capture (e.g., 'https://example.com')"),
  		firstScreenOnly: z.boolean().optional().describe("Set to true for a single screen capture (faster), false for full page capture including content below the fold (default: false)")
  	},
  	async ({ url, firstScreenOnly }: { url: string; firstScreenOnly?: boolean }) => {
  		try {
  			const props = getProps();
  			const headers: Record<string, string> = {
  				'Accept': 'application/json',
  				'Content-Type': 'application/json',
  				'X-Return-Format': firstScreenOnly === true ? 'screenshot' : 'pageshot',
  			};
  
  			// Add Authorization header if bearer token is available
  			if (props.bearerToken) {
  				headers['Authorization'] = `Bearer ${props.bearerToken}`;
  			}
  
  			const response = await fetch('https://r.jina.ai/', {
  				method: 'POST',
  				headers,
  				body: JSON.stringify({ url }),
  			});
  
  			if (!response.ok) {
  				return handleApiError(response, "Screenshot capture");
  			}
  
  			const data = await response.json() as any;
  
  			// Fetch and return the screenshot as base64-encoded image
  			const imageUrl = data.data.screenshotUrl || data.data.pageshotUrl;
  			if (imageUrl) {
  				try {
  					// Download the image from the URL
  					const imageResponse = await fetch(imageUrl);
  					if (!imageResponse.ok) {
  						return {
  							content: [
  								{
  									type: "text" as const,
  									text: `Error: Failed to download screenshot from ${imageUrl}`,
  								},
  							],
  							isError: true,
  						};
  					}
  
  					// Convert to base64
  					const imageBuffer = await imageResponse.arrayBuffer();
  					const base64Image = Buffer.from(imageBuffer).toString('base64');
  
  					return {
  						content: [
  							{
  								type: "image" as const,
  								data: base64Image,
  								mimeType: "image/png",
  							},
  						],
  					};
  				} catch (downloadError) {
  					return {
  						content: [
  							{
  								type: "text" as const,
  								text: `Error downloading screenshot: ${downloadError instanceof Error ? downloadError.message : String(downloadError)}`,
  							},
  						],
  						isError: true,
  					};
  				}
  			} else {
  				return {
  					content: [
  						{
  							type: "text" as const,
  							text: "Error: No screenshot URL received from API",
  						},
  					],
  					isError: true,
  				};
  			}
  		} catch (error) {
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: `Error: ${error instanceof Error ? error.message : String(error)}`,
  					},
  				],
  				isError: true,
  			};
  		}
  	},
  );

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

  Calls registerJinaTools in the MCP agent's init() method, which registers all Jina tools including capture_screenshot_url.

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