Skip to main content
Glama
DeanWard

HAL (HTTP API Layer)

by DeanWard
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

MCP Badge

HAL (HTTP API Layer)

HAL is a Model Context Protocol (MCP) server that provides HTTP API capabilities to Large Language Models. It allows LLMs to make HTTP requests and interact with web APIs through a secure, controlled interface. HAL can also automatically generate tools from OpenAPI/Swagger specifications for seamless API integration.

Documentation

Complete Documentation →

Visit our comprehensive documentation site for detailed guides, examples, and API reference.

Related MCP server: FastAPI MCP Server

Features

  • HTTP GET/POST/PUT/PATCH/DELETE/OPTIONS/HEAD Requests: Fetch and send data to any HTTP endpoint

  • Secure Secret Management: Environment-based secrets with {secrets.key} substitution and automatic redaction

  • Swagger/OpenAPI Integration: Automatically generate tools from API specifications

  • Built-in Documentation: Self-documenting API reference

  • Secure: Runs in isolated environment with controlled access

  • Fast: Built with TypeScript and optimized for performance

Usage

HAL is designed to work with MCP-compatible clients. Here are some examples:

Basic Usage (Claude Desktop)

Add HAL to your Claude Desktop configuration (npx will automatically install and run HAL):

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"]
    }
  }
}

With Swagger/OpenAPI Integration and Secrets

To enable automatic tool generation from an OpenAPI specification and use secrets:

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SWAGGER_FILE": "/path/to/your/openapi.json",
        "HAL_API_BASE_URL": "https://api.example.com",
        "HAL_SECRET_API_KEY": "your-secret-api-key",
        "HAL_SECRET_USERNAME": "your-username",
        "HAL_SECRET_PASSWORD": "your-password"
      }
    }
  }
}

URL-based Configuration

You can also load OpenAPI specs directly from URLs:

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SWAGGER_FILE": "/swagger/v1/swagger.json",
        "HAL_API_BASE_URL": "http://localhost:5065",
        "HAL_SECRET_API_KEY": "your-secret-api-key"
      }
    }
  }
}

Direct Usage

# Start the HAL server with default tools
npx hal-mcp

# Or with Swagger/OpenAPI integration
HAL_SWAGGER_FILE=/path/to/api.yaml HAL_API_BASE_URL=https://api.example.com npx hal-mcp

# Or load from URL
HAL_SWAGGER_FILE=/swagger/v1/swagger.json HAL_API_BASE_URL=http://localhost:5065 npx hal-mcp

Configuration

