Skip to main content
Glama

HAL (HTTP API Layer)

by DeanWard
MIT License
3

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 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
  • 📄 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

Installation

npx hal-mcp

Via npm

npm install -g hal-mcp hal-mcp

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:

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

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

Configuration

HAL supports 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 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/*")

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.

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-STORAGEazure.storage (dashes become dots, lowercase)
  4. Transform key: ACCESS_KEYaccess_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 VariableTemplate UsageURL 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)

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

Related MCP Servers

  • -
    security
    A
    license
    -
    quality
    An MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
    Last updated -
    2
    Python
    MIT License
  • -
    security
    A
    license
    -
    quality
    Model Context Protocol server for interacting with the HaloPSA API, enabling AI assistants like Claude to manage tickets, users, and assets in HaloPSA through natural language.
    Last updated -
    74
    JavaScript
    MIT License
    • Apple
    • Linux
  • -
    security
    -
    license
    -
    quality
    这是一个基于 ALAPI 的 MCP (Model Control Protocol) 服务器实现,可以通过MCP协议直接调用ALAPI的接口
    Last updated -
    2
    Go
    MIT License
  • -
    security
    A
    license
    -
    quality
    A server that translates Model Context Protocol (MCP) tool callings to traditional HTTP API requests, allowing existing HTTP APIs to be integrated into MCP territory through configurable mappings.
    Last updated -
    Python
    Apache 2.0

View all related MCP servers

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