AI Clients: Ask Claude, Codex, Cursor, or Gemini

Connect Claude Code, Codex, Cursor, Gemini CLI, or any MCP client to your self-hosted Fusionaly. Ask about your traffic in plain English. Read-only, and your data stays on your server.

Ask “Where did my traffic come from this week?” in the AI client you already use. The client asks your Fusionaly server and answers with your real numbers.

Fusionaly has a Model Context Protocol (MCP) server built in, at /mcp on your own domain. The Fusionaly plugin connects your client to it and adds a skill that turns questions into the right queries.

How it works

You ask your client a question, for example “Which pages drive signups?”.
The client calls the Fusionaly tools on your server.
Fusionaly runs a read-only query on its SQLite database and returns the rows.
The client answers in plain English: a verdict, the numbers, and whether you need to act.

Fusionaly itself never calls an AI provider. Your client sends the question and the results to the model you chose in that client. Nothing else leaves your server.

Tools

Tool	What it does
`list_websites`	Your websites and their ids
`whats_new`	What changed: traffic spikes and drops against the usual day, new referrers, goal spikes, trending pages, milestones
`get_schema`	The analytics tables, and how to query them
`query`	One read-only SQL query, up to 1000 rows

No tool writes. The tools read the analytics tables only. They can’t read user accounts, settings, or keys.

Before you start

You need two values:

Your Fusionaly URL, for example https://data.yoursite.com.
An agent key. In Fusionaly, go to Administration > Agents and select Generate API Key. The key is read-only.

The same page shows your MCP URL and the install command for each client.

Connect your client

Claude Code

Type these commands one at a time:

/plugin marketplace add karloscodes/fusionaly-oss
/plugin install fusionaly
/fusionaly:connect

/fusionaly:connect asks for the URL and the key and verifies them against your server. Restart Claude Code. Then /mcp lists the fusionaly server.

Codex

codex plugin marketplace add karloscodes/fusionaly-oss
codex plugin add fusionaly@fusionaly

Then ask Codex to “connect Fusionaly”. It verifies the URL and the key, and adds the server:

codex mcp add fusionaly --url https://data.yoursite.com/mcp --bearer-token-env-var FUSIONALY_AGENT_KEY

Gemini CLI

gemini extensions install https://github.com/karloscodes/fusionaly-oss

The install asks for the URL and the key. To change them later, run gemini extensions config fusionaly.

Cursor

Import the plugin from Dashboard > Plugins > Add Marketplace > Import from Repo with karloscodes/fusionaly-oss. Then ask the agent to “connect Fusionaly”.

To add the server by hand, edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fusionaly": {
      "url": "https://data.yoursite.com/mcp",
      "headers": { "Authorization": "Bearer ${env:FUSIONALY_AGENT_KEY}" }
    }
  }
}

Claude Desktop, VS Code, and other clients

Every MCP client takes a URL with an Authorization: Bearer <key> header, or a local command. The plugin README has the exact config for each client.

Keep the key out of config files

The setups above read the key from the FUSIONALY_AGENT_KEY environment variable. Put the variable in a file that git does not track, or in your secret manager. Do not commit a file that holds the key. Many people keep their shell profile and editor settings in a dotfiles repo, and a key in that repo is public.

To change the key, go to Administration > Agents and select Regenerate. The old key stops working at once.

What you can ask

“How is my traffic this week compared to last week?”
“Where do my visitors come from?”
“Which pages drive signups?”
“Why did visitors drop on Tuesday?”
“What day of the week gets the most visits?”
“What changed on my websites this month?”

Without MCP: the SQL API

Scripts and clients without MCP support use the same key over HTTP.

Get the schema:

curl -s -H "Authorization: Bearer $FUSIONALY_AGENT_KEY" \
  "https://data.yoursite.com/z/api/v1/schema"

Run a query:

curl -s -X POST "https://data.yoursite.com/z/api/v1/sql" \
  -H "Authorization: Bearer $FUSIONALY_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT DATE(hour) AS day, SUM(visitors) AS visitors FROM site_stats WHERE website_id = 1 GROUP BY day ORDER BY day DESC LIMIT 7"}'

Limits

One SELECT or WITH statement per query. No comments.
At most 1000 rows per result. The response sets truncated when a query hits the cap.
Each query can run for 5 seconds.
30 requests per minute for the MCP server and the SQL API together.

If it does not connect

Problem	Fix
`404` on `/mcp`	Your server is older than v2.3.0. Update it: run the install line again, or `sudo fusionaly update` on a server of the older installer.
`401`	The key is wrong, or you did not generate one. Get it from Administration > Agents.
No tools appear	Most clients read MCP config only at startup. Restart the client.
The server appears, but it has no tools	The URL or the key did not resolve. Run the connect step again: `/fusionaly:connect` in Claude Code, or “connect Fusionaly” in other clients.

Ask AI in the dashboard

Earlier versions had Ask AI, which ran in the dashboard with your own OpenRouter key. From v2.3.0 it is hidden, because your AI client now does the same job without a separate key. The page still works. To show it again in one browser, open the browser console and run:

localStorage.setItem("fusionaly:lens", "on")