HAL supports the following environment variables:

  • HAL_SWAGGER_FILE: Path or URL to OpenAPI/Swagger specification file (JSON or YAML format). Can be:

    • Local file path: /path/to/api.yaml

    • Full URL: https://api.example.com/swagger.json

    • Relative path: /swagger/v1/swagger.json (combined with HAL_API_BASE_URL)

  • HAL_API_BASE_URL: Base URL for API requests (overrides the servers specified in the OpenAPI spec)

  • HAL_SECRET_*: Secret values for secure substitution in requests (e.g., HAL_SECRET_TOKEN=abc123)

  • HAL_ALLOW_*: URL restrictions for namespaced secrets (e.g., HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*")

  • HAL_WHITELIST_URLS: Comma-separated list of URL patterns that are allowed (if set, only these URLs are permitted)

  • HAL_BLACKLIST_URLS: Comma-separated list of URL patterns that are blocked (if set, these URLs are denied)

Secret Management

HAL provides secure secret management to keep sensitive information like API keys, tokens, and passwords out of the conversation while still allowing the AI to use them in HTTP requests.

How It Works

  1. Environment Variables: Define secrets using the HAL_SECRET_ prefix:

    HAL_SECRET_API_KEY=your-secret-api-key
HAL_SECRET_TOKEN=your-auth-token
HAL_SECRET_USERNAME=your-username

  2. Template Substitution: Reference secrets in your requests using {secrets.key} syntax:

    • URLs: https://api.example.com/data?token={secrets.token}

    • Headers: {"Authorization": "Bearer {secrets.api_key}"}

    • Request Bodies: {"username": "{secrets.username}", "password": "{secrets.password}"}

  3. Security: The AI never sees the actual secret values, only the template placeholders. Values are substituted at request time.

Automatic Secret Redaction

HAL automatically redacts secret values from all responses sent back to the AI, providing an additional layer of security against credential exposure.

How It Works

  1. Secret Tracking: HAL maintains a registry of all secret values from environment variables

  2. Response Scanning: All HTTP responses (headers, bodies, error messages) are scanned for secret values

  3. Automatic Replacement: Any occurrence of actual secret values is replaced with [REDACTED] before sending to the AI

  4. Comprehensive Coverage: Redaction applies to:

    • Error messages (including URL parsing errors that might expose credentials)

    • Response headers (in case APIs echo back authentication data)

    • Response bodies (protecting against API responses that might include sensitive data)

    • All other text returned to the AI

Example Protection

Before (vulnerable):

Error: Request cannot be constructed from a URL that includes credentials: 
https://65GQiI8-1JCOWV1KAuYr0g:-VOIfpydl2GWfucCdEJ1BJ2vrsJyjQ@www.reddit.com/api/v1/access_token

After (secure):

Error: Request cannot be constructed from a URL that includes credentials: 
https://[REDACTED]:[REDACTED]@www.reddit.com/api/v1/access_token

This protection is automatic and requires no configuration - HAL will redact any secret values regardless of how they appear in responses, ensuring that even if an API or error message attempts to expose credentials, the AI never sees the actual values.

Namespaces and URL Restrictions

HAL supports organizing secrets into namespaces and restricting them to specific URLs for enhanced security:

Namespace Convention

Use - for namespace separators and _ for word separators within keys:

# Single namespace
HAL_SECRET_MICROSOFT_API_KEY=your-api-key
# Usage: {secrets.microsoft.api_key}

# Multi-level namespaces
HAL_SECRET_AZURE-STORAGE_ACCESS_KEY=your-storage-key
HAL_SECRET_AZURE-COGNITIVE_API_KEY=your-cognitive-key
HAL_SECRET_GOOGLE-CLOUD-STORAGE_SERVICE_ACCOUNT_KEY=your-service-key
# Usage: {secrets.azure.storage.access_key}
# Usage: {secrets.azure.cognitive.api_key}
# Usage: {secrets.google.cloud.storage.service_account_key}

URL Restrictions

Restrict namespaced secrets to specific URLs using HAL_ALLOW_* environment variables:

# Restrict Microsoft secrets to Microsoft domains
HAL_SECRET_MICROSOFT_API_KEY=your-api-key
HAL_ALLOW_MICROSOFT="https://azure.microsoft.com/*,https://*.microsoft.com/*"

# Restrict Azure Storage secrets to Azure storage endpoints
HAL_SECRET_AZURE-STORAGE_ACCESS_KEY=your-storage-key
HAL_ALLOW_AZURE-STORAGE="https://*.blob.core.windows.net/*,https://*.queue.core.windows.net/*"

# Multiple URLs are comma-separated
HAL_SECRET_GOOGLE-CLOUD_API_KEY=your-google-key
HAL_ALLOW_GOOGLE-CLOUD="https://*.googleapis.com/*,https://*.googlecloud.com/*"

How Parsing Works

Understanding how environment variable names become template keys:

HAL_SECRET_AZURE-STORAGE_ACCESS_KEY
│         │              │
│         │              └─ Key: "ACCESS_KEY" → "access_key" 
│         └─ Namespace: "AZURE-STORAGE" → "azure.storage"
└─ Prefix

Final template: {secrets.azure.storage.access_key}

Step-by-step breakdown:

  1. Remove HAL_SECRET_ prefix → AZURE-STORAGE_ACCESS_KEY

  2. Split on first _ → Namespace: AZURE-STORAGE, Key: ACCESS_KEY

  3. Transform namespace: AZURE-STORAGE → azure.storage (dashes become dots, lowercase)

  4. Transform key: ACCESS_KEY → access_key (underscores stay, lowercase)

  5. Combine: {secrets.azure.storage.access_key}

More Examples

# Simple namespace
HAL_SECRET_GITHUB_TOKEN=your_token
→ {secrets.github.token}

# Two-level namespace  
HAL_SECRET_AZURE-COGNITIVE_API_KEY=your_key
→ {secrets.azure.cognitive.api_key}

# Three-level namespace
HAL_SECRET_GOOGLE-CLOUD-STORAGE_SERVICE_ACCOUNT=your_account
→ {secrets.google.cloud.storage.service_account}

# Complex key with underscores
HAL_SECRET_AWS-S3_BUCKET_ACCESS_KEY_ID=your_id
→ {secrets.aws.s3.bucket_access_key_id}

# No namespace (legacy style)
HAL_SECRET_API_KEY=your_key
→ {secrets.api_key}

Visual Guide: Complete Flow

Environment Variable          Template Usage                   URL Restriction
├─ HAL_SECRET_MICROSOFT_API_KEY    ├─ {secrets.microsoft.api_key}    ├─ HAL_ALLOW_MICROSOFT
├─ HAL_SECRET_AZURE-STORAGE_KEY    ├─ {secrets.azure.storage.key}    ├─ HAL_ALLOW_AZURE-STORAGE  
├─ HAL_SECRET_AWS-S3_ACCESS_KEY    ├─ {secrets.aws.s3.access_key}    ├─ HAL_ALLOW_AWS-S3
└─ HAL_SECRET_UNRESTRICTED_TOKEN   └─ {secrets.unrestricted.token}   └─ (no restriction)

Security Benefits

  • Principle of Least Privilege: Secrets only work with their intended services

  • Prevents Cross-Service Leakage: Azure secrets can't be sent to AWS APIs

  • Defense in Depth: Even with AI errors or prompt injection, secrets are constrained

  • Clear Organization: Namespace structure makes secret management more intuitive

Real-World Usage Scenarios

Scenario 1: Multi-Cloud Application

# Azure services
HAL_SECRET_AZURE-STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...
HAL_SECRET_AZURE-COGNITIVE_SPEECH_KEY=abcd1234...
HAL_ALLOW_AZURE-STORAGE="https://*.blob.core.windows.net/*,https://*.queue.core.windows.net/*"
HAL_ALLOW_AZURE-COGNITIVE="https://*.cognitiveservices.azure.com/*"

# AWS services  
HAL_SECRET_AWS-S3_ACCESS_KEY=AKIA...
HAL_SECRET_AWS-LAMBDA_API_KEY=lambda_key...
HAL_ALLOW_AWS-S3="https://s3.*.amazonaws.com/*,https://*.s3.amazonaws.com/*"
HAL_ALLOW_AWS-LAMBDA="https://*.lambda.amazonaws.com/*"

# Google Cloud
HAL_SECRET_GOOGLE-CLOUD_SERVICE_ACCOUNT_KEY={"type":"service_account"...}
HAL_ALLOW_GOOGLE-CLOUD="https://*.googleapis.com/*"

Usage in requests:

{
  "url": "https://mystorageaccount.blob.core.windows.net/container/file",
  "headers": {
    "Authorization": "Bearer {secrets.azure.storage.connection_string}"
  }
}

✅ Works: URL matches Azure Storage pattern
❌ Blocked: If used with https://s3.amazonaws.com/bucket - wrong service!

Scenario 2: Development vs Production

# Development environment
HAL_SECRET_DEV-API_KEY=dev_key_123
HAL_ALLOW_DEV-API="https://dev-api.example.com/*,https://staging-api.example.com/*"

# Production environment  
HAL_SECRET_PROD-API_KEY=prod_key_456
HAL_ALLOW_PROD-API="https://api.example.com/*"

Scenario 3: Department Isolation

# Marketing team APIs
HAL_SECRET_MARKETING-CRM_API_KEY=crm_key...
HAL_SECRET_MARKETING-ANALYTICS_TOKEN=analytics_token...
HAL_ALLOW_MARKETING-CRM="https://api.salesforce.com/*"
HAL_ALLOW_MARKETING-ANALYTICS="https://api.googleanalytics.com/*"

# Engineering team APIs
HAL_SECRET_ENGINEERING-GITHUB_TOKEN=ghp_...
HAL_SECRET_ENGINEERING-JIRA_API_KEY=jira_key...
HAL_ALLOW_ENGINEERING-GITHUB="https://api.github.com/*"
HAL_ALLOW_ENGINEERING-JIRA="https://*.atlassian.net/*"

Error Examples

When URL restrictions are violated, you get clear error messages:

❌ Error: Secret 'azure.storage.access_key' (namespace: AZURE-STORAGE) is not allowed for URL 'https://api.github.com/user'. 
   Allowed patterns: https://*.blob.core.windows.net/*, https://*.queue.core.windows.net/*

This helps you quickly identify:

  • Which secret was blocked

  • What URL was attempted

  • What URLs are actually allowed

Quick Reference

Environment Variable

Template Usage

URL Restriction

HAL_SECRET_GITHUB_TOKEN

{secrets.github.token}

HAL_ALLOW_GITHUB

HAL_SECRET_AZURE-STORAGE_KEY

{secrets.azure.storage.key}

HAL_ALLOW_AZURE-STORAGE

HAL_SECRET_AWS-S3_ACCESS_KEY

{secrets.aws.s3.access_key}

HAL_ALLOW_AWS-S3

HAL_SECRET_GOOGLE-CLOUD_API_KEY

{secrets.google.cloud.api_key}

HAL_ALLOW_GOOGLE-CLOUD

Pattern: HAL_SECRET_<NAMESPACE>_<KEY> → {secrets.<namespace>.<key>} + HAL_ALLOW_<NAMESPACE>

Backward Compatibility

Non-namespaced secrets (without URL restrictions) continue to work as before:

HAL_SECRET_API_KEY=your-key
# Usage: {secrets.api_key} - works with any URL (no restrictions)

URL Filtering

HAL supports global URL filtering to control which URLs can be accessed through whitelist or blacklist patterns. This provides an additional security layer beyond the namespace-based secret restrictions.

Whitelist Mode

When HAL_WHITELIST_URLS is set, only URLs matching the specified patterns are allowed:

# Only allow requests to GitHub and Google APIs
HAL_WHITELIST_URLS="https://api.github.com/*,https://*.googleapis.com/*"

Blacklist Mode

When HAL_BLACKLIST_URLS is set, all URLs are allowed except those matching the specified patterns:

# Block requests to internal networks and localhost
HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://10.*,https://172.16.*"

Pattern Syntax

URL patterns support wildcard matching using *:

  • https://api.example.com/* - Matches any path under the API

  • https://*.example.com/* - Matches any subdomain

  • *://internal.company.com/* - Matches any protocol

Important Notes

  • Whitelist takes precedence: If both HAL_WHITELIST_URLS and HAL_BLACKLIST_URLS are set, the whitelist is used and a warning is logged

  • Global filtering: This applies to all HTTP requests, regardless of secrets or tools used

  • Case-insensitive: URL pattern matching is case-insensitive

  • No filtering by default: If neither environment variable is set, all URLs are allowed

Examples

# Production environment - only allow specific APIs
HAL_WHITELIST_URLS="https://api.stripe.com/*,https://*.googleapis.com/*,https://api.github.com/*"

# Development environment - block internal services
HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://admin.internal.com/*"

# Restrictive setup - only allow HTTPS to specific domains
HAL_WHITELIST_URLS="https://api.trusted-service.com/*,https://webhooks.trusted-service.com/*"

Example Usage

{
  "url": "https://api.github.com/user",
  "headers": {
    "Authorization": "Bearer {secrets.github_token}",
    "Accept": "application/vnd.github.v3+json"
  }
}

The {secrets.github_token} will be replaced with the value of HAL_SECRET_GITHUB_TOKEN environment variable before making the request.

Available Tools

Built-in HTTP Tools

These tools are always available regardless of configuration:

list-secrets

Get a list of available secret keys that can be used with {secrets.key} syntax.

Parameters: None

Example Response:

Available secrets (3 total):

You can use these secret keys in your HTTP requests using the {secrets.key} syntax:

1. {secrets.api_key}
2. {secrets.github_token}  
3. {secrets.username}

Usage examples:
- URL: "https://api.example.com/data?token={secrets.api_key}"
- Header: {"Authorization": "Bearer {secrets.api_key}"}
- Body: {"username": "{secrets.username}"}

Security Note: Only shows the key names, never the actual secret values.

http-get

Make HTTP GET requests to any URL.

Parameters:

  • url (string, required): The URL to request

  • headers (object, optional): Additional headers to send

Example:

{
  "url": "https://api.github.com/user",
  "headers": {
    "Authorization": "Bearer {secrets.github_token}",
    "Accept": "application/vnd.github.v3+json"
  }
}

http-post

Make HTTP POST requests with optional body and headers.

Parameters:

  • url (string, required): The URL to request

  • body (string, optional): Request body content

  • headers (object, optional): Additional headers to send

  • contentType (string, optional): Content-Type header (default: "application/json")

Example:

{
  "url": "https://api.example.com/data",
  "body": "{\"message\": \"Hello, World!\", \"user\": \"{secrets.username}\"}",
  "headers": {
    "Authorization": "Bearer {secrets.api_key}"
  },
  "contentType": "application/json"
}

Auto-generated Swagger/OpenAPI Tools

When you provide a Swagger/OpenAPI specification via HAL_SWAGGER_FILE, HAL will automatically generate tools for each endpoint defined in the specification. These tools are named using the pattern swagger_{operationId} and include:

  • Automatic parameter validation based on the OpenAPI schema

  • Path parameter substitution (e.g., /users/{id} → /users/123)

  • Query parameter handling

  • Request body support for POST/PUT/PATCH operations

  • Proper HTTP method mapping

For example, if your OpenAPI spec defines an operation with operationId: "getUser", HAL will create a tool called swagger_getUser that you can use directly.

Available Resources

docs://hal/api

Access comprehensive API documentation and usage examples, including documentation for any auto-generated Swagger tools.

OpenAPI/Swagger Integration Details

Supported OpenAPI Features

  • ✅ OpenAPI 3.x and Swagger 2.x specifications

  • ✅ JSON and YAML format support

  • ✅ Path parameters (/users/{id})

  • ✅ Query parameters

  • ✅ Request body (JSON, form-encoded)

  • ✅ All HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.)

  • ✅ Parameter validation (string, number, boolean, arrays)

  • ✅ Required/optional parameter handling

  • ✅ Custom headers support

