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.

Features

HTTP Methods

Complete support for all HTTP operations

GET, POST, PUT, PATCH, DELETE, OPTIONS, and HEAD requests to fetch and send data to any HTTP endpoint.

Secure Secret Management

Environment-based secrets with automatic redaction

Use {secrets.key} substitution to keep sensitive information secure while enabling API access. All responses are automatically scanned and any secret values are redacted with [REDACTED] before reaching the AI.

OpenAPI Integration

Automatic tool generation from API specifications

Automatically generate tools from Swagger/OpenAPI specifications for seamless API integration.

Built-in Documentation

Self-documenting API reference

Access comprehensive API documentation and usage examples through the built-in resource system.

Installation

Quick and Easy

Just add HAL to your Claude Desktop configuration and npx will automatically download and run it.

Configuration Examples

HAL is designed to work with MCP-compatible clients. Choose the configuration that best fits your needs:

Basic Setup

The simplest configuration with no environment variables. This gives you access to all the basic HTTP tools (GET, POST, PUT, etc.) for making requests to any public API.

Basic Claude Desktop Configuration

No environment variables needed - just add HAL and start making HTTP requests

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

What you get

Access to all basic HTTP tools (http-get, http-post, http-put, etc.) for making requests to public APIs.

With Swagger/OpenAPI

Automatically generate tools from your OpenAPI/Swagger specification. HAL will create custom tools for each endpoint defined in your API spec.

Swagger/OpenAPI Integration

Enable automatic tool generation from API specifications

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

What you get

Basic HTTP tools PLUS auto-generated tools for each endpoint in your OpenAPI spec (named swagger_{operationId}).

Basic Secrets

Securely store API keys, tokens, and other sensitive data using environment variables. The AI never sees the actual values.

Simple Secret Management

Keep API keys and tokens secure with {secrets.key} substitution

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SECRET_API_KEY": "your-secret-api-key",
        "HAL_SECRET_TOKEN": "your-auth-token",
        "HAL_SECRET_USERNAME": "your-username",
        "HAL_SECRET_PASSWORD": "your-password"
      }
    }
  }
}

How the AI can use these secrets:

Authorization: Bearer {secrets.api_key}
X-Auth-Token: {secrets.token}
https://api.example.com/data?token={secrets.api_key}

Namespaced Secrets with URL Restrictions

Organize secrets by service and restrict them to specific URLs for enhanced security. Perfect for managing multiple API providers.

Advanced Secret Organization

Namespace secrets and restrict them to specific domains

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_SECRET_GITHUB_API_KEY": "github_pat_xxxxx",
        "HAL_ALLOW_GITHUB": "https://api.github.com/*,https://*.github.com/*",
        
        "HAL_SECRET_AZURE-STORAGE_ACCESS_KEY": "azure_storage_key_xxxxx",
        "HAL_SECRET_AZURE-COGNITIVE_API_KEY": "azure_cognitive_key_xxxxx",
        "HAL_ALLOW_AZURE-STORAGE": "https://*.blob.core.windows.net/*",
        "HAL_ALLOW_AZURE-COGNITIVE": "https://*.cognitiveservices.azure.com/*",
        
        "HAL_SECRET_GOOGLE-CLOUD_SERVICE_ACCOUNT": "google_service_account_json",
        "HAL_ALLOW_GOOGLE-CLOUD": "https://*.googleapis.com/*,https://*.googlecloud.com/*"
      }
    }
  }
}

How the AI can use these namespaced secrets:

{secrets.github.api_key} - Only works with GitHub URLs
{secrets.azure.storage.access_key} - Only works with Azure Storage
{secrets.google.cloud.service_account} - Only works with Google APIs

URL Whitelist

Restrict HAL to only make requests to specific, trusted domains. All other URLs will be blocked.

Whitelist Mode - Maximum Security

Only allow requests to explicitly approved URLs

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_WHITELIST_URLS": "https://api.github.com/*,https://*.googleapis.com/*,https://httpbin.org/*",
        "HAL_SECRET_GITHUB_TOKEN": "your-github-token",
        "HAL_SECRET_GOOGLE_API_KEY": "your-google-api-key"
      }
    }
  }
}

Security Note:

When whitelist is active, only URLs matching the patterns will be accessible. All other requests will be blocked with an error.

URL Blacklist

Block specific URLs or patterns while allowing everything else. Useful for preventing access to internal networks or specific services.

Blacklist Mode - Selective Blocking

Block specific URLs while allowing everything else

{
  "mcpServers": {
    "hal": {
      "command": "npx",
      "args": ["hal-mcp"],
      "env": {
        "HAL_BLACKLIST_URLS": "http://localhost:*,https://192.168.*,https://10.*,https://172.16.*,https://169.254.*",
        "HAL_SECRET_API_KEY": "your-external-api-key"
      }
    }
  }
}

