// docs / mcp
Connect an LLM to your analytics.
Abner exposes 27 tools for analytics, site management, API keys, account settings and billing over the Model Context Protocol. You choose which account permissions to grant. Payments, account deletion and recovery stay in your authenticated browser.
// on this page
00Try it now (demo access)
No account, no signup, no OAuth flow. A public, read-only demo token connects your MCP client to Abner's own live analytics for abner.app right now. Add this to your client config:
{
"mcpServers": {
"abner-demo": {
"type": "http",
"url": "https://mcp.abner.app/mcp",
"headers": { "Authorization": "Bearer abner_ws_demo_portfolio_readonly" }
}
}
}
Then just ask your agent:
"How is my traffic doing across all my sites, anything weird?"
That question routes straight to query_portfolio and get_changes, no site id needed. Demo access is read-only over one real site, abner.app's own live analytics; every write tool (create_site, delete_site) returns the tool error "demo access is read-only" instead of making a change. Here's the kind of answer you get back, one row since the demo account owns exactly one site:
// result of query_portfolio({ "period": "7d" })
{
"period": "7d",
"sites": [
{
"site_id": "…",
"name": "Abner",
"domain": "abner.app",
"last_event_at": "2026-08-18T10:12:00Z",
"status": "live",
"metrics": {
"visitors": { "current": 842, "previous": 761, "change_pct": 10.65 },
"pageviews": { "current": 2103, "previous": 1988, "change_pct": 5.78 }
}
}
],
"truncated": false
}
Ready for your own analytics? Skip to Install in Claude Code below and go through the real OAuth flow.
01Install in Claude Code
One command, browser opens for consent, you're done:
claude mcp add --transport http --scope user abner https://mcp.abner.app/mcp
Use --scope user so the server is available from any directory. The first time you call a tool, Claude Code pops your browser to log in to Abner and approve the consent screen.
In Claude Desktop
Settings → Developer → Edit Config, add:
{
"mcpServers": {
"abner": {
"transport": "http",
"url": "https://mcp.abner.app/mcp"
}
}
}
In Cursor
Cursor follows the same Streamable HTTP spec. Add an HTTP MCP entry pointing at https://mcp.abner.app/mcp.
02Authentication (OAuth 2.1)
Abner is a fully spec-compliant OAuth 2.1 server with:
- Authorization Code grant + PKCE (S256 only)
- Refresh tokens that rotate on every use
- Dynamic Client Registration (RFC 7591) — your client self-registers; no manual client_id setup
- Resource indicators (RFC 8707) — tokens are audience-bound to the MCP server URL
Discovery happens via two well-known endpoints:
# issued by the resource server
GET https://mcp.abner.app/.well-known/oauth-protected-resource
# issued by the authorization server
GET https://www.abner.app/.well-known/oauth-authorization-server
Token lifetimes:
- Authorization code: 60 seconds, single-use
- Access token: 1 hour
- Refresh token: 30 days, rotated on every use
Check your connection and permissions
Ask your client to call get_connection_status with no arguments. It reports the account ID and accessible sites for the credential on that request, whether it is the published demo or another read-only account key, and its granted and effective permissions. No credential is created, and no analytics query is run. Compare the account ID with MCP connections while signed in to Abner. Your browser account and your client's credential can belong to different accounts.
The diagnostic does not reveal your profile or email under analytics-only access. site_inventory.status: "unavailable" means the lookup failed, not that you have no sites. A capability's authorization describes permissions; availability: "configured" describes configured dependencies, not a successful backend health check. Optional missing scopes are upgrade choices, not connection failures. account:manage includes account reads even when account:read is not literally in the grant.
- Choose what you need. Existing analytics use
analytics:read. Account inspection additionally needsaccount:read; new management actions needaccount:manage. Analytics OAuth grants retain legacy site creation/deletion; they are not read-only credentials. Read-only account keys reject writes. - Start in your MCP client. Use its sign-out/disconnect and connect/authorize controls for this Abner connection. Ask it to request the space-separated scopes you chose. Client support varies: there is no universal reconnect URL or CLI flag for OAuth permissions. Claude Code's
--scope userselects local configuration visibility, not account permission. If your client cannot request additional OAuth scopes, consult that client's documentation; do not paste a credential into a browser page or chat as a workaround. - Review in your browser. Confirm the signed-in account, site coverage, client label and exact requested permissions. Choose Allow only if you intend that access; otherwise Deny. If the account changes while a consent tab is open, restart authorization from the client. Nothing on the connection page grants access automatically.
- Check again. Call
get_connection_statusafter connecting. Refresh never adds scopes. The server cannot change your client's saved configuration or identify its live credential from the browser token list.
| What you see | What to do |
|---|---|
| Only abner.app with published demo access | You are viewing the demo account. Connect your own account through the client's OAuth flow to see your sites. |
| Read-only account key | Read-only access may be your own account, not the public demo. Use OAuth with explicit management consent if you need writes; a site API key cannot authenticate MCP. |
| Missing permission / insufficient scope | Keep using already allowed features, or start a new client-controlled authorization request for the additional permission. Refreshing an old grant does not upgrade it. |
| 401 / invalid, expired or revoked bearer | The status tool cannot run without authentication. Let your client renew the access token; if renewal fails, reconnect there. Do not repeatedly retry a rejected bearer or create replacement keys blindly. |
| Expired access record in the browser | The client may still hold a valid refresh token. Expiry alone does not establish disconnection. |
| Revoked or rotated access record | A newer access token may exist. Only a record marked grant revoked establishes that its whole authorization family was revoked. |
| Inventory unavailable | Retry the lookup later; do not assume your account has no sites or authorizations. |
03Tools reference
All 27 tools require an authenticated connection with analytics:read. Personal account, billing and credential inventory requires an additional account:read or account:manage grant. New write tools require account:manage. The original create_site and delete_site tools retain their existing OAuth permissions; deletion still requires exact domain confirmation. Read-only account keys cannot perform any write.
list_sites
no argsReturns every site the authenticated user can read, each with last_event_at and a liveness status (best-effort; omitted if analytics is unavailable). Always call this first if you don't already have a site_id.
query_metrics
swiss armyVisitors, pageviews, sessions, custom events and scroll-depth averages — grouped and filtered with the supported vocabulary, over preset or custom dates. Includes bounded pagination, sorting and CSV export.
query_realtime
liveActive visitors in the last five minutes plus a stream of recent events (pageviews, custom events, scroll depth).
query_vitals
p75Core Web Vitals at the 75th percentile: LCP, FID, CLS, FCP, TTFB, INP. Takes period or a custom date_from/date_to range.
query_funnel
statelessAn ordered, per-session conversion funnel over inline steps — nothing is stored server-side; pass the steps you want each time.
query_portfolio
account-wideEvery site in the account in one call, each with metrics compared to the previous period and a liveness status. Use this before per-site tools when the question spans the whole portfolio. Example: "how are all my sites doing this week?"
get_changes
account-wideSites whose visitors moved at least 30 percent versus the previous period (minimum 50 visitors across both windows), ranked by swing size, each with the top pathnames and referrer hosts behind the move. Example: "anything weird going on across my sites this week?"
create_site
createsCreates a new site under your account and returns the ready-to-paste tracking snippet. Rejects a domain that's already registered to your account; call list_sites first to check.
delete_site
destructivePermanently deletes a site and its Postgres plus ClickHouse data. Requires direct site ownership and exact-match confirm_domain.
Additional analytics and management tools
| Tool | Capability | Additional permission |
|---|---|---|
get_connection_status | Current request's verified account ID, site coverage, credential kind and permissions; no arguments, secrets or analytics query | None |
query_meta | Live query vocabulary, property-key grammar, periods, pagination limits and export formats | None |
get_site | Owned site metadata, tracking snippet and data-flow status | None |
update_site | Change site name, tracked domain or reporting timezone | account:manage |
list_site_keys | List an owned site's key metadata, without existing secrets or hashes | account:read or account:manage |
create_site_key | Create a site read key; returns the new secret once | account:manage |
rotate_site_key | Replace a site key, preserving its label; exact key-ID confirmation required | account:manage |
revoke_site_key | Revoke a site key with exact key-ID confirmation | account:manage |
get_account | Account ID, profile name, email and creation date | account:read or account:manage |
update_account | Change the account profile name | account:manage |
list_account_keys | Account key metadata and read-only state, without secrets or hashes | account:read or account:manage |
create_account_key | Create a read-only key by default; writable REST key creation requires exact account-email confirmation | account:manage |
revoke_account_key | Revoke an account key with exact key-ID confirmation | account:manage |
list_mcp_tokens | Up to 100 OAuth access-token records with public IDs and client/expiry metadata | account:read or account:manage |
revoke_mcp_token | Revoke an OAuth authorization family, including its refreshed descendants; exact token-ID confirmation required | account:manage |
get_billing | Current plan, trial choice/end and whether a subscription is recorded | account:read or account:manage |
switch_trial_plan | Choose Indie or Studio on a free-trial account; does not purchase a subscription | account:manage |
get_account_action | Authenticated browser handoff for checkout, portal, account deletion, password reset, API keys, MCP tokens or staff pages | None; staff handoff additionally requires a staff account |
get_account_action returns { action, url, user_action_required: true, instructions }. You must sign in and complete the action in your browser. It does not start checkout, change a paid subscription, send recovery emails, delete an account or bypass staff authorization.
query_metrics — schema
type Input = {
site_id: "<uuid>", // from list_sites
metrics: ["visitors" | "pageviews" | "sessions" | "pageviews_per_visitor" | "events" | "avg_scroll_depth"],
dimensions?: ["pathname" | "referrer_host" | "country" | "region" | "city" |
"browser" | "os" | "device_type" |
"utm_source" | "utm_medium" | "utm_campaign" |
"time_day" | "time_hour" | "event_name" |
"outbound_url" | "file_extension" | "scroll_depth" | "property.<key>"],
filters?: { [dimension: string]: string },
period?: "24h" | "7d" | "14d" | "30d" | "month" | "year" | "all", // default 7d
date_from?: string, // YYYY-MM-DD (site timezone) or RFC3339; requires date_to, excludes period, span at most 366 days
date_to?: string, // inclusive for YYYY-MM-DD
compare?: "previous_period", // adds each metric's {current, previous, change_pct} vs the preceding window; only valid without dimensions
limit?: number, // default 50, max 1000
offset?: number, // grouped rows to skip: 0–1000000
sort?: string, // one of the requested metrics
order?: "asc" | "desc",
format?: "json" | "csv" // default json; CSV exports the requested page only
}
With no dimensions, returns a single overview row. Pass time_day or time_hour for a time series. Pass pathname for top pages. Pass filters: { country: "US" } to scope, or filters: { event_name: "signup" } to isolate a custom event, e.g. metrics: ["visitors"] to count signup conversions. Pass compare: "previous_period" on an overview query to get comparison: { visitors: { current, previous, change_pct }, … }; change_pct is null when the previous value was zero.
Grouped queries return meta with limit, offset, count, has_more and, when another bounded page may exist, next_offset. Rows use stable dimension tie-breaks, but pagination reads live data rather than a frozen snapshot. CSV is returned as a text/csv embedded resource and in the structured csv field with export_scope: "page"; continue paging to retrieve more groups. Untrusted text cells are escaped for spreadsheet safety.
Use query_meta for the current vocabulary. property.<key> selects one top-level property: 1–64 ASCII letters, digits, underscores or hyphens, starting with a letter or underscore. Strings are decoded; other values use JSON text; a missing property is an empty string. Filters are exact matches joined with AND. Use event_name: "outbound" with outbound_url, event_name: "file_download" with file_extension, and event_name: "scroll_depth" with scroll_depth. avg_scroll_depth averages numeric 0–100 scroll observations and returns 0 if none match.
result = await session.call_tool("query_metrics", {
"site_id": site_id, "metrics": ["events"],
"dimensions": ["outbound_url"],
"filters": {"event_name": "outbound"},
"limit": 100, "offset": 0, "sort": "events",
"order": "desc", "format": "csv"
})
Site and credential examples
// Requires an account:manage grant. No existing secret is retrievable.
await session.call_tool("update_site", {"site_id": site_id, "timezone": "America/New_York"})
created = await session.call_tool("create_site_key", {"site_id": site_id, "label": "Reporting"})
// Store the newly returned key securely; do not log or paste it into chat.
await session.call_tool("rotate_site_key", {"site_id": site_id, "key_id": key_id, "confirm_key_id": key_id})
await session.call_tool("create_account_key", {"label": "Agent", "read_only": true})
await session.call_tool("get_account_action", {"action": "billing_portal"})
create_account_key defaults to read_only: true. To create a writable REST management key, pass read_only: false and confirm_account matching your account email exactly. Writable REST management keys are not MCP login credentials. rotate_site_key reports replacement_created and old_key_revoked; if old-key revocation fails, secure the returned replacement and retry revoking the old key. Creating or rotating credentials is not idempotent: inspect an uncertain outcome before repeating the request.
query_funnel — schema
type Input = {
site_id: "<uuid>", // from list_sites
steps: [string], // 2-8 ordered specs: "path:<pathname>" or "event:<name>"
period?: "24h" | "7d" | "14d" | "30d" | "month" | "year" | "all", // default 7d
date_from?: string, // YYYY-MM-DD (site timezone) or RFC3339; requires date_to, excludes period, span at most 366 days
date_to?: string, // inclusive for YYYY-MM-DD
window_seconds?: number // max seconds between first & last step in a session; default 86400, max 604800
}
Steps must occur in order within one session. Example — signup funnel over the last 30 days:
result = await session.call_tool("query_funnel", {
"site_id": site_id,
"period": "30d",
"steps": ["path:/pricing", "path:/signup", "event:signed_up"],
})
// → { site_id, period: "30d", steps: [
// { step: 1, label: "path:/pricing", sessions: 820, conversion_rate: 100, dropoff_rate: 0 },
// { step: 2, label: "path:/signup", sessions: 240, conversion_rate: 29.3, dropoff_rate: 70.7 },
// { step: 3, label: "event:signed_up", sessions: 164, conversion_rate: 20, dropoff_rate: 31.7 },
// ] }
query_portfolio schema
type Input = {
metrics?: ["visitors" | "pageviews" | "sessions" | "pageviews_per_visitor" | "events"], // default visitors, pageviews; visitors is always included
period?: "24h" | "7d" | "14d" | "30d" | "month" | "year" | "all", // default 7d; always compared to the previous window of equal length
date_from?: string, // YYYY-MM-DD or RFC3339; requires date_to, excludes period, span at most 366 days
date_to?: string // inclusive for YYYY-MM-DD
}
No site_id: this is the one query tool that spans every site in the account. The window resolves in UTC, since it spans sites in different timezones. Accounts with more than 500 sites are truncated after sorting by name (truncated: true). Example, "how are all my sites doing this week?":
result = await session.call_tool("query_portfolio", { "period": "7d" })
// → { period: "7d", sites: [
// { site_id, name: "Example", domain: "example.com", last_event_at: "2026-08-18T10:12:00Z", status: "live",
// metrics: { visitors: { current: 1240, previous: 980, change_pct: 26.53 }, pageviews: { current: 3877, previous: 4210, change_pct: -7.91 } } }
// ], truncated: false }
get_changes schema
type Input = {
period?: "24h" | "7d" | "14d" | "30d" | "month" | "year" | "all", // default 7d; always compared to the previous window of equal length
date_from?: string, // YYYY-MM-DD or RFC3339; requires date_to, excludes period, span at most 366 days
date_to?: string // inclusive for YYYY-MM-DD
}
No site_id: spans every site in the account, same UTC window as query_portfolio. A site is dropped as noise when its current-plus-previous visitors total is below 50. Of the rest, a site is listed when its absolute percent change is at least 30, ranked by absolute percent change descending (a move from zero visitors ranks first), each with its top 3 contributing pathname and referrer_host values by absolute visitor delta. An empty changes list means nothing moved beyond the thresholds, which is itself the answer. Example, "anything weird going on across my sites this week?":
result = await session.call_tool("get_changes", { "period": "7d" })
// → { period: "7d", changes: [
// { site_id, name: "Example", domain: "example.com", direction: "up",
// visitors: { current: 1240, previous: 640, change_pct: 93.75 },
// contributors: {
// pathname: [ { value: "/blog/launch", current: 480, previous: 40, delta: 440 } ],
// referrer_host: [ { value: "news.ycombinator.com", current: 390, previous: 0, delta: 390 } ] } }
// ] }
create_site schema
type Input = {
name: "Marketing Site", // human-readable, shown in the dashboard
domain: "example.com", // scheme, www., and any path are stripped automatically
timezone?: "America/New_York" // IANA name; default UTC
}
Returns site_id (use it for every other tool), public_id (the tracking id, embedded in tracking_snippet), and the ready-to-paste tracking_snippet itself. Paste the snippet verbatim rather than assembling your own tag from public_id, since site_id and public_id are different values and only public_id is accepted by the tracking endpoint. Fails if a site with the same domain already exists in your account.
delete_site — schema
type Input = {
site_id: "<uuid>", // from list_sites
confirm_domain: "example.com" // must exactly match the site's domain
}
This tool permanently deletes the site row, related Postgres data, and ClickHouse rows in analytics, vitals, search-console, forecast, conversion, and anomaly tables. The authenticated user must directly own the site.
04Calling from code
The MCP server speaks plain Streamable HTTP — any MCP SDK works.
Python
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
async with streamablehttp_client(
"https://mcp.abner.app/mcp",
headers={"Authorization": f"Bearer {access_token}"},
) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
sites = await session.call_tool("list_sites", {})
result = await session.call_tool("query_metrics", {
"site_id": sites.structuredContent["sites"][0]["site_id"],
"metrics": ["visitors", "pageviews"],
"dimensions": ["time_day"],
"period": "30d",
})
TypeScript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const transport = new StreamableHTTPClientTransport(
new URL("https://mcp.abner.app/mcp"),
{ requestInit: { headers: { Authorization: `Bearer ${token}` } } },
);
const client = new Client({ name: "my-app", version: "0.1.0" });
await client.connect(transport);
const result = await client.callTool({
name: "query_realtime",
arguments: { site_id },
});
Curl (for debugging)
curl -sS https://mcp.abner.app/mcp \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
05Token management
Review OAuth access-token records at /account/mcp-tokens/ or with list_mcp_tokens (up to 100 records; requires account:read or account:manage). Listings contain random public IDs and client, issue, expiry and revocation metadata, never bearer secrets or hashes. Check revocation_scope: grant_family identifies one authorization family, while legacy_client_connections identifies grouped legacy connections.
revoke_mcp_token requires account:manage, a public token_id, identical confirm_token_id, and confirm_revocation_scope matching the current listing. It revokes the entire authorization family, including access and refresh descendants, so that connection must re-authorize. Independent new grants remain separate. Confirming legacy_client_connections disconnects every grouped legacy session for that account, client and resource. Missing or mismatched scope confirmation fails before revocation. Revoking the current connection may interrupt its next call.
Migration preserves existing token authority and does not revoke valid refresh-only legacy sessions. Those connections appear in this access-token inventory after they next refresh; existing revoked or mismatched pairs remain denied.
API keys are separate from OAuth tokens: use the site-key and account-key tools above. Secrets are stored hashed at rest (SHA-256), and newly generated API secrets are returned only in the creation or rotation result.
06Scopes & rate limits
analytics:readis required on every connection. It covers analytics, owned-site discovery and browser handoffs. For compatibility, existing OAuth grants also retaincreate_siteanddelete_site, with ownership and deletion confirmation checks.account:readopts into profile, billing and credential/token metadata. It does not allow writes.account:manageopts into new site, credential, profile and trial-plan writes, and also allows account reads. Newly generated API secrets are included in create/rotate results.
Your MCP client requests space-separated scopes during OAuth authorization, for example analytics:read account:read for account inspection or analytics:read account:manage for management. An existing analytics-only grant needs a new consent flow for these permissions; refresh does not add scopes. The Claude Code --scope user flag controls local configuration visibility, not OAuth permissions.
Read-only account keys, including the demo key, authenticate analytics-only access and reject all writes. They do not grant the new personal-account or credential inventory permissions. Site API keys remain scoped to the site REST read API and do not authenticate MCP.
An operator can temporarily expose only the original nine tools using MCP_LEGACY_TOOLS_ONLY=true on the current image. Authentication and grant-family protections remain in place; clients should refresh their tool inventory. This mode does not revert the enhanced analytics query behavior or require existing multi-scope clients to re-authorize.
Rate limits will be applied per-token; documented values will land here once they're enforced. For now: be reasonable.