Allows secure access to Atlassian services through namespaced secrets and domain-specific URL restrictions.
Allows making requests to GitHub's API for accessing user data and repositories, with support for authentication via tokens stored as secrets.
Supports integration with Google Cloud services via API requests using service account keys stored securely as namespaced secrets.
Supports interaction with Jira's API for engineering teams through namespaced secrets and URL restrictions to Atlassian endpoints.
Enables interaction with Salesforce CRM APIs through URL restrictions and secure credential management for marketing team access.
Provides automatic tool generation from OpenAPI/Swagger specifications, enabling seamless integration with any API that offers a Swagger specification.
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
Via npx (Recommended)
Via npm
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:
With Swagger/OpenAPI Integration and Secrets
To enable automatic tool generation from an OpenAPI specification and use secrets:
Direct Usage
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
- Environment Variables: Define secrets using the
HAL_SECRET_
prefix: - 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}"}
- URLs:
- 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:
URL Restrictions
Restrict namespaced secrets to specific URLs using HAL_ALLOW_*
environment variables:
How Parsing Works
Understanding how environment variable names become template keys:
Step-by-step breakdown:
- Remove
HAL_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}
More Examples
Visual Guide: Complete Flow
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
Usage in requests:
✅ Works: URL matches Azure Storage pattern
❌ Blocked: If used with https://s3.amazonaws.com/bucket
- wrong service!
Scenario 2: Development vs Production
Scenario 3: Department Isolation
Error Examples
When URL restrictions are violated, you get clear error messages:
This helps you quickly identify:
- Which secret was blocked
- What URL was attempted
- What URLs are actually allowed
Quick Reference
Environment Variable | Template Usage | URL 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:
Example Usage
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:
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 requestheaders
(object, optional): Additional headers to send
Example:
http-post
Make HTTP POST requests with optional body and headers.
Parameters:
url
(string, required): The URL to requestbody
(string, optional): Request body contentheaders
(object, optional): Additional headers to sendcontentType
(string, optional): Content-Type header (default: "application/json")
Example:
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:
HAL will automatically create a swagger_getUser
tool that the LLM can use like:
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
Scripts
npm run build
- Build the TypeScript projectnpm run dev
- Run in development mode with hot reloadnpm start
- Start the built servernpm run lint
- Run ESLintnpm 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built with the Model Context Protocol TypeScript SDK
- Inspired by the need for LLMs to interact with web APIs safely and efficiently
- OpenAPI integration powered by swagger-parser
HAL (HTTP API Layer) is a Model Context Protocol (MCP) server that provides HTTP API capabilities to Large Language Models.
- Features
- Installation
- Usage
- Configuration
- Secret Management
- Available Tools
- Available Resources
- OpenAPI/Swagger Integration Details
- Development
- Security Considerations
- Contributing
- License
- Acknowledgments
Related Resources
Related MCP Servers
- -securityAlicense-qualityAn MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.Last updated -2PythonMIT License
- -securityAlicense-qualityModel 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 -74JavaScriptMIT License
mcp-alapi-cnofficial
-security-license-quality这是一个基于 ALAPI 的 MCP (Model Control Protocol) 服务器实现,可以通过MCP协议直接调用ALAPI的接口Last updated -2GoMIT License- -securityAlicense-qualityA 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 -PythonApache 2.0