Home

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:

• anonymous: safe public discovery and limited read-only access
• content.read: authenticated read tools
• content.write: content creation and update tools
• site.admin: build, validation, and all admin tools (system.admin is an alias)
• mcp: deprecated compatibility alias for content.read only

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

• AgentReady Pitfalls
• Pitfalls Index
• Pitfalls:
  • Pitfall invalid-scope disguised as 302 — 302 redirect hides invalid_scope error
  • Pitfall Claude auth callback vs oauth callback — wrong redirect URI path
  • Pitfall Redirect URI Exact Matching — exact vs wildcard URI rules
  • Pitfall OAuth Client Max Scope — scope clamping vs rejection
  • Pitfall Anonymous vs Authenticated Server — tool boundary between scopes
  • Pitfall openid-configuration 404 — ChatGPT OIDC probe returns 404 (expected)
  • Pitfall Release Tag Drift — release tag points behind verified main
• Live Deployment Runbook
• OAuth Clients and Scopes
• Scope and Tool Matrix
• Client Compatibility
• Release Checklist
• Discovery and RFC Map
• Documentation Source of Truth
• Smoke Tests and Live Verification
• Security Redaction Checklist
• Repository runbook: docs/agent-ready-howto.md
• Release smoke script: scripts/smoke-agent-interop.sh
• AgentReady preflight: scripts/check-agent-ready.sh

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-Proof-Client-Credential-Isolation — Using chatgpt-write credentials from Claude.ai is refused: redirect URI mismatch blocks cross-client token theft even when the secret is known.

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.