Clicky MCP server setup (for AI agents)

Clicky runs a hosted MCP server at:

https://clicky.com/mcp

Connecting it lets a compatible agent read your Clicky analytics directly. It exposes two tools that mirror the public API: sites (your websites and their keys) and analytics (every report the dashboard has) -- both return markdown tables by default, the cheapest format for the agent's context (pass output=json if the agent wants JSON). It is read-only, and it deliberately uses a simple static token instead of OAuth: your userkey, sent as a bearer token, or (for clients that can't send headers) as a ?userkey= parameter on the URL.

Supporting clients (Claude, Claude Code, Cursor) also get slash commands from the server's prompts: /clicky (a one-shot orientation so a cold session knows the drill), /clicky-install, and /clicky-help (a segmentation cookbook). And resources give agents ambient context without a tool call: clicky://sites (your site list, readable as-is) and a clicky://analytics/{site_id}/{type}/{date} report template.

You get the userkey from /user/edit (you generate it there once, then copy it; anyone who holds it can read your stats, so treat it like a password). Substitute it for YOUR-USERKEY below.

Tool calls hit the same server-side cache as the underlying API: 60 seconds of freshness on premium accounts (including trial), 15 minutes on free. Repeated identical calls inside that window return identical results even if new traffic just landed, so don't poll faster than that.

The analytics tool takes a filter in two forms: a plain word to match within a report, or -- if the value contains = -- a query tail appended to the underlying API call as-is, which is how you segment by visitor attributes: country=us&href=%2Fpricing. Anything going into that tail must be URL-encoded (values with &, = or spaces in them); most clients encode tool arguments for you, but if the agent builds the string itself it has to encode it.

Claude (claude.ai and Claude Desktop)

Claude connects to remote MCP servers through connectors. Open Settings → Connectors (on Desktop: Settings → Developer tools / Connectors), add a custom connector, and set:

  • URL: https://clicky.com/mcp
  • Authentication: the option for a fixed header / API key (not OAuth), with the header Authorization and the value Bearer YOUR-USERKEY. Claude sends the value exactly as you type it, so include the word Bearer.


If Claude shows a sign-in (OAuth) window instead of accepting the header, it decided the server wants OAuth and gave up on the token; that's a client-side quirk, not the server. Remove and re-add the connector, keeping the header auth selected.

Claude Code

claude mcp add --transport http clicky https://clicky.com/mcp \
  --header "Authorization: Bearer YOUR-USERKEY"

Or the project-scoped equivalent in .mcp.json (note the "type": "http" field, which Claude Code requires):
{
  "mcpServers": {
    "clicky": {
      "type": "http",
      "url": "https://clicky.com/mcp",
      "headers": { "Authorization": "Bearer YOUR-USERKEY" }
    }
  }
}

ChatGPT

ChatGPT on the web connects to custom MCP servers with OAuth or no authentication, and has no field for a static bearer token. No problem: put the userkey in the URL instead. In Settings → Connectors (or Plugins, plus-button, Add custom MCP server), use:
  • Server URL: https://clicky.com/mcp?userkey=YOUR-USERKEY
  • Authentication: No authentication (the key rides in the URL)

Caveat: that URL is your key in plain text. Anything that sees the URL sees the key (ChatGPT stores it in the connector config, and it lands in server logs). Don't paste that URL anywhere public, and prefer the bearer-header setups above in any client that supports them.

The ChatGPT desktop app / Codex instead read MCP servers from ~/.codex/config.toml and can send a proper bearer token from an environment variable:
[mcp_servers.clicky]
url = "https://clicky.com/mcp"
bearer_token_env_var = "YOUR-USERKEY"

Any other client that can't set headers: use the same ?userkey= trick in its server-URL field. Or skip MCP entirely and use the plain HTTP API walkthrough, which answers the same questions.

Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally), via Settings → MCP Tools → Add Custom MCP:
{
  "mcpServers": {
    "clicky": {
      "url": "https://clicky.com/mcp",
      "headers": { "Authorization": "Bearer YOUR-USERKEY" }
    }
  }
}

Troubleshooting

  • "Needs authentication" or 401 in the client: the token is missing or wrong. Check the header is Authorization: Bearer YOUR-USERKEY (one space, word Bearer included, no quotes), or that the ?userkey= URL param made it into the server URL, and that the key came from /user/edit. A per-site sitekey in either slot will 401 too; the MCP server only accepts the account userkey. After 15-ish failed attempts the key locks out for 15 minutes; fix the config before retrying.
  • Tools list loads but calls fail: the server is fine, the parameters aren't. The tools are thin pass-throughs to the API; see the API docs for the exact parameters, and limits for what's read-only.
  • Nothing shows in the client at all: confirm the URL is exactly https://clicky.com/mcp (no trailing slash needed, no /sse).


The /mcp URL itself, opened in a browser, is a short setup page with the same instructions in condensed form. Everything about what the underlying API can answer: /help/api.


📢 Experience analytics the way they should be

Sign up for Clicky now and transform your analytics