Skip to content

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:

dig +short mcp.alhornoconpapa.com.ar
dig +short docs.mcp.alhornoconpapa.com.ar

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.

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

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:

services:
  mcp:
    ports:
      - "127.0.0.1:8000:8000"

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:

sudo systemctl reload caddy
curl -fsS https://mcp.alhornoconpapa.com.ar/health

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:

sudo -u alhorno uv tool install /srv/alhorno/app
# /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:

  1. 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
  1. Add two environment variables under Settings → Environment variables:
Variable Value
PYTHON_VERSION 3.12
NO_MKDOCS_2_WARNING 1
  1. Under Custom domains, add docs.mcp.alhornoconpapa.com.ar and let Cloudflare create the record and the certificate.

  2. Every push to main rebuilds 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:

uv export --only-group docs --no-emit-project --no-hashes --output-file requirements-docs.txt

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:

sudo -u alhorno docker compose up -d --build
curl -fsS https://mcp.alhornoconpapa.com.ar/health

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 /health from an external monitor. It returns the version and the number of recipes, so a truncated snapshot is visible immediately.
  • Logs: docker compose logs -f mcp for tool calls, /var/log/caddy/mcp-access.log for 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.