HAL

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 →](https://deanward.github.io/HAL/documentation/)

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

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

1. 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}"}

1. 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