Skip to content

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

  1. Command line flags (--transport, --host, --port, --path, --data-dir).
  2. Environment variables (ALHORNO_*).
  3. 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:

localhost,localhost:*,127.0.0.1,127.0.0.1:*,[::1],[::1]:*

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:

ALHORNO_ALLOWED_HOSTS="localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.alhornoconpapa.com.ar"

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:

ALHORNO_DATA_DIR=/tmp/candidate uv run alhorno-mcp serve --transport streamable-http

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.

alhorno-mcp serve

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:

cp .env.example .env
docker compose up -d
docker compose logs -f mcp

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

ALHORNO_LOG_LEVEL=DEBUG alhorno-mcp serve --transport streamable-http

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.