Example OpenAPI Integration

Given this OpenAPI specification:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users/{id}:
    get:
      operationId: getUser
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success

HAL will automatically create a swagger_getUser tool that the LLM can use like:

{
  "id": "123"
}

This will make a GET request to https://api.example.com/v1/users/123.

Development

Prerequisites

  • Node.js 18 or later

  • npm or yarn

Setup

# Clone the repository
git clone https://github.com/your-username/hal-mcp.git
cd hal-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Scripts

  • npm run build - Build the TypeScript project

  • npm run dev - Run in development mode with hot reload

  • npm start - Start the built server

  • npm run lint - Run ESLint

  • npm test - Run tests

Security Considerations

  • HAL makes actual HTTP requests to external services

  • Use appropriate authentication and authorization for your APIs

  • Be mindful of rate limits and API quotas

  • Consider network security and firewall rules

  • When using Swagger integration, ensure your OpenAPI specifications are from trusted sources

Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Available Tools

8 tools
http-deleteHTTP DELETE RequestA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
headersNo

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description must convey behavioral traits. It mentions secret substitution, which is a useful feature, but fails to disclose error handling, authentication requirements, idempotency, or side effects of the request.

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, front-loaded with the primary action, and each sentence adds distinct information (the request itself and the secret substitution feature). No wasted words.

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?

