Troubleshooting

Common MCP connection and tool-call errors, and how to fix them.

Connection issues

`Server not connecting`

Confirm the URL is exactly https://mcp.aiclicks.io/mcp — the /mcp suffix matters.
Confirm the Authorization header is in the form Bearer ak_live_.... JWTs and any other key prefix will be rejected.
For Claude Desktop / mcp-remote, run npx --version to confirm Node.js + npx are on PATH.

`Server connects but no tools show up`

Confirm you're on a recent MCP client. The server uses streamable HTTP transport (current spec) — clients on plain SSE-only builds will not enumerate tools.
For Claude Code, run claude mcp list — the server should show Connected. If it shows Failed, re-run claude mcp add and double-check the header.

"Only team admins, co-admins, and editors can connect this team"

Connecting mints a connection key, which requires a manage role — same as creating an API key. Ask a team admin, or have your role upgraded in Settings → Team.

"API access is not enabled for this team"

The selected team's plan doesn't include API access. Pick a team that does, or contact support@aiclicks.io.

The Connect button does nothing / loops

Make sure the URL is exactly https://mcp.aiclicks.io/mcp and the Authorization header is blank (a stray header makes the client skip OAuth). If the flow stalled, the code may have expired (5-min window) — click Connect again.

Disconnect

Revoke the Claude (MCP) key under Settings → Developers.

Authentication errors

`Missing or malformed aiclicks API key`

The bearer token is missing or doesn't have the ak_live_ prefix. Re-issue the key from Settings → Developers in the dashboard and update your client config.

`domain_id not in caller scope`

The API key's allowed_domains list doesn't include the domain_id you passed. Two fixes:

Call list_domains first — only pass domain_id values from that list.
If a domain is missing, the user who created the API key needs to update their allowed-domains list in the dashboard.

Rate limits

`429 Too Many Requests`

You've exceeded 60 requests/minute on this key. The MCP server forwards the backend's rate limit verbatim — there's no separate MCP-layer budget.

Slow the assistant down (fewer parallel tool calls per turn).
Issue a second API key under the same team if you need a higher aggregate ceiling.

Tool-call errors

A specific tool returns `500`

Check the X-Request-Id header in the assistant's tool result and share it with support@aiclicks.io.
Try the same call against the underlying REST endpoint with curl — if it also returns 500, the issue is server-side, not MCP transport.

Results look stale

The MCP server inherits the backend's per-endpoint Redis cache (typically 30 minutes). Wait for the TTL or call again with a different window (days=7 vs days=30) to bypass.

Still stuck?

Email support@aiclicks.io with:

The client you're using (Claude Desktop, Cursor, …) and its version.
The exact tool call that failed.
The X-Request-Id from the response, if visible.

Was this page helpful?