# 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:

```text
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:

```bash
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:

```bash
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

```text
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.

```bash
alhorno-mcp serve
```

### Public HTTP service

```bash
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:

```bash
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

```bash
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.