For a simple HTTP tool, the description covers the essential action and a key feature (secret substitution). However, it lacks information on response handling, error conditions, and whether the tool modifies server state, which would be relevant given no output schema.

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?

With 0% schema description coverage, the description adds value by explaining the secret substitution syntax applicable to both url and headers. However, it does not detail the purpose of the headers parameter beyond being optional, nor the expected URL format beyond URI.

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 'Make an HTTP DELETE request', identifying the specific HTTP method and resource. The name and title reinforce this, and the sibling tools include other HTTP methods, making the distinction obvious.

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?

The description does not provide explicit guidance on when to use this tool over alternatives like http-get or http-post. The context suggests it is for DELETE requests, but no further context on appropriate scenarios or prerequisites is given.

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

http-getHTTP GET RequestB

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
headersNo

TDQS

B3.3/5.0
Behavior3/5

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

Discloses secret substitution feature using {secrets.key} syntax, which is a notable behavior. However, lacks other behavioral details such as idempotency, error handling, or response format. Since annotations are absent, more transparency is needed.

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?

Extremely concise with two sentences conveying essential purpose and a key feature (secret substitution). No redundancy.

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

Completeness2/5

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

Given no output schema and complex nested parameter (headers), the description omits important context like return values, error responses, or behavior of headers. Incomplete for effective use.

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

