TL;DR

The Cloudflare plugin in hugo-mcp v2.0 implements 3 cache purge modes (full, partial, smart). The partial mode computes the linked URLs to invalidate (canonical + sitemap + RSS + listing + home) to preserve 95% of the CDN cache on every modification. Concretely: 6 URLs purged instead of wiping everything. This post details the computation, the pitfalls, and why smart became the default.

TL;DR

hugo-mcp v2.0.0 introduces a Python plugin-system that lets anyone add hooks after each create_page / update_page / delete_page operation. 200 lines of code for the core, 3 production plugins shipped (IndexNow, Google Indexing, Cloudflare). This post explains the design, the trade-offs, the security posture, and shows how to write your own plugin in 5 minutes.

TL;DR

On May 9, 2026, I delivered all 10 chantiers of the MCP security sprint that I had announced earlier in the day in a single marathon session. hugo-mcp is now at v1.9.0 (GitHub Release), commit 1404f83 GPG-signed.

Here’s the high-level recap + a pedagogical deep-dive on 2 chantiers with real value beyond my specific context: C2 token rotation and C6 internal TLS.

Recap of 10 chantiers

Full details in the CHANGELOG v1.9.0 and commit 1404f83.

Status: ✅ DELIVERED — sprint closed on May 9, 2026

Update May 9, 2026 (end of session): all 10 chantiers delivered in a single marathon session, and all 3 coordinated releases published the same day (hugo-mcp v1.9.0, mcp-oauth-proxy v2.1.0, mcp-installer v1.3.0). Every component of the MCP ecosystem hardened in one day. Full technical recap: MCP security sprint delivered: v1.9.0, 10 chantiers, hardened ecosystem.

This page stays published as an archive — to show the trajectory of an announced sprint, then kept. All original content below is preserved.

Original status (pre-delivery)

This page publicly documented an ongoing hardening sprint on arleo.eu’s MCP infrastructure. For security reasons, specific details of each chantier were not exposed until fixes were delivered (“sec-first” philosophy: don’t publish an attack roadmap).

Why this transparency

I debated whether to publish this page. Arguments for transparency:

• Public commitment = healthy pressure on yourself to deliver
• Documentation of a homelab whose goal is to learn and share
• Honesty with readers consuming other technical articles

Arguments against:

• Attack roadmap: if I precisely list what’s not yet protected, I give clues to a patient attacker
• Artificial pressure: announcing a sprint then not delivering = worse than announcing nothing

Adopted compromise: publish the direction and hardening domains without specifying what’s weak today. Specific technical detail published on delivery.

Sprint scope

The sprint covered 10 chantiers grouped into 4 domains:

1. Application hardening (FastAPI + Pydantic)

Reinforcement of MCP entry layers: strict input validation, unified error handling, no information leak in responses (stack traces, internal paths, lib versions).

2. Authentication and tokens

Refactor of MCP access token management: lifetime, rotation, revocation, hashing in storage. Allow cutting off a compromised client’s access without redeploying the service.

3. Observability and audit

Integration of JSON structured logs ingested in BetterStack via Vector. Each MCP call must produce a traceable event: who, what, when, duration, status. Enables anomaly detection in near real-time.

4. Infrastructure and resilience

TLS for internal traffic between NUC and VM, dedicated ModSec rules on the /mcp path, disaster recovery runbook (token theft, server compromise, data loss).

What was already in place before the sprint

To not create false impressions, here are the layers already in place on infrastructure before the sprint (so out of scope):

• nginx + mandatory TLS 1.3 (Mozilla Modern config)
• Cloudflare WAF + Bot Management + IP whitelist
• ModSecurity + OWASP CRS 4.x on all vhosts
• CrowdSec in WAF mode + Cloudflare bouncer
• systemd hardening at level 1.7 (cf. systemd hardening)
• HMAC validation on webhooks
• Frontmatter Pydantic validation (1 chantier of 4 in the validation category)

