HAL (HTTP API Layer)

An MCP server that enables Large Language Models to make HTTP requests and interact with web APIs. It supports automatic tool generation from OpenAPI/Swagger specifications.

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.

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

- 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

HAL is designed to work with MCP-compatible clients. Here are some examples:

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

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

# 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

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 withHAL_API_BASE_URL)

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

Environment Variables: Define secrets using theHAL_SECRET_prefix:

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

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

Security: The AI never sees the actual secret values, only the template placeholders. Values are substituted at request time.

HAL automatically redacts secret values from all responses sent back to the AI, providing an additional layer of security against credential exposure.
- Secret Tracking: HAL maintains a registry of all secret values from environment variables
- Response Scanning: All HTTP responses (headers, bodies, error messages) are scanned for secret values
- Automatic Replacement: Any occurrence of actual secret values is replaced with[REDACTED]before sending to the AI
- 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

Error: Request cannot be constructed from a URL that includes credentials: https://65GQiI8-1JCOWV1KAuYr0g:-VOIfpydl2GWfucCdEJ1BJ2vrsJyjQ@www.reddit.com/api/v1/access_token

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.

HAL supports organizing secrets into namespaces and restricting them to specific URLs for enhanced security:

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}

Restrict namespaced secrets to specific URLs usingHAL_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/"

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}

- RemoveHAL_SECRET_prefix →AZURE-STORAGE_ACCESS_KEY
- Split on first_→ Namespace:AZURE-STORAGE, Key:ACCESS_KEY
- Transform namespace:AZURE-STORAGE→azure.storage(dashes become dots, lowercase)
- Transform key:ACCESS_KEY→access_key(underscores stay, lowercase)
- Combine:{secrets.azure.storage.access_key}

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

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)

- 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

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

{ "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 withhttps://s3.amazonaws.com/bucket- wrong service!

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

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

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/

- Which secret was blocked
- What URL was attempted
- What URLs are actually allowed

Pattern:HAL_SECRET_<NAMESPACE>_<KEY>→{secrets.<namespace>.<key>}+HAL_ALLOW_<NAMESPACE>

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)

HAL supports global URL filtering to control which URLs can be accessed through whitelist or blacklist patterns. This provides an additional security layer beyond the namespace-based secret restrictions.

WhenHAL_WHITELIST_URLSis set,onlyURLs matching the specified patterns are allowed:

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

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

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

# Production environment - only allow specific APIs HAL_WHITELIST_URLS="https://api.stripe.com/,https://.googleapis.com/,https://api.github.com/" # Development environment - block internal services HAL_BLACKLIST_URLS="http://localhost:,https://192.168.,https://admin.internal.com/" # Restrictive setup - only allow HTTPS to specific domains HAL_WHITELIST_URLS="https://api.trusted-service.com/,https://webhooks.trusted-service.com/"

{ "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 ofHAL_SECRET_GITHUB_TOKENenvironment variable before making the request.

These tools are always available regardless of configuration:

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

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.

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

Make HTTP POST requests with optional body and headers.

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

When you provide a Swagger/OpenAPI specification viaHAL_SWAGGER_FILE, HAL will automatically generate tools for each endpoint defined in the specification. These tools are named using the patternswagger_{operationId}and include:

- Automatic parameter validationbased on the OpenAPI schema
- Path parameter substitution(e.g.,/users/{id}→/users/123)
- Query parameter handling
- Request body supportfor POST/PUT/PATCH operations
- Proper HTTP method mapping

For example, if your OpenAPI spec defines an operation withoperationId: "getUser", HAL will create a tool calledswagger_getUserthat you can use directly.

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

- ✅ 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

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 aswagger_getUsertool that the LLM can use like:

This will make a GET request tohttps://api.example.com/v1/users/123.

# 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

- 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

- 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