HAL (HTTP API Layer) MCP server

HAL (HTTP API Layer) is a Model Context Protocol (MCP) server that enables Large Language Models to make HTTP requests and interact with web APIs through a secure interface. It supports various HTTP methods, secure secret management, and can automatically generate tools from OpenAPI/Swagger specifications for seamless API integration.

Installation

Basic Installation

You can run HAL using npx, which automatically installs and runs it:

npx hal-mcp

Integration with Claude Desktop

Add HAL to your Claude Desktop configuration:

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

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

Configuration

HAL can be configured using the following environment variables:

• HAL_SWAGGER_FILE: Path to OpenAPI/Swagger specification file (JSON or YAML format)
• HAL_API_BASE_URL: Base URL for API requests (overrides 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
• HAL_BLACKLIST_URLS: Comma-separated list of URL patterns that are blocked

Using HAL

Built-in HTTP Tools

HAL provides several built-in tools for making HTTP requests:

HTTP GET Requests

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

HTTP POST Requests

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

Listing Available Secrets

The list-secrets tool shows all available secret keys (but not their values):

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

Secret Management

HAL provides secure secret management for sensitive information like API keys.

Setting Up Secrets

Define secrets using environment variables with the HAL_SECRET_ prefix:

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

Using Secrets in Requests

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

{
  "url": "https://api.example.com/data?token={secrets.token}",
  "headers": {
    "Authorization": "Bearer {secrets.api_key}"
  },
  "body": "{\"username\": \"{secrets.username}\", \"message\": \"Hello\"}"
}

Namespaced Secrets

Organize secrets into namespaces for better organization and security:

# 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
# Usage: {secrets.azure.storage.access_key}

URL Restrictions for Secrets

Restrict namespaced secrets to specific URLs for enhanced security:

# 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/*"

URL Filtering

Control which URLs can be accessed using whitelist or blacklist patterns:

Whitelist Mode

Only URLs matching specified patterns are allowed:

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

Blacklist Mode

All URLs are allowed except those matching specified patterns:

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

OpenAPI/Swagger Integration

HAL can automatically generate tools from an OpenAPI specification:

1. Provide a Swagger file path:

   HAL_SWAGGER_FILE=/path/to/api.yaml HAL_API_BASE_URL=https://api.example.com npx hal-mcp
   

2. HAL generates tools named swagger_{operationId} for each endpoint.

For example, with 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 creates a swagger_getUser tool that can be used like:

{
  "id": "123"
}

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

Accessing Documentation

HAL provides built-in documentation accessible through the resource:

docs://hal/api

This provides comprehensive API documentation, including any auto-generated Swagger tools.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hal" '{"command":"npx","args":["hal-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect