// 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.

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:

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:

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.

  1. Choose what you need. Existing analytics use analytics:read. Account inspection additionally needs account:read; new management actions need account:manage. Analytics OAuth grants retain legacy site creation/deletion; they are not read-only credentials. Read-only account keys reject writes.
  2. 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 user selects 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.
  3. 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.
  4. Check again. Call get_connection_status after 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 seeWhat to do
Only abner.app with published demo accessYou are viewing the demo account. Connect your own account through the client's OAuth flow to see your sites.
Read-only account keyRead-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 scopeKeep 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 bearerThe 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 browserThe client may still hold a valid refresh token. Expiry alone does not establish disconnection.
Revoked or rotated access recordA newer access token may exist. Only a record marked grant revoked establishes that its whole authorization family was revoked.
Inventory unavailableRetry 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 args

Returns 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 army

Visitors, 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

live

Active visitors in the last five minutes plus a stream of recent events (pageviews, custom events, scroll depth).

query_vitals

p75

Core Web Vitals at the 75th percentile: LCP, FID, CLS, FCP, TTFB, INP. Takes period or a custom date_from/date_to range.

query_funnel

stateless

An ordered, per-session conversion funnel over inline steps — nothing is stored server-side; pass the steps you want each time.

query_portfolio

account-wide

Every 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-wide

Sites 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

creates

Creates 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

destructive

Permanently deletes a site and its Postgres plus ClickHouse data. Requires direct site ownership and exact-match confirm_domain.

Additional analytics and management tools

ToolCapabilityAdditional permission
get_connection_statusCurrent request's verified account ID, site coverage, credential kind and permissions; no arguments, secrets or analytics queryNone
query_metaLive query vocabulary, property-key grammar, periods, pagination limits and export formatsNone
get_siteOwned site metadata, tracking snippet and data-flow statusNone
update_siteChange site name, tracked domain or reporting timezoneaccount:manage
list_site_keysList an owned site's key metadata, without existing secrets or hashesaccount:read or account:manage
create_site_keyCreate a site read key; returns the new secret onceaccount:manage
rotate_site_keyReplace a site key, preserving its label; exact key-ID confirmation requiredaccount:manage
revoke_site_keyRevoke a site key with exact key-ID confirmationaccount:manage
get_accountAccount ID, profile name, email and creation dateaccount:read or account:manage
update_accountChange the account profile nameaccount:manage
list_account_keysAccount key metadata and read-only state, without secrets or hashesaccount:read or account:manage
create_account_keyCreate a read-only key by default; writable REST key creation requires exact account-email confirmationaccount:manage
revoke_account_keyRevoke an account key with exact key-ID confirmationaccount:manage
list_mcp_tokensUp to 100 OAuth access-token records with public IDs and client/expiry metadataaccount:read or account:manage
revoke_mcp_tokenRevoke an OAuth authorization family, including its refreshed descendants; exact token-ID confirmation requiredaccount:manage
get_billingCurrent plan, trial choice/end and whether a subscription is recordedaccount:read or account:manage
switch_trial_planChoose Indie or Studio on a free-trial account; does not purchase a subscriptionaccount:manage
get_account_actionAuthenticated browser handoff for checkout, portal, account deletion, password reset, API keys, MCP tokens or staff pagesNone; 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

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.