HAL

HAL is an MCP server that provides an HTTP API layer for large language models. It enables LLMs to perform HTTP requests, interact with web APIs, and securely manage secrets with template substitution. It also has the ability to auto-generate tools from OpenAPI/Swagger specifications, making it easier to integrate external APIs into your LLM workflows. You can run HAL via npx hal-mcp and, depending on your needs, enable Swagger/OpenAPI integration by providing a path or URL to your OpenAPI spec and supplying secret values as environment variables. The self-documented API, secret redaction, and URL-restriction features help keep interactions secure while giving the model the capabilities it needs to fetch data from external services. When configuring HAL, you can load OpenAPI specs from local files or remote URLs and specify a base API URL that overrides the servers in the spec if desired.

To use HAL in your MCP client, add the server configuration under mcpServers with the command and arguments shown in examples. If you want to automatically generate tools from an OpenAPI specification, set HAL_SWAGGER_FILE to point to your spec and provide any required HAL_API_BASE_URL and HAL_SECRET_* environment variables. The generated tools will mirror the endpoints defined in the OpenAPI document, enabling the LLM to call those endpoints through HAL.

Prerequisites:\n- Node.js (recommended v14+ or current LTS) and npm installed on your machine.\n- Basic familiarity with running commands in a terminal.\n\nStep-by-step installation:\n1) Verify Node.js and npm are installed:\nbash\nnode -v\nnpm -v\n\n2) Use npx to run HAL directly (no global install required):\nbash\nnpx hal-mcp\n\n3) If you prefer to keep a local/explicit setup, initialize a project and install HAL as a dev dependency (alternative):\nbash\nnpm init -y\nnpm install hal-mcp --save-dev\n\n4) Start HAL using the MCP configuration from documentation (example shown in this README):\nbash\nnpx hal-mcp\n\n5) For OpenAPI integration, ensure the OpenAPI file is accessible, then start HAL with the appropriate environment variables, for example:\nbash\nHAL_SWAGGER_FILE=/path/to/api.yaml HAL_API_BASE_URL=https://api.example.com npx hal-mcp\n

Tips and common considerations:\n- Secret management: HAL uses environment variables prefixed with HAL_SECRET_ to populate {secrets.} placeholders. Redaction is automatic so the actual secret values are never exposed to the AI.\n- OpenAPI integration: HAL can automatically generate tools based on an OpenAPI/Swagger spec. Provide HAL_SWAGGER_FILE (path or URL) and HAL_API_BASE_URL if you want to override servers defined in the spec.\n- URL restrictions: Use HAL_WHITELIST_URLS and HAL_BLACKLIST_URLS to constrain where HAL may access resources. You can also namespace secrets with HAL_ALLOW_ to restrict which secrets can be used for which URLs.\n- Security: HAL runs in a controlled, isolated environment and supports restrictions via environment configuration to minimize risk when exposing HTTP capabilities to LLMs.\n- Debugging: If tools don’t appear as expected, verify that the OpenAPI spec is valid and accessible, and check that HAL_SWAGGER_FILE points to a valid JSON/YAML document. Ensure HAL_API_BASE_URL is reachable from the HAL process if you override spec servers.