MCP Troubleshooting
Common recovery paths for OAuth, paid-plan, permission, approval, and async generation issues.
Paid plan required
If a tool returns isError: true with code plan_required, the account is authenticated but not on a paid MCP-enabled plan.
- Open the billing action URL in the error response.
- Upgrade the account or use a paid test account.
- Retry connector authorization after the account state refreshes.
Insufficient scope
If a tool returns isError: true with code reauthorization_required or forbidden, the token is valid but the grant does not include the scopes required for that tool.
- Use mcp_permission_upgrade_request to summarize the scopes needed for the next tool or workflow.
- Authorize the returned requestedScopes in the existing MCP client; retain the connection and previously granted permissions. If the client cannot start incremental consent, use its authorization or reconnect action without revoking the existing connection.
- Retry with the new access token rather than the old token.
Async generation
Image generation and carousel workflows are asynchronous. Repeating the initial write tool can create duplicate work.
- Start N designs with ONE designgen_generate (operation "image") call: numImages for variations, prompts for up to 4 concepts.
- Then wait once: designgen_generation (operation "get") long-polls up to waitSeconds and takes generationIds for a batch. When the DesignGen proof sheet is showing it fills in by itself; do not poll or re-list its links.
- After carousel generation starts, use designgen_carousel (operation "wait").
- Use the nextCall fields returned by DesignGen instead of asking the user to poll manually.