Using your analytics
Ask about your store from the dashboard, Puddle AI, Claude, ChatGPT or any MCP client.
The same analytics, defined once in PQL, are available in three places. Every one of them only shows the stores you can access, and only to accounts with the View analytics permission.
| Where | Best for |
|---|---|
| Analytics dashboard | Day-to-day numbers: sales, customers, operations, website traffic |
| Puddle AI | Quick questions while you work in the admin |
| Claude, ChatGPT and other AI apps | Deeper analysis and reports in your own AI app |
Analytics dashboard
Open Analytics in the admin. Every page uses the date range at the top right, and every number on it is a PQL query. You can rerun any of them in Puddle AI or Claude and get the same result.
| Page | What it shows | Compared with |
|---|---|---|
| Sales | Revenue, orders, average order value, discount usage, revenue per day/week/month, weekly totals, top products | Same dates last year |
| Customers | Active customers, first-time and returning buyers, repeat buyer rate, sign-ups, dormant accounts, top customers | Same dates last year |
| Operations | Orders waiting to be fulfilled, last 24 hours of orders, revenue split, delivery methods, delivery provinces, low stock | — |
| Website | Pageviews, visitors, visits, bounce rate, visit time, traffic trend, provinces, referrers, top pages, devices | The period just before |
Some definitions:
- Revenue is order totals including shipping, minus refunds, for placed orders.
- First-time buyers placed their first ever order in the selected dates. Returning buyers had ordered before.
- Orders waiting to be fulfilled and Low stock show the current state and ignore the date range.
- Website numbers follow standard web analytics definitions. A visit is a browsing session; a bounce is a visit with one pageview.
Puddle AI in the admin
Open Puddle AI from any admin page and ask in plain language. It looks up what it can measure, writes the PQL query and answers with the numbers, linking any products or customers it mentions.
Try:
- "How did revenue this month compare with last month?"
- "Which 10 products sold best in the last 90 days?"
- "Where does our website traffic come from?"
- "What's our conversion rate per week this quarter?"
- "Which products get lots of views but few sales?"
Puddle AI is read-only for analytics. It can't change orders, products or settings unless you approve a specific action.
Connect Claude, ChatGPT or another MCP client
Puddle has an MCP server, so AI apps that support custom connectors can query your store directly.
Server URL: https://api.puddle.co.za/mcp
In the admin, Settings → MCP Connection (needs the Manage settings permission) shows your server URL, step-by-step setup for Claude, Claude Code, Cursor, VS Code and Windsurf, and the apps you've connected. You can disconnect an app there at any time.
Claude
- In Claude, open Settings → Connectors → Add custom connector.
- Name it "Puddle" and paste the server URL. Leave the OAuth client ID and secret empty.
- Click Connect. You're sent to Puddle to sign in.
- Review the consent screen. Puddle asks for Store analytics (read-only), and may also ask for Offline access so you stay connected without signing in every hour. Click Allow.
- Back in Claude, enable the Puddle connector in a chat and ask a question.
ChatGPT
In ChatGPT, turn on developer mode, add a connector with the same server URL, and sign in to Puddle when prompted. Leave the OAuth client fields empty. If ChatGPT says it can't register with Puddle, see troubleshooting.
Other MCP clients
Any client that supports MCP over Streamable HTTP with OAuth works. The client discovers how to sign in from the server URL automatically. It needs to support Client ID Metadata Documents; see troubleshooting if it doesn't.
What the AI app can do
| Tool | What it does |
|---|---|
list_stores | Lists the stores you can view analytics for |
describe_analytics | Explains what can be measured (datasets, measures, dimensions) with examples |
query_analytics | Runs a PQL query |
get_comprehensive_analytics | A ready-made store overview |
get_revenue_comparison | Revenue by day, week or month compared with last year |
get_trending_products | Trending products |
If your account can access more than one store, say which store you mean ("for Coco Blue…"); the AI app can call list_stores to find the right one. The connection is read-only. It can never change your store.
Try:
- "Give me a summary of my store's performance this month compared with last year."
- "Which provinces order the most, and what's the average order value in each?"
- "Which marketing campaigns (UTM) brought the most visitors last month?"
- "Build a weekly table of orders, visits and conversion rate for the last quarter."
Troubleshooting
| Problem | What to do |
|---|---|
| "Couldn't register with Puddle's sign-in service … add an OAuth Client ID" | Your app couldn't find or use Puddle's sign-in details. Check the server URL ends in /mcp. If it persists, your app may not support Client ID Metadata Documents: ask the Puddle team to set up a client ID for it, and enter that in the connector settings. |
| Sign-in loops or "You don't have access" | Sign in with the admin account that belongs to the store, and check it has the View analytics permission. |
| "No accessible store 'x'" | The store slug isn't one you can access. Ask the AI app to run list_stores. |
| Website numbers are unavailable | Website analytics aren't connected for the store yet. Sales, customer and operations data still work. |
| "Query took longer than 10s" | Ask for a shorter date range or fewer breakdowns. |
To disconnect an AI app, use Settings → MCP Connection in the admin (this revokes its access), and remove the connector in the app.