Configuration¶
The server reads a small set of environment variables. Command line flags win for a single run, which is handy when you only want to change the port.
Precedence¶
- Command line flags (
--transport,--host,--port,--path,--data-dir). - Environment variables (
ALHORNO_*). - Built-in defaults (stdio,
127.0.0.1,8000,/mcp).
Nothing else is consulted: no config file, no user directory, no ~/.config lookups. A container
and a laptop run the identical code path.
Environment variables¶
| Variable | Default | Accepted values | Meaning |
|---|---|---|---|
ALHORNO_TRANSPORT |
stdio |
stdio, streamable-http |
Transport to serve. |
ALHORNO_HOST |
127.0.0.1 |
Any interface | Interface the HTTP transport binds to. |
ALHORNO_PORT |
8000 |
1–65535 |
Port the HTTP transport binds to. |
ALHORNO_PATH |
/mcp |
Any path | Path of the MCP endpoint; a missing leading slash is added. |
ALHORNO_STATELESS_HTTP |
true |
boolean | Treat every HTTP request independently. |
ALHORNO_ALLOWED_HOSTS |
localhost only | comma-separated | Host headers accepted by the HTTP transport. |
ALHORNO_ALLOWED_ORIGINS |
empty | comma-separated | Origin headers accepted, for browser clients. |
ALHORNO_SITE_BASE_URL |
https://alhornoconpapa.com.ar |
absolute URL | Base URL used to build links back to the website. |
ALHORNO_LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING, ERROR, CRITICAL |
Log level. Logs always go to stderr. |
ALHORNO_DATA_DIR |
packaged data/ |
directory | Where recipes.json is read from. |
Booleans accept 1/0, true/false, yes/no and on/off, case-insensitively. An invalid value
fails at startup with an explanatory message and exit code 1; the server never falls back to a
surprising default.
Host allowlist¶
The HTTP transport enables DNS-rebinding protection. A request whose Host header is not in the
list is rejected with 421 Misdirected Request, before any MCP handling.
The default list is:
The :* entries accept any port, which is what a local localhost:8000 request sends. In
production, append the public hostname. Behind Caddy, the proxied request keeps the original
Host, so the public name is the one you need:
Stateless HTTP¶
With ALHORNO_STATELESS_HTTP=true (the default) the server creates no session state between
requests: a client may call tools without an Mcp-Session-Id, and any instance can answer any
request. That makes horizontal scaling and restarts trivial, at the cost of server-initiated
notifications. Keep the default unless your client requires sessions.
Data directory¶
ALHORNO_DATA_DIR points at a directory holding recipes.json. Use it to test a candidate
snapshot without rebuilding the package:
The file is validated on load: duplicate ids or slugs, a missing required field or an oversized
payload stops the process with a SnapshotError instead of serving broken data.
Command line¶
alhorno-mcp [--version] <command> [options]
commands:
serve run the MCP server
sync download the upstream snapshot into the package
| Flag | Applies to | Meaning |
|---|---|---|
--transport |
serve |
stdio or streamable-http. |
--host |
serve |
Interface for the HTTP transport. |
--port |
serve |
Port for the HTTP transport, validated to 1–65535. |
--path |
serve |
Path of the MCP endpoint. |
--data-dir |
serve, sync |
Directory holding or receiving recipes.json. |
--url |
sync |
Upstream JSON URL; defaults to the website repository. |
--check |
sync |
Compare the stored snapshot with upstream without writing. |
Examples¶
Local host, stdio¶
Nothing to configure: this is the default.
Public HTTP service¶
ALHORNO_TRANSPORT=streamable-http \
ALHORNO_HOST=0.0.0.0 \
ALHORNO_PORT=8000 \
ALHORNO_ALLOWED_HOSTS="localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.alhornoconpapa.com.ar" \
alhorno-mcp serve
Docker Compose¶
docker-compose.yml reads the repository's .env file. Copy the template and edit the hostname:
Every variable in the table above can live in that file. Values are passed to the container
unchanged, so the same names work in a docker run -e invocation.
Debugging¶
Each tool call logs one line with its name, duration and outcome (for example
search_recipes 12 ms, 7 results). Logs go to stderr so they never corrupt a stdio MCP stream.