Deploy to a VPS¶
The reference deployment is a single small VPS running the container behind Caddy, which handles TLS. Nothing else is required: no database, no object storage, no queue, no secrets.
Target topology¶
client ──HTTPS──▶ Caddy (443) ──HTTP──▶ 127.0.0.1:8000 ──▶ alhorno-mcp container
│
└── automatic certificates for mcp.alhornoconpapa.com.ar
| Name | Serves | Hosting |
|---|---|---|
mcp.alhornoconpapa.com.ar |
MCP endpoint /mcp, health /health |
VPS + Caddy |
docs.mcp.alhornoconpapa.com.ar |
this documentation | Cloudflare Pages |
1. DNS¶
Create an A record (and AAAA if the VPS has IPv6) for mcp.alhornoconpapa.com.ar pointing at
the VPS, and keep it DNS only: grey cloud, not proxied. Caddy terminates TLS for this hostname,
and a proxied record puts Cloudflare in front of it, so long-lived MCP responses then depend on the
proxy's buffering and idle timeouts instead of the container's.
The docs hostname needs no manual record when the zone is already on Cloudflare: adding
docs.mcp.alhornoconpapa.com.ar as a Pages custom domain creates the CNAME to
<project>.pages.dev in the same zone. On another DNS provider, create it manually.
Verify before asking for certificates:
2. Prepare the VPS¶
# Debian or Ubuntu
sudo apt update
sudo apt install -y docker.io docker-compose-v2 git curl ufw
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER" # log out and back in
Firewall: allow SSH, HTTP and HTTPS only.
Port 8000 stays closed: Caddy reaches the container over loopback.
3. Put the code on the box¶
sudo useradd --system --create-home --shell /usr/sbin/nologin alhorno
sudo mkdir -p /srv/alhorno
sudo chown alhorno:alhorno /srv/alhorno
sudo -u alhorno git clone https://github.com/FedeG/al_horno_con_papa_mcp.git /srv/alhorno/app
cd /srv/alhorno/app
sudo -u alhorno cp .env.example .env
Edit .env:
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_LOG_LEVEL=INFO
Bind the published port to loopback in docker-compose.yml:
Build and start:
sudo -u alhorno docker compose up -d --build
sudo -u alhorno docker compose ps
curl -fsS http://127.0.0.1:8000/health
4. Caddy¶
Install Caddy from the official repository, then edit /etc/caddy/Caddyfile:
mcp.alhornoconpapa.com.ar {
encode zstd gzip
# The MCP transport is stateless, but long-lived responses are normal.
reverse_proxy 127.0.0.1:8000 {
header_up Host {host}
flush_interval -1
}
log {
output file /var/log/caddy/mcp-access.log {
roll_size 10MiB
roll_keep 5
}
format json
}
}
Reload and check:
header_up Host {host} keeps the public hostname in the proxied request, which is what the
transport's allowlist checks. flush_interval -1 disables response buffering, so streamed MCP
responses are not delayed.
Verify the MCP handshake through TLS¶
curl -sS -X POST https://mcp.alhornoconpapa.com.ar/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
-o /dev/null -w '%{http_code}\n'
200 means DNS, TLS, Caddy and the allowlist all line up.
5. Run without Docker (optional)¶
If you prefer a plain process, install the wheel and use a systemd unit:
# /etc/systemd/system/alhorno-mcp.service
[Unit]
Description=alhorno-mcp
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=alhorno
Group=alhorno
Environment=ALHORNO_TRANSPORT=streamable-http
Environment=ALHORNO_HOST=127.0.0.1
Environment=ALHORNO_PORT=8000
Environment=ALHORNO_ALLOWED_HOSTS=localhost,localhost:*,127.0.0.1,127.0.0.1:*,mcp.alhornoconpapa.com.ar
ExecStart=/home/alhorno/.local/bin/alhorno-mcp serve
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/alhorno
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now alhorno-mcp
sudo systemctl status alhorno-mcp
The service binds to loopback, so Caddy keeps doing TLS exactly as before.
6. Publish the documentation¶
Cloudflare Pages builds and serves the docs site, connected directly to the GitHub repository.
GitHub Actions only checks work: it regenerates requirements-docs.txt, runs
mkdocs build --strict, and never deploys.
Create the Pages project once:
- Workers & Pages → Create application → Pages → Import an existing Git repository, pick the repository, and use these settings:
| Setting | Value |
|---|---|
| Production branch | main |
| Build command | pip install -r requirements-docs.txt && mkdocs build --strict |
| Build directory | site |
- Add two environment variables under Settings → Environment variables:
| Variable | Value |
|---|---|
PYTHON_VERSION |
3.12 |
NO_MKDOCS_2_WARNING |
1 |
-
Under Custom domains, add
docs.mcp.alhornoconpapa.com.arand let Cloudflare create the record and the certificate. -
Every push to
mainrebuilds the site, and every pull request gets a preview URL.
requirements-docs.txt is generated from uv.lock, so Pages installs exactly the versions CI
tests against:
CI fails when the file drifts from the lockfile, so regenerate and commit it whenever the docs dependencies change.
Two details matter on a fresh project. There is no requirements.txt, so the automatic dependency
install finds nothing and the build command has to install the file itself. And the Markdown build
reads CHANGELOG.md from the repository root through pymdownx.snippets, so the build has to run
with the repository root as its working directory, which is the default.
The build also writes robots.txt, sitemap.xml (from MkDocs, with the 404 page excluded),
llms.txt, llms-full.txt and a Markdown copy of every page, so both crawlers and LLMs can read
the documentation without HTML.
7. Weekly routine¶
New recipes appear weekly. Recipes are immutable; only tags and relations change.
cd /srv/alhorno/app
sudo -u alhorno uv run alhorno-mcp sync --check # exit 1 means upstream changed
sudo -u alhorno uv run alhorno-mcp sync
git diff --stat src/alhorno_mcp/data/recipes.json
Commit the refreshed snapshot, then roll it out:
If you mount the snapshot instead, replace the file in the volume and restart the container: the snapshot is read once at startup.
Monitoring and rollback¶
- Health: poll
GET /healthfrom an external monitor. It returns the version and the number of recipes, so a truncated snapshot is visible immediately. - Logs:
docker compose logs -f mcpfor tool calls,/var/log/caddy/mcp-access.logfor HTTP status codes. Tool errors are visible in the response, not the log, by design. - Rollback:
git checkout <previous-tag> && docker compose up -d --build. The image is self-contained, so a rollback is one command and needs no data migration.
Abuse and rate limiting¶
The endpoint is public and read-only, with no authentication and no per-caller state. A simple
limit/offset paging contract keeps responses small, but nothing prevents a client from calling
it in a loop. If that becomes a problem, put the hostname behind a proxy with a request-rate rule
(Cloudflare, or Caddy with a rate-limit plugin) rather than adding tokens to this server: the data
is public anyway, so the goal is availability, not secrecy.