API reference
Connect an AI assistant
Connect Claude, Claude Code, ChatGPT or Cursor to ProductLense’s MCP server: sign in from the assistant and ask about traffic, revenue and profit.
ProductLense runs an MCP (Model Context Protocol) server at https://api.productlense.app/api/mcp. An AI assistant connected to it can read your traffic, revenue and profit and answer questions such as "Which channel made the most profit last month?" with the same numbers as your dashboard. MCP, the Read API and the CLI need the Starter plan or above.
Connect with a sign-in (recommended)
Every client below finds the sign-in on its own. Its first call gets a 401 that points at ProductLense's OAuth metadata, the client registers itself, and ProductLense opens a consent page in your browser. There you pick the site the assistant reads by default and whether it may make changes. Nothing is pasted by hand, and no key sits in a config file.
- Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector, URL
https://api.productlense.app/api/mcp. - Claude Code:
claude mcp add --transport http productlense https://api.productlense.app/api/mcp, then/mcpto sign in. - ChatGPT: Settings → Connectors (developer mode) → Create, URL
https://api.productlense.app/api/mcp, authentication OAuth. Custom connectors depend on your ChatGPT plan. - Cursor: add the server to
~/.cursor/mcp.json, or.cursor/mcp.jsoninside a project:
{ "mcpServers": { "productlense": { "url": "https://api.productlense.app/api/mcp" } } }- Any other client that speaks Streamable HTTP and the MCP authorization specification: the same URL.
With a sign-in, the assistant can read every site in your account. Connected assistants are listed under Account → Connected apps in the dashboard. Disconnecting one there ends its access at once.
Connect with an API key (read only)
For a client without OAuth, or for a script, create a key with the read scope under the site's Settings → API keys (see Authentication and API keys) and send it as a header:
{ "mcpServers": { "productlense": { "url": "https://api.productlense.app/api/mcp", "headers": { "Authorization": "Bearer mk_live_…" } } } }A key reads one site and never sees the write tools. The key reads every report of its site, including revenue and customer rows, so keep it in the assistant's configuration, not in a chat message, and delete it in Settings → API keys when you stop using it.
What the assistant can read
| Tool | What it returns |
|---|---|
list_sites | The sites this connection can read, with id, name, hostnames and timezone |
get_overview | The overview numbers for a range: visitors, pageviews, signups, revenue, fees, spend, profit and more |
get_timeseries | One metric over time, by hour, day, week or month |
get_breakdown | Rows for one dimension, such as channel, source, campaign, page, country or device |
get_realtime | Visitors on the site right now |
get_profit_by_channel | Revenue, fees, spend, profit, CAC, ROAS and payback per channel, source, medium and campaign |
get_revenue | MRR, new, expansion and churned MRR, refunds, revenue, fees, net revenue, customers, ARPU and LTV |
list_customers | Paying customers with their first-touch channel |
get_revenue_retention | Net revenue retention cohorts by channel, source or campaign |
list_goals, list_funnels, get_funnel_results | Goals, funnels and the counts at each step |
list_visitors, get_visitor_journey | Recent visitors and one visitor's pages and events |
ask | A plain-language question answered through the same validated flow as Ask |
Every result includes method_url, a link to How ProductLense counts, so the assistant can cite how a number was computed. A tool for a report your plan does not include answers with an error naming the plan. Tools for features that have not shipped yet, such as raw events, notes and alerts, appear as those features ship.
The assistant sees what you would see in the dashboard, customer and visitor rows included. ProductLense's own AI features never send that data to an outside model; a connected assistant is your choice and runs under your account.
What the assistant can change
Only with a sign-in, only when you allowed changes on the consent page, and only for an owner or admin. The write tools are create_goal and create_funnel; note and alert tools follow their features. Each write first answers with a preview that changes nothing, and applies only when the assistant calls again with confirm: true after asking you. Each write carries an idempotency_key, so a retried call never writes twice. Writes run as you, through the dashboard's own validation and permission checks, and are limited to 60 an hour per connection.
Limits and security
- Reads are limited to 120 a minute per connection, like the Read API.
- Access tokens last an hour and refresh for up to 30 days. Only hashes of tokens and keys are stored.
- A connection stops working when you disconnect it, when you leave the account, or when the plan drops below Starter.
- The consent page shows the client's self-chosen name, marked as unverified, next to the host it will send the code to. Check both before approving.