MCP Troubleshoot
Distinguish and mitigate authentication, permission, plan, and runtime business errors.
| Symptom or code | Action |
|---|---|
| Server unavailable | Check site URL and account rollout availability |
| 401 or invalid authorization | Sign in again; check removal, ban or revocation |
| 403 insufficient_scope | Grant mcp:write (required on Free as well as Pro) |
| error.booksQuotaExceeded | Library limit reached; upgrade or write into an existing library |
| STORAGE_QUOTA_EXCEEDED | Upgrade the workspace or delete unused assets |
| RESOURCE_NOT_FOUND | List IDs again in the target workspace and check removal |
| IDEMPOTENCY_CONFLICT | Arguments changed for a key; use a new key for a new operation |
| THREAD_CONFLICT | Reread and reconcile the draft before updating |
| UNSUPPORTED_CONTENT | Edit drafts with media or references on the website |
| RATE_LIMITED or 429 | Wait before retrying and retain creation keys |
| EXECUTION_TIMEOUT | Retry creation with the same arguments and key |
Start with whoami, then list_organizations. A missing workspace requires checking membership. Write tools are available on every plan; library, storage, and rate limits still apply.
Native clients may omit Origin. Invalid Origin, issuer, audience, expired tokens or invalid DPoP proofs are rejected. Browser cookies cannot authenticate MCP.
Revoke a client in MCP settings. New authorization does not revive old tokens. Give support the client version, request ID, error code and time. Remove tokens, cookies and private content.