mcp-api-tools

Instructions

Implementation Reference

• src/tools/http-request.ts:30-112 (handler)

  The core handler function for the 'http_request' tool, which performs the actual network request using the 'fetch' API.

  export async function httpRequest(
    params: HttpRequestParams
  ): Promise<HttpRequestResult> {
    const {
      method,
      url,
      headers = {},
      body,
      timeout = 30000,
      follow_redirects = true,
      auth,
    } = params;
  
    const upperMethod = method.toUpperCase();
    const validMethods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
    if (!validMethods.includes(upperMethod)) {
      throw new Error(
        `Invalid HTTP method: ${method}. Supported: ${validMethods.join(", ")}`
      );
    }
  
    try {
      new URL(url);
    } catch {
      throw new Error(`Invalid URL: ${url}`);
    }
  
    const requestHeaders: Record<string, string> = { ...headers };
  
    if (auth) {
      if (auth.type === "basic" && auth.username && auth.password) {
        const encoded = Buffer.from(
          `${auth.username}:${auth.password}`
        ).toString("base64");
        requestHeaders["Authorization"] = `Basic ${encoded}`;
      } else if (auth.type === "bearer" && auth.token) {
        requestHeaders["Authorization"] = `Bearer ${auth.token}`;
      }
    }
  
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeout);
  
    const startMs = Date.now();
  
    try {
      const response = await fetch(url, {
        method: upperMethod,
        headers: requestHeaders,
        body:
          upperMethod !== "GET" && upperMethod !== "HEAD" ? body : undefined,
        signal: controller.signal,
        redirect: follow_redirects ? "follow" : "manual",
      });
  
      const responseBody = await response.text();
      const endMs = Date.now();
  
      const responseHeaders: Record<string, string> = {};
      response.headers.forEach((value, key) => {
        responseHeaders[key] = value;
      });
  
      return {
        status: response.status,
        status_text: response.statusText,
        headers: responseHeaders,
        body:
          responseBody.length > 50000
            ? responseBody.slice(0, 50000) + "\n...[truncated]"
            : responseBody,
        timing: {
          start_ms: startMs,
          end_ms: endMs,
          duration_ms: endMs - startMs,
        },
        redirected: response.redirected,
        final_url: response.url,
      };
    } finally {
      clearTimeout(timer);
    }
  }

• src/tools/http-request.ts:1-14 (schema)

  Type definitions for the inputs and outputs of the 'http_request' tool.

  export interface HttpRequestParams {
    method: string;
    url: string;
    headers?: Record<string, string>;
    body?: string;
    timeout?: number;
    follow_redirects?: boolean;
    auth?: {
      type: "basic" | "bearer";
      username?: string;
      password?: string;
      token?: string;
    };
  }

• src/index.ts:29-79 (registration)

  Definition and registration of the 'http_request' tool schema in the MCP server.

  {
    name: "http_request",
    description:
      "Make an HTTP request with full control over method, headers, body, authentication, and timeouts. Returns status, headers, body, and timing information.",
    inputSchema: {
      type: "object" as const,
      properties: {
        method: {
          type: "string",
          description: "HTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS",
        },
        url: {
          type: "string",
          description: "The full URL to send the request to",
        },
        headers: {
          type: "object",
          description: "Key-value pairs of HTTP headers to include",
          additionalProperties: { type: "string" },
        },
        body: {
          type: "string",
          description: "Request body (for POST, PUT, PATCH)",
        },
        timeout: {
          type: "number",
          description: "Request timeout in milliseconds (default: 30000)",
        },
        follow_redirects: {
          type: "boolean",
          description: "Whether to follow redirects (default: true)",
        },
        auth: {
          type: "object",
          description: "Authentication configuration",
          properties: {
            type: {
              type: "string",
              enum: ["basic", "bearer"],
              description: "Auth type: basic or bearer",
            },
            username: { type: "string", description: "Username for basic auth" },
            password: { type: "string", description: "Password for basic auth" },
            token: { type: "string", description: "Token for bearer auth" },
          },
          required: ["type"],
        },
      },
      required: ["method", "url"],
    },
  },

• src/index.ts:191-205 (handler)

  Request handler switch-case in the main MCP server entry point that invokes the 'httpRequest' tool.

  case "http_request": {
    const result = await httpRequest({
      method: args?.method as string,
      url: args?.url as string,
      headers: args?.headers as Record<string, string> | undefined,
      body: args?.body as string | undefined,
      timeout: args?.timeout as number | undefined,
      follow_redirects: args?.follow_redirects as boolean | undefined,
      auth: args?.auth as {
        type: "basic" | "bearer";
        username?: string;
        password?: string;
        token?: string;
      } | undefined,
    });