Parameters2/5

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

Schema coverage is 0%, meaning the description does not elaborate on parameter usage beyond the schema. The description mentions secret substitution but does not relate it to parameters. No information on how headers affect the request.

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?

Clearly states 'Make an HTTP GET request to a specified URL', specifying exact verb and resource. Implicitly differentiates from sibling tools like http-post or http-delete by naming the method.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus siblings (e.g., when a GET vs POST is appropriate). No prerequisites or exclusions provided.

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

http-headHTTP HEAD RequestA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
headersNo

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries full behavioral disclosure burden. It adds the behavioral detail of secret substitution using {secrets.key} syntax, which is valuable. However, it does not cover other behaviors such as error handling, redirect following, timeouts, or authentication requirements.

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, front-loading the core purpose and key behavior in the first sentence. Every sentence adds value; there is no redundancy or unnecessary detail.

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 absence of an output schema and annotations, the description partially compensates by stating the response is 'only headers, no body'. However, it lacks details on status codes, error responses, and potential redirect behavior, leaving gaps for a complete understanding.

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

Parameters4/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 compensate. It explains that headers are optional and introduces secret substitution for both URL and headers, adding meaning beyond the schema's basic type definitions.

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 the verb ('Make an HTTP HEAD request') and specific resource (a URL). It notes that it 'returns only headers, no body', which implicitly differentiates it from sibling tools like http-get that return body content. The mention of secret substitution adds specificity.

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?

