http-delete
Make an HTTP DELETE request to a specified URL with optional headers. Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.
LABSCO SUMMARY
The model builds the request; the credential is filled in after it leaves.
That indirection is the whole design — a key referenced as {secrets.key} is substituted at send time and redacted from the response, so an API token never enters the transcript, and HAL_ALLOW_ patterns stop a secret from being sent to a host it was not meant for. The OpenAPI mode is the second reason to reach for it: point it at a specification and the endpoints arrive as tools, which beats teaching a model to hand-assemble paths. Treat it as powerful by construction — with no host restrictions configured, these seven tools can reach anything the machine can.
What it is
A general HTTP client for models. Seven verb tools plus a secret-substitution scheme: credentials live in the environment and are referenced as {secrets.key}, so the model composes requests with them without ever seeing their values.
What you get
- http-get, http-post, http-put, http-patch, http-delete, http-head and http-options, each taking a URL, headers, and where relevant a body and content type
- {secrets.key} placeholders substituted in the URL, headers and body from HAL_SECRET_ variables — the actual values are redacted from what comes back
- list-secrets returns only the key names available, never the values, so the model can see what it may reference
- HAL_ALLOW_ variables restrict a namespaced secret to specific URLs, so a key meant for one vendor cannot be sent to another host
- An OpenAPI or Swagger specification named in HAL_SWAGGER_FILE — a local path or a URL, JSON or YAML — is turned into tools automatically, with HAL_API_BASE_URL overriding the servers the spec declares
Requirements
No account of its own — it needs whatever the APIs you point it at need. It runs as npx hal-mcp. Secrets go in HAL_SECRET_ prefixed variables, one per credential; HAL_ALLOW_ variables bind namespaced secrets to permitted URL patterns; HAL_SWAGGER_FILE and HAL_API_BASE_URL switch on the generated-tools mode. Note what it does not have: no allowlist of hosts by default, so a request can go anywhere the machine can reach.
Setup effort
One command — npx hal-mcp
USE CASES
01
Calling an API that has no MCP server of its own
Make the request directly with the right method, headers and body, and reference the key rather than pasting it.
02
Turning an OpenAPI spec into usable tools
Point HAL at the specification and its endpoints become callable tools, with the base URL overridden if the spec's servers are wrong for your environment.
03
Working with an authenticated API without leaking the token
Put the credential in the environment, reference it by key in the header, and let substitution and redaction keep it out of the conversation.
04
Checking what an endpoint supports before calling it
Ask for its options and headers first, which is cheaper than a failed request against an unfamiliar API.
05
Driving a REST resource through its lifecycle
Create it, amend it in place, replace it wholesale, and delete it when done.
8 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
http-get
Make an HTTP GET request to a specified URL. Supports secret substitution using {secrets.key} syntax where 'key' corresponds to HAL_SECRET_KEY environment variables.
http-head
Make an HTTP HEAD request to a specified URL with optional headers (returns only headers, no body). Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.
http-options
Make an HTTP OPTIONS request to a specified URL to check available methods and headers. Supports secret substitution using {secrets.key} syntax in URL and headers where 'key' corresponds to HAL_SECRET_KEY environment variables.
http-patch
Make an HTTP PATCH request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.
http-post
Make an HTTP POST request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.
http-put
Make an HTTP PUT request to a specified URL with optional body and headers. Supports secret substitution using {secrets.key} syntax in URL, headers, and body where 'key' corresponds to HAL_SECRET_KEY environment variables.
list-secrets
Get a list of available secret keys that can be used with {secrets.key} syntax. Only shows the key names, never the actual secret values.
BEFORE YOU INSTALL
What to know first
Tools you get
8 tools when we connected. Setting HAL_SWAGGER_FILE to a spec adds one swagger_{operationId} tool per endpoint, so a configured install exposes 8 plus the spec's operations.
Requires
- npx on PATH
- Node.js 18 or later
CONTEXT COST
Light Standing cost
Rated by the size of the 8 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
Any MCP client — npx
TERMINAL
npx hal-mcpMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"hal": {
"command": "npx",
"args": [
"hal-mcp"
]
}
}
}Claude Desktop — With OpenAPI
CLAUDE DESKTOP — WITH OPENAPI · JSON
{
"mcpServers": {
"hal": {
"command": "npx",
"args": [
"hal-mcp"
],
"env": {
"HAL_SWAGGER_FILE": "<YOUR_HAL_SWAGGER_FILE>",
"HAL_API_BASE_URL": "<YOUR_HAL_API_BASE_URL>",
"HAL_SECRET_API_KEY": "<YOUR_HAL_SECRET_API_KEY>",
"HAL_SECRET_USERNAME": "<YOUR_HAL_SECRET_USERNAME>",
"HAL_SECRET_PASSWORD": "<YOUR_HAL_SECRET_PASSWORD>"
}
}
}
}
