Troubleshooting

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.

New tools aren't showing up

We ship new tools regularly. Your client caches the tool list when it connects, not per chat — so a brand-new tool won't appear, even in a fresh conversation, until the client re-fetches the list. Starting a new chat does not force this. Reconnect the server once and the new tools appear:

• Claude (web / desktop app): open Settings → Connectors, find AIclicks, and toggle it off then on (or remove and re-add it). Reopen your chat — the new tools are now listed.
• Claude Code: run claude mcp remove aiclicks then re-add it with claude mcp add, or just restart Claude Code. Confirm with claude mcp list.
• Cursor / other clients: disable and re-enable the AIclicks MCP server in the client's MCP settings, or restart the client.

Existing tools always run the latest server code the moment we deploy — a reconnect is only needed to pick up newly added tools.

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:

1. Call list_domains first — only pass domain_id values from that list.
2. 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.