Skip to main content
Glama
DeanWard

HAL (HTTP API Layer)

by DeanWard
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

HTTP POST Request

http-post

Send HTTP POST requests to any URL with custom body, headers, and secret substitution from environment variables.

Instructions

Make an HTTP POST request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYes
bodyNo
headersNo
contentTypeNoapplication/json

Implementation Reference

  • src/index.ts:586-605 (handler)
    The http-post tool handler: registers the tool with server.registerTool, defines input schema (url, body, headers, contentType), and makes an HTTP POST request via makeHttpRequest with Content-Type header set.
    server.registerTool(
  "http-post",
  {
    title: "HTTP POST Request",
    description: "Make an HTTP POST request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      body: z.string().optional(),
      headers: z.record(z.string()).optional(),
      contentType: z.string().default('application/json')
    }
  },
  async ({ url, body, headers = {}, contentType }: { url: string; body?: string; headers?: Record<string, string>; contentType: string }) => {
    const requestHeaders = {
      'Content-Type': contentType,
      ...headers
    };
    return makeHttpRequest('POST', url, { headers: requestHeaders, body });
  }
);
  • src/index.ts:587-596 (schema)
    Input schema definition for http-post: url (string.url), body (optional string), headers (optional record), and contentType (default 'application/json').
    "http-post",
{
  title: "HTTP POST Request",
  description: "Make an HTTP POST request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.",
  inputSchema: {
    url: z.string().url(),
    body: z.string().optional(),
    headers: z.record(z.string()).optional(),
    contentType: z.string().default('application/json')
  }
  • src/index.ts:571-692 (registration)
    All HTTP tool registrations on the server, including http-post at line 586. Each tool is registered via server.registerTool with name, metadata, and handler function.
    server.registerTool(
  "http-get",
  {
    title: "HTTP GET Request",
    description: "Make an HTTP GET request to a specified URL. Supports secret substitution using {secrets.key} syntax where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: { 
      url: z.string().url(),
      headers: z.record(z.string()).optional()
    }
  },
  async ({ url, headers = {} }: { url: string; headers?: Record<string, string> }) => {
    return makeHttpRequest('GET', url, { headers });
  }
);

server.registerTool(
  "http-post",
  {
    title: "HTTP POST Request",
    description: "Make an HTTP POST request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      body: z.string().optional(),
      headers: z.record(z.string()).optional(),
      contentType: z.string().default('application/json')
    }
  },
  async ({ url, body, headers = {}, contentType }: { url: string; body?: string; headers?: Record<string, string>; contentType: string }) => {
    const requestHeaders = {
      'Content-Type': contentType,
      ...headers
    };
    return makeHttpRequest('POST', url, { headers: requestHeaders, body });
  }
);

server.registerTool(
  "http-put",
  {
    title: "HTTP PUT Request",
    description: "Make an HTTP PUT request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      body: z.string().optional(),
      headers: z.record(z.string()).optional(),
      contentType: z.string().default('application/json')
    }
  },
  async ({ url, body, headers = {}, contentType }: { url: string; body?: string; headers?: Record<string, string>; contentType: string }) => {
    const requestHeaders = {
      'Content-Type': contentType,
      ...headers
    };
    return makeHttpRequest('PUT', url, { headers: requestHeaders, body });
  }
);

server.registerTool(
  "http-patch",
  {
    title: "HTTP PATCH Request",
    description: "Make an HTTP PATCH request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      body: z.string().optional(),
      headers: z.record(z.string()).optional(),
      contentType: z.string().default('application/json')
    }
  },
  async ({ url, body, headers = {}, contentType }: { url: string; body?: string; headers?: Record<string, string>; contentType: string }) => {
    const requestHeaders = {
      'Content-Type': contentType,
      ...headers
    };
    return makeHttpRequest('PATCH', url, { headers: requestHeaders, body });
  }
);

server.registerTool(
  "http-delete",
  {
    title: "HTTP DELETE Request",
    description: "Make an HTTP DELETE request to a specified URL with optional headers. Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      headers: z.record(z.string()).optional()
    }
  },
  async ({ url, headers = {} }: { url: string; headers?: Record<string, string> }) => {
    return makeHttpRequest('DELETE', url, { headers });
  }
);

server.registerTool(
  "http-head",
  {
    title: "HTTP HEAD Request",
    description: "Make an HTTP HEAD request to a specified URL with optional headers (returns only headers, no body). Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      headers: z.record(z.string()).optional()
    }
  },
  async ({ url, headers = {} }: { url: string; headers?: Record<string, string> }) => {
    return makeHttpRequest('HEAD', url, { headers });
  }
);

