HAL

🚀 HAL (HTTP API Layer)

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

🚀 Quick Start

To get started with HAL, you can follow the usage examples provided below. It's designed to work with MCP-compatible clients, and here are some ways to use it:

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"]
    }
  }
}

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

✨ 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 an isolated environment with controlled access.
• Fast: Built with TypeScript and optimized for performance.

📦 Installation

There's no complex installation process. You can use npx to run HAL directly. For example, in the basic usage with Claude Desktop, npx will handle the installation and running of HAL:

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

💻 Usage Examples

Basic Usage (Claude Desktop)

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

With Swagger/OpenAPI Integration and 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"
      }
    }
  }
}

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

📚 Documentation

Complete Documentation →

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

🔧 Technical Details

Configuration

HAL supports the following environment variables:

Secret Management

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, response headers, response bodies, and all other text returned to the AI.

URL Filtering

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.

Available Tools

Built-in HTTP Tools

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, path parameter substitution, query parameter handling, request body support, and proper HTTP method mapping.

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.

📄 License

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