Skip to content

Home

Jump to bottom
Jm Rohmer edited this page Jul 18, 2026 · 13 revisions

mcp-hugo-server-go Wiki

This wiki is the operational notebook for mcp-hugo-server-go, the canonical unified MCP server for the Arleo Hugo site.

The repository contains the Go MCP/OAuth server. The live public setup also depends on the Hugo VM, OpenResty vhosts, and static discovery files served by www.arleo.eu.

What This Repository Is For

mcp-hugo-server-go exposes a Hugo site through the Model Context Protocol with strict scope separation. Since #450, there are exactly two internal scopes:

  • anonymous: safe public discovery only (.well-known/*, auth.md, server card) — genuinely no auth required for these
  • read: full read tool set, including drafts — no client secret needed, obtained via self-serve OAuth registration; not the same as "no auth at all" on production (see correction below)
  • write: requires a registered OAuth client — implies read plus content creation/update/delete, build, validation, and every tool that used to require a separate admin tier

Correction (2026-07-18, #498). With OAuth enabled — production's actual config — /mcp challenges every request with no Authorization header at all, by deliberate design (RFC 6750 discovery), even for what would resolve to the anonymous/read tier. There is no genuinely bearerless path to any tool on /mcp in production; read is obtained via self-serve DCR + PKCE, not zero-auth access. See Pitfall Anonymous vs Authenticated Server for the full correction and live reproduction.

Older scope strings (content.read, content.write, site.admin, system.admin, mcp, and others) are accepted only as compatibility aliases for read/write — see Scope and Tool Matrix for the full alias table.

The server is intended to be compatible with:

  • Claude Desktop and Claude.ai remote MCP connectors
  • ChatGPT MCP/custom connector flows
  • OAuth/OIDC discovery
  • MCP server cards
  • IsItAgentReady Agent-Native discovery checks

Live Endpoints

Purpose URL
Public site https://www.arleo.eu
MCP endpoint https://mcp.arleo.eu/mcp
OAuth issuer https://mcp.arleo.eu
Authorization metadata https://mcp.arleo.eu/.well-known/oauth-authorization-server
Protected resource metadata https://mcp.arleo.eu/.well-known/oauth-protected-resource
MCP server card https://mcp.arleo.eu/.well-known/mcp/server-card.json
Auth guide https://www.arleo.eu/auth.md and https://mcp.arleo.eu/auth.md

Production Topology

The live setup uses two hostnames with different responsibilities:

  • www.arleo.eu is the Hugo site and static AgentReady discovery surface.
  • mcp.arleo.eu is the MCP/OAuth server.

Traffic path:

Cloudflare
  -> host OpenResty
    -> www.arleo.eu -> Hugo VM Nginx -> Hugo static files
    -> mcp.arleo.eu -> Hugo VM mcp-hugo-server-go service

The current reference config examples live in the repository:

  • docs/examples/agent-ready/openresty-www.arleo.eu.conf
  • docs/examples/agent-ready/openresty-mcp.arleo.eu.conf
  • docs/examples/agent-ready/nginx-hugo-vm.conf
  • docs/examples/agent-ready/static/auth.md
  • docs/examples/agent-ready/static/.well-known/oauth-protected-resource
  • docs/examples/agent-ready/static/llms.txt
  • docs/examples/agent-ready/static/robots.txt

Operational warning: do not leave backup copies of live OpenResty vhosts inside the active sites-enabled/* include path. A stale *.bak file there is still live config, not an inert backup.

Important Pages

Community and Contribution

Repository-level collaboration rules live in:

  • CONTRIBUTING.md
  • CODE_OF_CONDUCT.md
  • SECURITY.md

Expected contribution standard:

  • one issue or one coherent behavior change at a time;
  • proof-driven review comments;
  • no issue closure without tests, checks, or validated runtime evidence;
  • AI assistance allowed, but never as a substitute for proof.

Release Rule

Do not tag or release if any of these fail:

go test ./...
go test -race ./...
go vet ./...
staticcheck ./...
govulncheck ./...
gitleaks detect --no-banner --redact --source .
SMOKE_LIVE=1 ./scripts/check-agent-ready.sh
SMOKE_LIVE=1 ./scripts/smoke-agent-interop.sh

For AgentReady releases, also scan https://www.arleo.eu on IsItAgentReady and require API/Auth/MCP/Skill Discovery to stay at 7/7, unless the release explicitly documents why that external score changed.

Security Proofs

Live tests that demonstrate the security model works as intended:

Security Notes

  • Never publish OAuth client secrets, bearer tokens, Cloudflare tokens, or private host config containing credentials.
  • Docs and wiki pages must use redacted examples only.
  • Write/admin tools must never become anonymous.
  • Discovery can be public; authorization must still be enforced on both tools/list and tools/call.

Clone this wiki locally