Lupul-Augmentat/docs/tools/http-request.md

HTTP Request Tool

Make HTTP/HTTPS requests with comprehensive options and security controls.

Overview

The HttpRequestTool enables making HTTP requests to external services with support for various methods, headers, authentication, and response handling.

Input Schema

{
  url: string;                        // Target URL (required)
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
  headers?: Record<string, string>;   // Request headers
  body?: string | object;             // Request body
  timeout?: number;                   // Timeout in ms (default: 30000)
  followRedirects?: boolean;          // Follow redirects (default: true)
}

Output Schema

{
  status: number;                     // HTTP status code
  statusText: string;                 // Status message
  headers: Record<string, string>;    // Response headers
  body: any;                          // Response body (parsed based on content-type)
  duration: number;                   // Request duration in ms
}

Features

Supported Methods

• GET - Retrieve data
• POST - Submit data
• PUT - Update resource
• DELETE - Remove resource
• PATCH - Partial update
• HEAD - Headers only
• OPTIONS - Check allowed methods

Automatic Content Handling

• JSON responses are automatically parsed
• Text responses returned as strings
• Binary data returned as base64 encoded strings
• Content-Type header automatically set for JSON bodies

Security Features

• Blocks requests to private IP ranges (localhost, internal networks)
• Validates URLs before making requests
• Timeout protection against hanging requests
• Requires network:http permission

Example Usage

Simple GET Request

const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/users'
});
console.log(response.body); // Parsed JSON

POST with JSON Body

const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/users',
  method: 'POST',
  body: {
    name: 'John Doe',
    email: 'john@example.com'
  }
});

Custom Headers

const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/data',
  headers: {
    'Authorization': 'Bearer token123',
    'X-API-Key': 'myapikey'
  }
});

Form Data

const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/form',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: 'name=John&email=john@example.com'
});

With Timeout

const response = await mcp.callTool('http_request', {
  url: 'https://slow-api.example.com/data',
  timeout: 5000  // 5 seconds
});

Disable Redirect Following

const response = await mcp.callTool('http_request', {
  url: 'https://example.com/redirect',
  followRedirects: false
});
// Check response.status for 301/302

Response Handling

JSON Response

const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/json'
});
// response.body is already parsed object
console.log(response.body.data);

Text Response

const response = await mcp.callTool('http_request', {
  url: 'https://example.com/text.txt'
});
// response.body is string
console.log(response.body);

Binary Response

const response = await mcp.callTool('http_request', {
  url: 'https://example.com/image.png'
});
// response.body is base64 encoded string
const buffer = Buffer.from(response.body, 'base64');

Status Checking

const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/resource'
});

if (response.status >= 200 && response.status < 300) {
  // Success
} else if (response.status === 404) {
  // Not found
} else if (response.status >= 500) {
  // Server error
}

Error Handling

Network Errors

try {
  const response = await mcp.callTool('http_request', {
    url: 'https://nonexistent.example.com'
  });
} catch (error) {
  // Error: HTTP request failed: ...
}

Timeout Errors

try {
  const response = await mcp.callTool('http_request', {
    url: 'https://slow.example.com',
    timeout: 1000
  });
} catch (error) {
  // Error: Request timeout after 1000ms
}

Invalid URLs

try {
  const response = await mcp.callTool('http_request', {
    url: 'not-a-url'
  });
} catch (error) {
  // Error: Invalid URL
}

Blocked Internal IPs

try {
  const response = await mcp.callTool('http_request', {
    url: 'http://192.168.1.1/admin'
  });
} catch (error) {
  // Error: Requests to private IP ranges are not allowed
}

Best Practices

1. Always set appropriate timeouts for external requests
2. Handle all status codes - don't assume 200 OK
3. Use HTTPS when possible for security
4. Set User-Agent header to identify your application
5. Implement retry logic for transient failures
6. Respect rate limits of external APIs
7. Validate response data before using it

Common Patterns

API Authentication

// Bearer Token
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/protected',
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});

// API Key
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/data',
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

// Basic Auth
const credentials = Buffer.from('username:password').toString('base64');
const response = await mcp.callTool('http_request', {
  url: 'https://api.example.com/secure',
  headers: {
    'Authorization': `Basic ${credentials}`
  }
});

Pagination

let allData = [];
let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await mcp.callTool('http_request', {
    url: `https://api.example.com/items?page=${page}&limit=100`
  });
  
  allData = allData.concat(response.body.items);
  hasMore = response.body.hasNextPage;
  page++;
}

Limitations

• Cannot access localhost or private networks
• Maximum timeout of 5 minutes
• No support for streaming responses
• No built-in retry mechanism
• No connection pooling or keep-alive