MCP Fetch

Instructions

Implementation Reference

• src/tools/fetch.ts:70-218 (handler)

  Main handler function for the 'fetch' tool. Performs HTTP requests using globalThis.fetch, validates inputs, handles timeouts, body content types, parses responses (JSON/text/binary), and returns structured results or errors.
  export default async function fetch(params: InferSchema<typeof schema>) { try { const { url, method, headers, body, timeout, followRedirects, signal, ...fetchOptions } = params // Validate URL if (!url || url.trim() === '') { throw new TypeError('Invalid URL: URL cannot be empty'); } try { new URL(url); } catch { throw new TypeError('Invalid URL: Not a valid URL format'); } // Build fetch options const options: RequestInit = { method, headers: headers || {}, ...fetchOptions, } // Handle followRedirects parameter if (followRedirects === false) { options.redirect = 'manual'; } // Add body if provided and method supports it if (body && ["POST", "PUT", "PATCH", "DELETE"].includes(method)) { options.body = body // Ensure headers is a proper object for type safety const requestHeaders = options.headers as Record<string, string> // Auto-detect content type if not provided if (!requestHeaders["Content-Type"] && !requestHeaders["content-type"]) { try { JSON.parse(body) requestHeaders["Content-Type"] = "application/json" } catch { // If not JSON, assume plain text requestHeaders["Content-Type"] = "text/plain" } } } // Create abort controller for timeout let abortController: AbortController | undefined let timeoutId: NodeJS.Timeout | undefined if (timeout) { abortController = new AbortController() options.signal = abortController.signal timeoutId = setTimeout(() => { abortController?.abort() }, timeout) } // Perform the fetch const startTime = Date.now() const response = await globalThis.fetch(url, options) const responseTime = Date.now() - startTime // Clear timeout if set if (timeoutId) { clearTimeout(timeoutId) } // Get response headers const responseHeaders: Record<string, string> = {} response.headers.forEach((value, key) => { responseHeaders[key] = value }) // Determine response content type const contentType = response.headers.get("content-type") || "" let responseBody: any try { if (contentType.includes("application/json")) { responseBody = await response.json() } else if (contentType.includes("text/") || contentType.includes("application/xml")) { responseBody = await response.text() } else { // For binary data, convert to base64 const buffer = await response.arrayBuffer() responseBody = { type: "binary", size: buffer.byteLength, base64: Buffer.from(buffer).toString("base64") } } } catch (error) { responseBody = { error: "Failed to parse response body", message: error instanceof Error ? error.message : "Unknown error" } } return JSON.stringify({ success: true, status: response.status, statusText: response.statusText, headers: responseHeaders, body: responseBody, url: response.url, redirected: response.redirected, responseTime: `${responseTime}ms`, request: { method, url: params.url, headers: headers || {} } }, null, 2) } catch (error) { // Handle different error types let errorMessage = "Unknown error occurred" let errorType = "UnknownError" if (error instanceof Error) { errorMessage = error.message if (error.name === "AbortError") { errorType = "TimeoutError" errorMessage = `Request timed out after ${params.timeout}ms` } else if (error.message.includes("Failed to fetch") || error.message.includes("ECONNREFUSED") || error.message.includes("ENOTFOUND")) { errorType = "NetworkError" errorMessage = "Network error - could not connect to the server" } else if (error.message.includes("Invalid URL") || error.message.includes("invalid URL")) { errorType = "InvalidURLError" } else if (error instanceof TypeError && (error.message.includes("fetch") || error.message.includes("URL"))) { errorType = "InvalidURLError" } } return JSON.stringify({ success: false, error: errorMessage, errorType, request: { method: params.method, url: params.url, headers: params.headers || {} } }, null, 2) } }
• src/tools/fetch.ts:5-55 (schema)

  Input schema for the fetch tool using Zod, defining parameters like url, method, headers, body, and various fetch options.
  export const schema = { url: z.string().describe("The URL to fetch from"), method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]) .optional() .default("GET") .describe("The HTTP method to use. Defaults to GET"), headers: z.record(z.string()) .optional() .describe("HTTP headers to include in the request as key-value pairs"), body: z.string() .optional() .describe("The request body. Can be a string, JSON, or form data"), mode: z.enum(["cors", "no-cors", "same-origin"]) .optional() .describe("The mode for the request (cors, no-cors, or same-origin)"), credentials: z.enum(["omit", "same-origin", "include"]) .optional() .describe("Whether to include credentials with the request"), cache: z.enum(["default", "no-store", "reload", "no-cache", "force-cache", "only-if-cached"]) .optional() .describe("The cache mode for the request"), redirect: z.enum(["follow", "error", "manual"]) .optional() .default("follow") .describe("How to handle redirects. Defaults to follow"), referrer: z.string() .optional() .describe("The referrer to send with the request"), referrerPolicy: z.enum([ "no-referrer", "no-referrer-when-downgrade", "origin", "origin-when-cross-origin", "same-origin", "strict-origin", "strict-origin-when-cross-origin", "unsafe-url" ]) .optional() .describe("The referrer policy for the request"), signal: z.any() .optional() .describe("An AbortSignal to abort the request"), timeout: z.number() .optional() .describe("Request timeout in milliseconds"), followRedirects: z.boolean() .optional() .default(true) .describe("Whether to follow redirects. Defaults to true"), }
• src/tools/fetch.ts:58-67 (registration)

  Tool metadata registration defining the name 'fetch', description, and annotations for the MCP tool.
  export const metadata: ToolMetadata = { name: "fetch", description: "Perform HTTP requests with full control over method, headers, body, and other fetch options", annotations: { title: "HTTP Fetch", readOnlyHint: false, destructiveHint: false, idempotentHint: false, }, }