**Source:** https://heykiku.com/help/mcp-troubleshooting

# Troubleshoot MCP connections

Most MCP connection issues come from authentication, workspace access, or role permissions. Start with the error your client shows, then check the matching section below.

## The client says 401

A 401 means heykiku could not verify the Bearer credential.

Check:

- The API key is copied exactly and still starts with `kiku_live_`.
- The header is `Authorization: Bearer kiku_live_...`.
- The key has not expired or been revoked.
- For OAuth, the consent is still active and the token was issued for the heykiku MCP resource.

If you are using an API key, create a fresh `read` key and update the client. If you are using OAuth, disconnect heykiku in the client and connect again.

## The client connects but finds no results

MCP uses your current heykiku role. It only searches folders, documents, and libraries your role can see.

Check:

- The connected user is a member of the correct workspace.
- The documents are approved or otherwise visible to that role.
- The document access tier matches the user's role: freelancers see general, employees see general and internal, admins also see sensitive, and owners see owner-only.
- The client is asking the right workspace if you belong to more than one.

Use `whoami`, `list_folders`, or `list_libraries` to confirm what the client can access.

## The client says rate limited

`ask_kiku` uses the chat quota because it calls the workspace agent. Other MCP tools use the MCP request bucket. Wait for the reset, then retry with fewer repeated calls. See [rate limits and error codes](https://heykiku.com/help/api-rate-limits) for the current limits and headers.

## Authentication still looks wrong

Review [authentication and key management](https://heykiku.com/help/api-authentication). For a clean reset, revoke the old API key or OAuth connection, create a new `read` credential, and reconnect the client to `https://heykiku.com/api/mcp`.