httptoolkit-mcp

Instructions

Implementation Reference

• src/httptoolkit-client.ts:126-181 (handler)

  The HttpToolkitClient.sendHttpRequest method performs the actual HTTP request by communicating with the HTTP Toolkit REST API (/client/send), processes the resulting NDJSON stream, and returns a formatted JSON string of the response.

  async sendHttpRequest(
    request: RequestDefinition,
    options: SendRequestOptions
  ): Promise<string> {
    const url = `${this.baseUrl}/client/send`;
    const body = {
      request: {
        ...request,
        rawBody: request.rawBody
          ? Buffer.from(request.rawBody).toString('base64')
          : '',
      },
      options,
    };
  
    const res = await fetch(url, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(body),
    });
  
    if (!res.ok) {
      const errorBody = await res.text();
      throw new Error(`HTTP Toolkit send request failed (${res.status}): ${errorBody}`);
    }
  
    // Read the NDJSON stream and collect all events
    const text = await res.text();
    const events = text
      .split('\n')
      .filter((line) => line.trim())
      .map((line) => JSON.parse(line));
  
    // Build a readable response summary
    const responseHead = events.find((e: any) => e.type === 'response-head');
    const bodyParts = events.filter((e: any) => e.type === 'response-body-part');
    const error = events.find((e: any) => e.type === 'error');
  
    if (error) {
      throw new Error(`Request failed: ${error.error?.message || JSON.stringify(error)}`);
    }
  
    const responseBody = bodyParts
      .map((p: any) => Buffer.from(p.rawBody, 'base64').toString('utf-8'))
      .join('');
  
    const result: Record<string, unknown> = {};
    if (responseHead) {
      result.statusCode = responseHead.statusCode;
      result.statusMessage = responseHead.statusMessage;
      result.headers = responseHead.headers;
    }
    result.body = responseBody;
  
    return JSON.stringify(result, null, 2);
  }

• src/index.ts:333-364 (registration)

  The send_http_request tool is registered here, defining the input schema and the handler that calls the underlying client.sendHttpRequest method.

  server.registerTool(
    'send_http_request',
    {
      title: 'Send HTTP Request',
      description:
        'Send an HTTP request through the HTTP Toolkit proxy. The request will be intercepted and visible in the HTTP Toolkit UI. Returns the full response including status code, headers, and body.',
      inputSchema: z.object({
        method: z.string().describe('HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)'),
        url: z.string().describe('Full URL to send the request to'),
        headers: z
          .array(z.tuple([z.string(), z.string()]))
          .optional()
          .describe('Request headers as array of [name, value] pairs. Host header is auto-added if missing.'),
        body: z.string().optional().describe('Request body as a string'),
        ignoreHostHttpsErrors: z
          .union([z.array(z.string()), z.boolean()])
          .optional()
          .describe('Hostnames to ignore HTTPS errors for, or true to ignore all'),
      }),
    },
    async ({ method, url, headers, body, ignoreHostHttpsErrors }) => {
      const requestDef = {
        method,
        url,
        headers: headers || [['Host', new URL(url).host]],
        rawBody: body,
      };
      const options = { ignoreHostHttpsErrors };
      const result = await client.sendHttpRequest(requestDef, options);
      return { content: [{ type: 'text' as const, text: result }] };
    }
  );