Troubleshooting

The errors below come back as JSON inside the tool response, so your agent usually reads them to you verbatim. Here is what they mean and what to do.

Connection and authentication

The client cannot connect at all. Check the URL character for character:

https://kafkai.com/mcp

The path ends in /server. The client must support the MCP streamable HTTP transport — stdio-only clients cannot reach a remote server.

The sign-in page never appears (OAuth clients). Pop-up blockers are the usual cause. Allow the pop-up, or remove and re-add the connector to restart the flow.

Calls fail with an authorization error after working before. For OAuth clients: remove and re-add the connector to sign in again. For API tokens: the token was probably revoked — check the API tokens page and issue a new one if needed. Tokens are shown only once, so a lost token is replaced, not recovered.

"No Kafkai user found." The account you authenticated with does not exist on kafkai.com. Register first, then reconnect.

Credits

"No credit wallet found" or "Insufficient credits." Your balance cannot cover the call. Check it (free) by asking the agent for your credit balance, then top up on the pricing page. Calls refused for balance reasons cost nothing.

Projects and data

"Project '…' not found." The project id is wrong or the project belongs to a different account. Ask the agent to list your Kafkai projects and use an id from that list.

Keyword tools return empty lists on a new project. Research runs in the background and takes a few minutes after project creation. Ask for the project summary — while counts are still zero, the research has not finished. If a project stays empty for hours, contact support.

"Competitor '…' not found in this project." Ask the agent to list the project's competitors and use a domain from that list — the value must match the tracked domain, not an arbitrary URL.

The update was not queued. Only one ranking update per project runs at a time. Wait for the current one to finish; the keyword tools always serve the freshest completed data in the meantime.

kafkai_publish_article returns "Publishing failed". The destination refused the post, and the error carries its reason. Check the destination's URL and credentials with kafkai_list_publishing_destinations, fix the destination, then ask the agent to publish again.

Somewhere else entirely

If none of this matches what you see, contact support and include the tool name and the error text from the response. The _usage and error objects in tool responses carry no secrets, so they are safe to paste.