MCP Authoring Surface Reference (for Content Agents)

The operational facts an agent needs when authoring wiki content through the MCP servers. The definitive tool registry is the live server (McpServerInitializer / KnowledgeMcpInitializer); verify counts there before editing docs that state them.

The two servers

Operational rules that bite

  1. Rate limit ~50 req/s per client (1-second sliding window; raised 5x from 10/s on 2026-08-08 — MCP_RATE_LIMIT_PER_CLIENT, global cap 500/s). Modest parallelism is fine now; a genuinely tight loop still 429s — back off ~1s on 429.
  2. Optimistic locking: update_page requires expectedContentHash from read_page. On drift you get {updated:false, currentHash, latestContent} — rebase and retry without a new read. Background processes (the structural spine maintaining hubs: frontmatter) can move the hash between your read and write; this is normal.
  3. Frontmatter merges: update_page metadata merges onto existing frontmatter — a one-field edit never wipes the rest; content (body) replaces wholesale and may be omitted for metadata-only edits.
  4. write_pages fails pages that already exist — use update_page for those; per-page results let you retry only failures.
  5. System pages refuse MCP writes (About, Main, LeftMenu, CSS/help pages); Main.md is generated from Main.pins.yaml and CI reverts hand-edits.
  6. type: runbook requires a structured runbook: block (when_to_use / steps / pitfalls) or validation rejects the page.
  7. Re-indexing is async — dense retrieval reflects a save after the embed queue drains; don't measure recall immediately after bulk edits.
  8. MCP access keys are DB-managed (admin UI), not config files.

The authoring loop in one line

Discover (list_*, search) → write (write_pages/update_page) → lint (verify_pages with retrieval_readiness+seo_readiness) → live-check (assemble_bundle) → optionally ping_search_engines (IndexNow; Google needs manual GSC).

See Also