server.registerTool(
  "http-options",
  {
    title: "HTTP OPTIONS Request",
    description: "Make an HTTP OPTIONS request to a specified URL to check available methods and headers. Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.",
    inputSchema: {
      url: z.string().url(),
      headers: z.record(z.string()).optional()
    }
  },
  async ({ url, headers = {} }: { url: string; headers?: Record<string, string> }) => {
    return makeHttpRequest('OPTIONS', url, { headers });
  }
);
  • src/index.ts:342-447 (helper)
    The makeHttpRequest helper function: handles HTTP requests with secret substitution, URL validation, query parameter building, header management, response parsing, and secret redaction. Used by http-post handler.
    // Helper function to make HTTP request
async function makeHttpRequest(
  method: string,
  url: string,
  options: {
    headers?: Record<string, string>;
    body?: string;
    queryParams?: Record<string, any>;
  } = {}
) {
  try {
    const { headers = {}, body, queryParams = {} } = options;
    
    // First, substitute secrets in URL to get the final URL for validation
    // We need to do this in two passes to handle URL restrictions properly
    const processedUrl = substituteSecrets(url, url);
    
    // Now substitute secrets in headers, body, and query parameters using the processed URL
    const processedHeaders = substituteSecretsInObject(headers, processedUrl);
    const processedBody = body ? substituteSecrets(body, processedUrl) : body;
    const processedQueryParams = substituteSecretsInObject(queryParams, processedUrl);
    
    // Build URL with query parameters
    const urlObj = new URL(processedUrl);
    Object.entries(processedQueryParams).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        urlObj.searchParams.set(key, String(value));
      }
    });
    
    const finalUrl = urlObj.toString();
    
    // Check global URL whitelist/blacklist
    const urlCheck = isUrlAllowedGlobal(finalUrl);
    if (!urlCheck.allowed) {
      throw new Error(urlCheck.reason || 'URL is not allowed');
    }
    
    const defaultHeaders = {
      'User-Agent': 'HAL-MCP/1.0.0',
      ...processedHeaders
    };
    
         // Add Content-Type for methods that typically send data
     if (['POST', 'PUT', 'PATCH'].includes(method.toUpperCase()) && processedBody && !('Content-Type' in processedHeaders)) {
       (defaultHeaders as any)['Content-Type'] = 'application/json';
     }
    
    const response = await fetch(finalUrl, {
      method: method.toUpperCase(),
      headers: defaultHeaders,
      body: processedBody
    });

    const contentType = response.headers.get('content-type') || 'text/plain';
    let content: string;
    
    // HEAD requests don't have a body by design
    if (method.toUpperCase() === 'HEAD') {
      content = '(No body - HEAD request)';
    } else {
      try {
        if (contentType.includes('application/json')) {
          const text = await response.text();
          if (text.trim()) {
            content = JSON.stringify(JSON.parse(text), null, 2);
          } else {
            content = '(Empty response)';
          }
        } else {
          content = await response.text();
        }
      } catch (parseError) {
        // If JSON parsing fails, try to get text
        try {
          content = await response.text();
        } catch (textError) {
          content = '(Unable to parse response)';
        }
      }
    }

    // Redact secrets from response headers and content before returning
    const redactedHeaders = Array.from(response.headers.entries())
      .map(([key, value]) => `${key}: ${redactSecretsFromText(value)}`)
      .join('\n');
    const redactedContent = redactSecretsFromText(content);

         return {
       content: [{
         type: "text" as const,
         text: `Status: ${response.status} ${response.statusText}\n\nHeaders:\n${redactedHeaders}\n\nBody:\n${redactedContent}`
       }]
     };
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
    const redactedErrorMessage = redactSecretsFromText(errorMessage);
         return {
       content: [{
         type: "text" as const,
         text: `Error making ${method.toUpperCase()} request: ${redactedErrorMessage}`
       }],
       isError: true
     };
  }
}

Tool Definition Quality

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses secret substitution behavior, which is positive, but omits details on idempotency, error handling, rate limits, or whether it's safe/unsafe. For a standard HTTP tool, the lack of such details reduces transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, each serving a purpose: the first states the core operation, the second adds the key feature. No redundant words, and the information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (4 parameters, no output schema, no annotations), the description covers essential purpose and a special feature but lacks details on response structure, error handling, and exactly how secrets are resolved. It is minimally viable but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It notes that body and headers are optional, and secret substitution applies to URL, headers, and body. However, it does not describe the contentType parameter or provide details on the format of headers or the expected body structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it makes an HTTP POST request, specifying the method and optional components (body, headers). It also mentions the unique secret substitution feature, which distinguishes it from sibling tools like http-get and http-put.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. The description implies standard POST semantics (e.g., creating resources) but does not compare with other methods or highlight alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DeanWard/HAL'

If you have feedback or need assistance with the MCP directory API, please join our Discord server