The description implies usage when only headers are needed ('returns only headers, no body') but does not explicitly state when to use this tool versus alternatives like http-get. No when-not or alternative tool names are provided.

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

http-optionsHTTP OPTIONS RequestA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
headersNo

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It mentions secret substitution using {secrets.key} syntax, which adds value, but lacks information on authentication needs, error handling, or rate limits.

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?

Two sentences, front-loaded with the main action. No redundant words. Efficiently conveys purpose and a key feature (secret substitution).

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

Completeness4/5

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

Given no annotations, no output schema, and 0% schema coverage, the description is fairly complete. It covers the main purpose and secret substitution. Could have mentioned that no request body is sent (implied by OPTIONS).

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 mentions URL and headers implicitly and adds the secret substitution feature for both. However, it does not elaborate on the format or constraints beyond the schema.

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 the tool makes an HTTP OPTIONS request to check available methods and headers. It distinguishes itself from sibling tools like http-get and http-post by specifying the HTTP method.

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?

The description implies usage for checking methods/headers but does not explicitly compare with alternatives or state when not to use it. No exclusions or preconditions are mentioned.

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

http-patchHTTP PATCH RequestB

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
bodyNo
headersNo
contentTypeNoapplication/json

TDQS

B3.2/5.0
Behavior3/5

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

The description discloses the secret substitution feature using {secrets.key} syntax, which is a behavioral trait beyond the input schema. However, it does not mention authentication requirements, error handling, or the idempotency nature of PATCH. Annotations are absent, so the description carries the burden, but it adds some value.

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

Conciseness4/5

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

The description is two sentences, front-loading the primary action in the first sentence. It is concise without redundancy, though the secret substitution detail could be more seamlessly integrated.

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

Completeness2/5

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

Given the lack of annotations and output schema, the description does not cover return values, error behavior, or authentication context. It only addresses the request structure and secrets feature, leaving significant gaps for a tool that sends network requests.

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

Parameters2/5

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

With 0% schema description coverage, the description must add meaning to parameters. It only generically mentions 'optional body and headers' without explaining each parameter's purpose, format, or constraints. The secret substitution detail applies to URL and headers, but it's not tied to the parameters explicitly.

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 explicitly states 'Make an HTTP PATCH request' which is a specific verb+resource combination. The tool name and title align, and it clearly distinguishes from sibling tools which represent different HTTP methods (GET, POST, PUT, etc.).

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

Usage Guidelines2/5

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

No guidance is provided on when to use PATCH versus the sibling methods (POST, PUT, DELETE). The description lacks context about partial updates or idempotency, leaving the agent to infer usage from the method name alone.

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

