Developer troubleshooting
Fix MCP, forms, renderer, and export integration issues.
Use this page when an integration fails. Start by separating authentication, site targeting, transport, and product-state problems.
MCP auth fails
Confirm the endpoint is https://app.miniagency.ai/api/mcp and the request uses Authorization: Bearer with a personal token that starts with miniagency_mcp_. If initialize works but tools/list fails, the client completed the handshake without authenticated calls.
Create a new token if the token was copied once and lost. Mini Agency stores only a hash and cannot reveal the plaintext again.
tools/list works but tools/call fails
Read the JSON-RPC error. Common causes are unknown tool name, missing required arguments, strict schema mismatch, admin-only tool, or a tool that requires user identity. Generated reference pages show each tool schema.
The active-site rule blocks a call
Pass _site with workspace-slug/site-slug. If using a header, use x-paper3-site with the same value. Confirm the token user is a member of that workspace. Agency users should never rely on implicit active site state.
Forms fail cross-origin
Test from the final domain. Confirm the form has the required data attributes, the site and form IDs are correct, and the server accepts the origin. Check browser console and network response body for validation errors.
Renderer route returns 404
Confirm the workspace slug, site slug, page slug, and publish state. For CMS item routes, confirm the item slug exists and the single-template page is bound to the collection.
Static export misses content
Check whether the missing route is dynamic CMS content, an asset path, or server-backed behavior. Re-run export after publishing or preparing the target state, then inspect the generated route list.