Troubleshooting

REST / public MCP (GET /mcp/…)

The public REST API serves page JSON and sitemaps. All errors are JSON with error.code and error.message.

• 404 — Page not found or not published. Only published pages are served and listed in the sitemap. Do not add the MCP meta tag until the page is published.
• 503 — Site disabled or suspended. Re-enable the site in the portal.
• 429 (rate limit) — Per-IP limit exceeded. Respect the Retry-After header and error.retry_after (seconds); do not retry immediately.
• 429 (bandwidth quota) — Same REST shape, message e.g. "Bandwidth quota exceeded for this site". Back off and retry after the next period.

See Integration for the meta tag and where to get MCP URLs.

Domain verification not completing

• Ensure the TXT record is on _mcp-verification.yourdomain.com (not the root domain).
• The value must be exactly mcp-verify=<your-token> with no extra spaces.
• DNS propagation can take 5-30 minutes (up to 48 hours in rare cases).
• Use dig TXT _mcp-verification.yourdomain.com to confirm the record exists.

Ingestion fails or returns 0 pages

• Check that the site's domain is verified (ingestion requires verification).
• Ensure the base_url is reachable and returns HTTP 200.
• For sitemap mode, verify that sitemap.xml exists and is valid XML.
• For crawl mode, ensure internal links are standard <a href> tags (JS-rendered links may not be followed).
• Check your ingestion quota — you may have reached the daily limit.

MCP endpoint returns errors

• 404 — The site slug may be incorrect. Check your site's MCP endpoint URL.
• 429 — Rate limit exceeded. Wait and retry, or check your plan's request quota.
• -32600 / -32601 — Invalid JSON-RPC request or unknown method. Verify your request format.
• X-Cache: BYPASS on every request — Caching may be disabled for error responses. Ensure underlying data is valid.

Pages not appearing in search results

• Check that ingestion completed successfully (status: "completed").
• Verify that the pages have "published" status in the Pages overview.
• Cached search results may be stale — try a slightly different query to get a fresh result.
• If pages were recently re-ingested, cache invalidation happens automatically but may take a moment.

UI shows unstyled or broken pages (deployment)

• Run npm ci && npm run build after every deployment.
• Ensure public/build/manifest.json exists and includes all entrypoints.
• If using a containerized deployment, include the build step in your CI/CD pipeline.