http-postHTTP POST RequestA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
bodyNo
headersNo
contentTypeNoapplication/json

TDQS

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.

http-putHTTP PUT RequestB

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
bodyNo
headersNo
contentTypeNoapplication/json

TDQS

B3.3/5.0
Behavior3/5

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

The description discloses the secret substitution feature, which is valuable behavioral context. However, it does not mention idempotency, response handling, or potential errors, and there are no annotations to supplement these details.

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 concise with two sentences, front-loading the core purpose and adding a key feature. Every sentence serves a clear purpose without redundancy.

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

Completeness2/5

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

Given the absence of annotations and output schema, the description should be more thorough. It lacks details on response format, authentication, error cases, and idempotency, leaving the agent underinformed for a network operation.

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

Parameters2/5

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

With 0% schema description coverage, the description should explain each parameter. It only mentions URL, body, and headers, and omits the contentType parameter entirely. The secret substitution hint is useful but insufficient to clarify parameter roles.

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 the tool makes an HTTP PUT request to a specified URL with optional body and headers. The verb and resource are explicit, and it effectively distinguishes from sibling HTTP methods.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like http-patch or http-post. No conditions or exclusions are mentioned, leaving the agent without context for selection.

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

list-secretsList Available SecretsA

Get a list of available secret keys that can be used with {secrets.key} syntax. Only shows the key names, never the actual secret values.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explicitly states that only key names are shown and never actual secret values, which is a critical safety trait. Additional details like authentication or rate limits are absent, but the primary behavioral constraint is well communicated.

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 a single, information-dense sentence with no wasted words. It front-loads the action and resource, then adds a critical safety caveat.

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

Completeness5/5

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

For a tool with no parameters and no output schema, the description fully covers what the tool does and what it returns (key names) and explicitly what it does not return (values). It provides sufficient context for correct usage.

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

Parameters4/5

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

The tool has zero parameters and schema coverage is 100% trivially. The description does not need to add parameter meaning. According to guidelines, 0 parameters earns a baseline of 4.

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 uses specific verb 'Get a list' and clearly identifies the resource 'available secret keys'. It distinguishes itself from sibling HTTP tools by focusing on secrets. The additional detail about not showing actual values further clarifies purpose.

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?

The description implies usage when a list of secret keys is needed, but does not explicitly state when not to use or provide alternatives. Among sibling tools, it is unique, so no competing tool is mentioned, but the description lacks explicit guidance.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.14
    • Changedlist-secrets1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
  2. 8 tool updatesv1.0.0
    • First observedhttp-delete
    • First observedhttp-get
    • First observedhttp-head
    • First observedhttp-options
    • First observedhttp-patch
    • First observedhttp-post
    • First observedhttp-put
    • First observedlist-secrets
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Each tool corresponds to a distinct HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) plus a separate secrets management tool. There is no overlap in purpose.

Naming Consistency5/5

All HTTP tools use a consistent 'http-<method>' naming pattern, and 'list-secrets' follows a similar verb-noun pattern. The naming is predictable and uniform.

Tool Count5/5

With 8 tools covering standard HTTP methods and secrets management, the count is well-scoped for an HTTP API layer. No tool feels extraneous or missing.

Completeness5/5

The set includes all common HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) along with secrets management, providing full coverage for typical HTTP interactions.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • OpenAPI MCP Server

    ivo-toby
    A
    license
    Not graded
    quality
    A
    maintenance
    A server that enables Large Language Models to discover and interact with REST APIs defined by OpenAPI specifications through the Model Context Protocol.
    3,501
    289
    MIT

  • FastAPI MCP Server

    purity3
    A
    license
    Not graded
    quality
    D
    maintenance
    A high-performance Model Context Protocol (MCP) server designed for large language models, enabling real-time communication between AI models and applications with support for session management and intelligent tool registration.
    2
    MIT

  • Hugging Face MCP Server

    huggingface
    A
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that provides Hugging Face Hub API and Search endpoints through multiple transport protocols (STDIO, SSE, StreamableHTTP, and StreamableHTTPJson), enabling integration with AI model capabilities.
    289
    MIT

  • OpenAPI MCP Server

    oneWalker
    A
    license
    Not graded
    quality
    D
    maintenance
    A server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.
    322
    2
    MIT

Appeared in Searches

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