The sprint aimed to complete this base, not replace it.

Method

For each chantier:

1. Implemented locally + unit tests
2. Validated on mcp-test-vm (pre-prod VM)
3. Deployed to prod only after passing tests
4. Structured JSON audit log for deployment traceability
5. Post-mortem or technical write-up published after delivery

No direct prod deployment without pre-prod step.

Published releases

Status: 🗂️ BACKLOG — not yet implemented

This page documents an architectural intent to be implemented in a future iteration. The code is not yet in production.

Context

In Strategy 4 (separating MCP / Git), I explained why content/ is in .gitignore on the arleo.eu repo: so that no conflict is possible between MCP writes and Git writes.

Concretely, this means that when I push a new version of layouts/, themes/, static/, hugo.toml, or deploy.sh from VS Code, nothing happens automatically server-side. I have to SSH into the Hugo VM and manually run git pull && hugo --minify && rsync.

Not critical (structure pushes happen ~1× per week), but it’s unnecessary friction. So: GitHub webhook → auto-rebuild.

Target architecture

The symptom

I just finished a webhook endpoint in hugo-mcp-proxy that will receive notifications from GitHub on every push to the arleo.eu repo. Clean implementation: HMAC-SHA256, rate limiting, IPAddressAllow GitHub ranges in systemd.

Functional test from an external client:

$ curl -X POST https://mcp-hugo.arleo.eu/webhook/test \
    -H "Content-Type: application/json" \
    -d '{"test": true}'

Response: 403 Forbidden.

Strange. The service is running, my source IP is whitelisted, the HMAC is correct. Why 403?

Server-side investigation

NUC nginx logs:

$ sudo tail -100 /var/log/nginx/mcp-hugo.access.log | grep webhook

Empty. No request reaches nginx.

mcp-oauth-proxy logs:

$ sudo journalctl -u mcp-oauth-proxy -n 100 | grep webhook

Empty too. The request doesn’t even reach the service.

Either it’s blocked by the firewall before nginx (CrowdSec or ufw), or upstream by Cloudflare.

The truth at Cloudflare

The bug

mcp-installer is a bash script I wrote to automate the installation of mcp-oauth-proxy (FastAPI + nginx + systemd) on a new host. Standard workflow: clone, run, done.

Except when re-running the script on an already installed host (e.g. to update the version), I discovered an idempotence bug: all secrets were regenerated.

$ sudo ./install.sh
[+] Generating MCP_TOKEN...
[+] Generating CLIENT_ID...
[+] Generating CLIENT_SECRET...
[+] Generating TOKEN_SECRET...
[+] Writing /etc/mcp-oauth-proxy/.env...

If you already have a .env with tokens in service, the installer overwrites them. All already-registered OAuth clients (Claude.ai in my case) end up with invalid credentials. Connection breaks.

Why it happened

The script used this logic:

MCP_TOKEN=$(openssl rand -hex 32)
CLIENT_ID=$(openssl rand -hex 16)
CLIENT_SECRET=$(openssl rand -hex 32)
TOKEN_SECRET=$(openssl rand -hex 32)

cat > /etc/mcp-oauth-proxy/.env <<EOF
MCP_TOKEN=$MCP_TOKEN
CLIENT_ID=$CLIENT_ID
CLIENT_SECRET=$CLIENT_SECRET
TOKEN_SECRET=$TOKEN_SECRET
EOF

The “generate then write” pattern is correct for first install. But on rerun, it completely ignores the existing .env.

It’s the classic mistake: the author (me) tested the script only on a fresh host. The “reinstall on existing host” mode was never tested.

Bug reproduction

$ sudo ./install.sh
[OK] Installation complete
$ cat /etc/mcp-oauth-proxy/.env | head -1
MCP_TOKEN=a7f3e9d2c4b8a1...

