Pitfalls Index

Pitfalls Index

This page groups the known operational pitfalls for mcp-hugo-server-go.

AgentReady and Discovery

• AgentReady Pitfalls
• Pitfall openid-configuration 404
• Pitfall Anonymous vs Authenticated Server

OAuth and Client Interop

• Pitfall invalid-scope disguised as 302
• Pitfall OAuth Client Max Scope
• Pitfall Redirect URI Exact Matching
• Pitfall Claude auth callback vs oauth callback

Release Process

• Pitfall Release Tag Drift

Current Scope Rule

Since #450, the server enforces exactly two canonical scopes:

read
write

write implies read, plus every tool that used to require a separate site.admin tier. Every other historical scope string (content.read, content.write, site.admin, system.admin, mcp, reader, admin, and more) is accepted only as a compatibility alias for one of the two — see Scope and Tool Matrix and docs/mcp-contract.md §6.12 for the full alias table.

If a page describes content.read/content.write/site.admin/system.admin as active standalone tiers (rather than legacy aliases), treat that as stale documentation and fix it.

Before Adding a New Pitfall

Each pitfall should include:

• symptom;
• root cause;
• exact reproduction or diagnostic command;
• fix;
• how to prevent recurrence;
• related issue or release link when available.

Do not include real tokens, client secrets, authorization codes, cookies, Cloudflare credentials, or private config dumps.