Security Note:

This example blocks access to localhost and common internal network ranges, while allowing all external APIs.

Environment Variables

HAL supports the following environment variables for configuration:

Variable	Description
`HAL_SWAGGER_FILE`	Path to OpenAPI/Swagger specification file (JSON or YAML format)
`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

The AI can reference secrets in its 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

The AI only sees the template placeholders like {secrets.api_key}. When the AI makes a request using these placeholders, HAL substitutes the actual secret values at request time.

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
# AI can use: {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
# AI can use: {secrets.azure.storage.access_key}
# AI can use: {secrets.azure.cognitive.api_key}
# AI can use: {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:

Step-by-step breakdown

Example: HAL_SECRET_AZURE-STORAGE_ACCESS_KEY

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}

Available Tools

Built-in HTTP Tools

These tools are always available regardless of configuration:

`list-secrets`

Get a list of available secret keys

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

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

{
  "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")

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

OpenAPI/Swagger Integration

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
✓ Parameter validation
✓ Required/optional parameter handling
✓ Custom headers support

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, path parameter substitution, and proper HTTP method mapping.

⚠️ Warning: Large OpenAPI/Swagger specifications may generate a very large number of tools. This can clutter your toolset and impact performance. Consider limiting your specification to only the endpoints you need.

Available Resources

`docs://hal/api`

Comprehensive API documentation and usage examples

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

Security Considerations

HAL provides powerful HTTP capabilities that require careful security consideration. Follow these best practices to keep your data and systems safe.

Secret Management

Environment Variables

Keep sensitive data secure

• Store all API keys, tokens, and passwords in environment variables
• Never hardcode secrets in your configuration files
• Use {secrets.key} substitution to reference secrets safely
• The AI never sees the actual secret values, only the template placeholders

Namespace Restrictions

Limit secret scope with URL restrictions

• Use HAL_ALLOW_* to restrict secrets to specific domains
• Organize secrets by service using namespaces
• Prevent credential leakage across different APIs
• Follow the principle of least privilege

Automatic Secret Redaction

Response Protection

All responses are automatically scanned and secrets are redacted

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

⚠️ 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

What gets redacted:

• Error messages (including URL parsing errors)
• Response headers (in case APIs echo back auth data)
• Response bodies (protecting against sensitive API responses)
• All other text returned to the AI

Note: This protection is automatic and requires no configuration. HAL tracks all secret values and replaces them with [REDACTED] before any text reaches the AI.

Network Security

URL Access Control

Control which endpoints HAL can access

Whitelist Mode (Recommended)

Only allow specific, trusted domains

HAL_WHITELIST_URLS="https://api.github.com/*,https://*.googleapis.com/*"

Blacklist Mode

Block internal networks and sensitive endpoints

HAL_BLACKLIST_URLS="http://localhost:*,https://192.168.*,https://10.*"

HTTPS and TLS

Secure communication protocols

• Always use HTTPS for production APIs
• Verify SSL certificates are valid
• Avoid HTTP for sensitive data transmission
• Consider certificate pinning for high-security environments

API Usage Best Practices

Rate Limiting & Quotas

Respect API limits and prevent abuse

• Monitor API usage to avoid hitting rate limits
• Implement retry logic with exponential backoff
• Be aware of daily/monthly quota restrictions
• Consider caching responses when appropriate

Authentication & Authorization

Properly secure API access

• Use strong authentication methods (OAuth, API keys)
• Implement proper authorization checks
• Rotate API keys and tokens regularly
• Use scoped permissions when available

OpenAPI/Swagger Security

Specification Trust

Ensure your API specifications come from trusted sources

Important Warnings:

• Large OpenAPI specs can generate hundreds of tools, impacting performance
• Only use specifications from trusted, verified sources
• Review the generated tools before using them in production
• Consider limiting specifications to only the endpoints you need

Best Practices:

• Validate OpenAPI specifications before deployment
• Use version-controlled specifications when possible
• Test generated tools in a development environment first
• Monitor tool usage and API calls in production

Security Checklist

Pre-deployment Checklist

Verify these security measures before going live

Configuration Security

☐ All secrets stored in environment variables
☐ URL restrictions configured (whitelist/blacklist)
☐ Namespace restrictions applied where needed
☐ No hardcoded credentials in configuration
☐ Automatic secret redaction is enabled (default)

Runtime Security

☐ HTTPS enabled for all external APIs
☐ Rate limiting awareness and monitoring
☐ Network firewall rules reviewed
☐ API permissions follow least privilege principle