$ sudo ./install.sh
[OK] Installation complete
$ cat /etc/mcp-oauth-proxy/.env | head -1
MCP_TOKEN=8c2f6a1b9e4d7c...   ← DIFFERENT

Reproducible test in 30 seconds. Almost comical I didn’t catch it sooner.

The lesson: “idempotent” is a contract, not a hope

An installation script must be idempotent by default. Meaning: ./install.sh once, twice, five times → system in the same stable state.

I had this contract in my head. I didn’t have it in the code.

The fix: pre-flight checks + explicit force flag

Context

I deployed a Hugo MCP Server (FastAPI, 7 tools) that lets me edit arleo.eu from Claude.ai. Architecture: claude.ai → mcp-oauth-proxy NUC → hugo-mcp-proxy NUC → MCP server VM.

The problem

You have a Hugo site. You want to:

1. Edit content via Claude.ai (publish an article, fix a typo, update a draft) without touching an SSH terminal.
2. Version the structure (layouts, themes, hugo.toml, deploy scripts) in Git, like a serious dev.

First instinct: “everything in Git”. Articles too. The MCP commits, pushes, GitHub webhook triggers a rebuild. Clean, GitOps-philosophy.

Except it doesn’t work that well. Here’s why, and the simple solution I call Strategy 4.

Why “everything in Git” breaks in practice

Imagine your MCP git commits on every create_page. Naive strategy, often suggested. Here are the problems:

Problem 1 — MCP ↔ Git conflict

You push a new layout from your laptop (layouts/index.html modified). At the same time, the MCP is committing a new article version. Race condition: the MCP might git pull --rebase and fail, or worse, overwrite your local commit.

Problem 2 — MCP’s Git identity

Whose commits is the MCP making? With which GPG key? If you have a “signed commits required” policy, the MCP needs to manage a GPG key, which has to be secured, rotated, etc.

Problem 3 — Unwanted auto-commits

You’re testing, you create a draft article to experiment, you delete it. But the MCP already committed. Now you have a “wip test” commit in history, to rebase or squash manually.

Problem 4 — Asymmetric reversibility

A git revert repo-side has no effect on files the MCP already created. You end up with a desynchronized repo and filesystem state.

Strategy 4: separate the zones

The idea: MCP and Git never write to the same files.

Repo-side .gitignore:

content/
public/
resources/

Implications:

• The MCP can write to content/ whenever. No Git conflict possible.
• You can git reset --hard repo-side with confidence — content/ stays intact.
• No need for the MCP to manage a Git identity.
• No “commit pollution”.

Trade-off: no content versioning

You lose Git versioning of content. That’s a real loss:

• No git blame on an article to see who wrote what.
• No git log content/csp-nonce/index.fr.md for history.
• No PR review for articles.

Mitigation: VM snapshots + daily encrypted content/ backup to QNAP. That covers disaster recovery, but not fine-grained versioning (who-changed-what-when).

For my personal homelab (single author, technical articles, no editorial validation workflow), it’s an acceptable trade-off. For a 10-contributor team blog, I’d reconsider.

Final architecture

⚡ In short

Connect Claude.ai to a Hugo site hosted in a KVM VM in 30 minutes: a FastAPI server exposes 6 MCP tools (read, create, modify, delete pages, rebuild the site) via JSON-RPC 2.0, an OAuth proxy reuses existing infrastructure, and every modification automatically triggers a Hugo rebuild + Cloudflare cache purge.

The code is available on GitHub:

• 🔌 Hugo MCP Server: jmrGrav/hugo-mcp
• 🔐 OAuth Proxy: jmrGrav/mcp-oauth-proxy

🧠 Why

Anthropic’s MCP (Model Context Protocol) allows Claude.ai to connect to external data sources via standardized tools. Unlike Grav CMS which is dynamic (PHP), Hugo generates pure static HTML — making content management via MCP even more powerful: every modification is compiled and deployed instantly.