Troubleshooting

Use this page when an AI client cannot connect to QUIQQER or MCP tools are missing.

Authentication Fails

Check:

• The token belongs to the intended QUIQQER user.
• The token was not deleted or rotated.
• The client sends the token as Authorization: Bearer <token>.
• The MCP endpoint URL points to the correct installation and ends with /mcp.
• The installation has quiqqer/ai-mcp installed.

Do not debug by pasting the token into a chat or public log. Use local logs and redacted values.

Tools Are Missing

Check:

• The package that provides the tools is installed.
• The package registered an MCP provider.
• The AI user has the required MCP permission.
• The AI user has normal QUIQQER permissions for the target area.
• Caches were refreshed after installing or updating packages.

For core project, site, media, and cache tools, the user needs Can use the core MCP tools (quiqqer.core.mcp.canUse). Cache clearing also needs Can clear the QUIQQER cache via MCP (quiqqer.core.mcp.clearCache).

For Bricks tools, the user needs Can edit bricks via MCP (quiqqer.bricks.mcp) and the relevant Bricks permissions.

Permission Errors

Permission errors usually mean the token is valid, but the QUIQQER user is not allowed to perform the action.

Check both layers:

• MCP permission, for example Can use the core MCP tools (quiqqer.core.mcp.canUse).
• Normal domain permission, for example project, site, media, or Bricks permissions.

Grant rights to a dedicated AI group instead of editing many individual users.

Wrong Project Or Language

QUIQQER projects can have multiple languages. A tool call can read or write the wrong content when the project or language is missing or incorrect.

Check:

• The project name is correct.
• The language value is correct.
• The site ID belongs to the selected project and language.
• The AI client read the target site before writing.

Use project and site read tools as the first step in any write workflow.

Token Was Exposed

If a token was pasted into a prompt, chat, ticket, log, or screenshot:

1. Delete or revoke the token.
2. Create a new token if the workflow still needs access.
3. Update the local client configuration.
4. Review recent actions by the token owner account.
5. Reduce permissions if the account had broader access than required.