HitKeep MCP Server for Read-Only Analytics

HitKeep includes an optional Model Context Protocol route for assistants and internal tools that need governed access to aggregate analytics and HitKeep documentation. It is an analytics MCP server for teams that want Claude, Cursor, or another MCP client to answer approved analytics questions without handing an assistant dashboard cookies or raw exports.

MCP is off by default. When enabled, it is mounted on the existing HitKeep HTTP server and accepts scoped API-client bearer tokens. Instances with OAuth discovery can also accept resource-bound OAuth access tokens; check release availability and instance support before using that setup. MCP does not accept dashboard cookies.

The v1 design is intentionally read-only. HitKeep MCP can answer traffic, event, ecommerce, Web Vitals, AI visibility, saved Opportunities, imported Search Console, and docs questions. It does not create funnels, create alerts, mutate goals, manage sites, or perform admin actions.

If you are evaluating HitKeep as a read-only MCP server for web analytics, use the tool-surface overview for the exact exposed tools, screenshots, Search Console behavior, AI crawler analytics behavior, and permission boundary.

For client setup, follow the dedicated Claude, ChatGPT, or Codex guide. Each separates installing analytics skills from authorizing an MCP connection. The Claude analytics, ChatGPT analytics, and Codex analytics pages explain the corresponding reporting workflows.

HitKeep MCP server

An optional read-only Streamable HTTP MCP route for aggregate analytics, official docs lookup, and scoped AI assistant access.

What it exposes

The v1 server is read-only:

• sites authorized for the OAuth grant or API client
• aggregate site overview analytics
• event names and event property breakdowns
• ecommerce summary, top products, source stats, and city/provider/ASN aggregates
• Web Vitals p75, sample counts, rating counts, optional page breakdowns, and aggregate visitor-context breakdowns
• AI visibility overview, timeseries, and optional correlation
• saved Opportunities recommendations with localization keys, params, cited evidence, detector metadata, and status
• imported Google Search Console status, overview, series, and optional dimensions
• official HitKeep docs pages returned as markdown
• local help and metric-definition resources
• short usage instructions sent when a client connects
• the public HitKeep analytics procedures as prompts

It does not expose raw hit exports, site creation, goal mutation, exclusions, takeout, billing, or instance administration.

Enable the server

Start the leader with MCP enabled:

hitkeep \
  -mcp-enabled \
  -mcp-path /mcp

Equivalent environment variables:

HITKEEP_MCP_ENABLED=true
HITKEEP_MCP_PATH=/mcp

By default MCP is served from the same address as the dashboard and API. If HitKeep listens on http://127.0.0.1:8080, the default MCP endpoint is http://127.0.0.1:8080/mcp.

Do not mount MCP at /. HitKeep reserves / for the dashboard and static assets. If the MCP path is empty or /, HitKeep normalizes it back to /mcp.

In clustered deployments, only the leader mounts MCP. Followers log that MCP is leader-only and skip the route.

Find your assistant endpoint

Open Integration → Assistants (/integration/assistants) after signing in to HitKeep. Copy the MCP endpoint shown there, then follow the setup link for Claude, ChatGPT, or Codex. Viewing this guidance does not require permission to manage OAuth registrations.

The endpoint comes from the instance’s canonical OAuth resource configuration, including its deployment prefix and custom MCP path. Use that exact URL rather than building one from the current browser address. Configured for assistant setup describes configuration; it does not verify an installed or working assistant connection.

If setup is unavailable, ask your administrator to check the instance’s MCP and canonical HTTPS configuration. A legacy API-token connection can remain available even when no canonical OAuth endpoint is shown; use the existing API clients workflow for manual setup. Enabling MCP does not grant any assistant access by itself.

After connecting, try: “Compare my site’s last seven complete days with the preceding seven. What changed, and what remains uncertain?” Choose a site explicitly if the assistant finds several matches.

Connect with OAuth

On an instance exposing OAuth discovery, an OAuth-capable MCP client can connect without a copied API token. First check the advertised resource and issuer metadata, then:

1. Enter the instance’s canonical HTTPS MCP URL in the client.
2. Follow the client to HitKeep and use your normal login, passkey, MFA, or SSO flow.
3. Explicitly approve one team, the sites the assistant may query, and sites:read analytics:read for the MCP resource.
4. Open the user menu in the header and choose Connected applications to review or revoke the connection.

MCP advertises its protected-resource metadata in the authentication challenge. The OAuth audience is the configured MCP URL, including any deployment prefix and custom mount. A token for the REST API resource cannot be used on MCP, or the reverse. Disabling MCP also disables its OAuth resource.

Every analytics request checks the token’s scopes, explicit consented sites, and your current site permissions. Removing access takes effect on subsequent requests. MCP-resource grants do not permit administration, raw exports, or write tools. Separate API-resource grants can authorize the bounded REST actions; they do not add writes to MCP. Client support and provider approval are separate from this protocol support; this does not claim an official Claude or ChatGPT listing.

If your client requires a registered client ID, a team owner or admin with team.manage_api_clients can register its exact HTTPS callbacks at Integration → OAuth clients. HitKeep generates a public client ID without a secret; the client must support PKCE S256. Editing or revoking that registration invalidates its existing grants. HTTPS Client ID Metadata Document clients can identify themselves without a dashboard registration.

The OAuth integration guide describes registration, discovery, refresh rotation, revocation, and compatibility. Existing API clients remain available for unattended jobs and clients without OAuth support.

Create a token

Use a scoped personal or team API client:

1. Open Integration → API for a personal token, or Administration → Team → API clients for a team token.
2. Scope the token only to the sites the MCP client needs.
3. Copy the token immediately. HitKeep stores only a hash after creation.

Team API clients are the better default for shared assistants because they are owned by the team and can be revoked independently.

Add an explicit site grant for every site the assistant should query. MCP site tools ignore instance/admin API-client roles unless the token also has a matching site grant, so a token with no site grants has no analytics access.

Connect an MCP client

Use the Streamable HTTP endpoint:

http://127.0.0.1:8080/mcp

Send the token as a bearer header:

Authorization: Bearer <hitkeep-api-client-token>

HitKeep does not accept dashboard cookies on MCP. Access remains explicit, revocable, and site-scoped for both OAuth and API clients.

The endpoint supports the sessionless MCP 2026-07-28 protocol. A client can call server/discover and list methods without initialize or Mcp-Session-Id; standard Mcp-Protocol-Version, Mcp-Method, and (where required) Mcp-Name headers must agree with the JSON-RPC request. Legacy clients can still negotiate the unchanged initialize-based protocol.

If the MCP client supports Agent Skills, install the HitKeep Agent Skills so analytics questions use the intended HitKeep tool sequence and privacy boundary.

If you are building or contributing AI-assisted workflows around HitKeep, use AI Development With HitKeep to choose between MCP, Agent Skills, REST API, dashboard workflows, open exports, and optional AI model configuration.

Configure an assistant

Use the client’s current Streamable HTTP setup and the exact HTTPS MCP URL for your instance. Choose one authentication route:

Route	What you need
OAuth with an HTTPS Client ID Metadata Document (CIMD)	A public client whose validated metadata and callbacks meet HitKeep’s OAuth client requirements.
Pre-registered OAuth client	A team registration for HTTPS callbacks, or an operator registration for a native client. Use the issued/configured client ID and PKCE S256, without a client secret.
Scoped bearer token	A dedicated personal or team API-client token with explicit grants for the requested sites.

HitKeep does not expose Dynamic Client Registration (DCR). A client that requires DCR must use a supported pre-registration or bearer-token route instead.

Codex with a scoped bearer token

Codex supports Streamable HTTP bearer tokens through an environment variable. Add this to your Codex config.toml:

[mcp_servers.hitkeep]
url = "https://analytics.example.com/mcp"
bearer_token_env_var = "HITKEEP_MCP_TOKEN"

Replace the URL with your canonical MCP endpoint. Supply HITKEEP_MCP_TOKEN to the Codex process through your environment or secret manager; keep the token out of the configuration file, prompts, and version control. Ask the assistant to list the granted sites before requesting a report.

Claude Code and Codex with OAuth

Use the exact MCP endpoint copied from Integration → Assistants. Claude Code supports HTTP MCP and browser OAuth sign-in:

claude mcp add --transport http hitkeep https://analytics.example.com/mcp

Then open /mcp in Claude Code and follow its sign-in flow. Codex supports MCP OAuth with CIMD or a configured client ID:

codex mcp add hitkeep --url https://analytics.example.com/mcp
codex mcp login hitkeep

Replace the example endpoint with your canonical URL, including its prefix and custom mount. HitKeep accepts validated HTTPS CIMD declarations for native HTTP loopback callbacks, including portless declarations. It permits only the listener port to vary; the declared hostname, scheme, escaped path, and raw query must match. This supports native callback patterns without allowing arbitrary HTTP redirects or private metadata fetches. See the exact native callback policy.

If pre-registration is required, give the operator the exact callback shown by the client and use the configured public client ID. Dashboard team registrations remain HTTPS-only. HitKeep requires PKCE S256 and does not accept client secrets or signed client assertions.

ChatGPT’s OAuth flow supports CIMD and predefined clients. Follow your account’s current custom-connection setup and select the MCP resource and sites explicitly. A custom connection authorizes an instance; installing an optional skills or plugin package is a separate step. Account, workspace, and network restrictions can affect setup.

These configuration paths describe supported protocol behavior. They do not establish a tested end-to-end connection for every client version or account, a published plugin, or a marketplace listing.

Publish MCP on the same origin

The simplest public setup is to publish MCP on the same origin as the dashboard at /mcp.

Example public URLs:

• dashboard: https://analytics.example.com/
• MCP: https://analytics.example.com/mcp

This avoids cross-origin browser issues and keeps one canonical endpoint to share with AI tools.

Reverse proxy

Keep HitKeep bound to loopback if your proxy terminates public traffic:

HITKEEP_MCP_ENABLED=true
HITKEEP_MCP_PATH=/mcp
HITKEEP_HTTP_ADDR=127.0.0.1:8080

Then publish the normal HitKeep HTTP server through your reverse proxy.

Caddy

analytics.example.com {
    reverse_proxy 127.0.0.1:8080
}

nginx

server {
    server_name analytics.example.com;

    location /mcp {
        proxy_pass http://127.0.0.1:8080/mcp;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Authorization $http_authorization;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

If you use Traefik or another proxy, use the same shape: route public traffic to the main HitKeep server and make sure /mcp preserves bearer auth headers.

In clustered deployments, route /mcp to the leader’s HitKeep HTTP server. Do not send MCP traffic to followers.

Proxy requirements

Your proxy should:

• preserve the Authorization header
• preserve the original Host
• forward X-Forwarded-For
• forward X-Forwarded-Proto
• disable response buffering for /mcp
• trust only the proxies you control through HitKeep’s trusted proxy settings

HitKeep validates MCP request hosts against HITKEEP_PUBLIC_URL. The easiest setup is to preserve the public Host header all the way to HitKeep.

If your proxy rewrites the upstream Host to a loopback address such as 127.0.0.1:8080, configure explicit trusted proxy CIDRs and forward the public host:

HITKEEP_PUBLIC_URL=https://analytics.example.com
HITKEEP_TRUSTED_PROXIES=127.0.0.1/32

proxy_set_header Host 127.0.0.1:8080;
proxy_set_header X-Forwarded-Host $host;

Do not rely on HITKEEP_TRUSTED_PROXIES=* for forwarded MCP hosts. The wildcard is useful for simple client IP setups, but MCP host validation only trusts forwarded host headers from explicitly configured proxy networks.

Frontend and browser usage

If you need a frontend feature to call MCP, keep /mcp on the same public origin as the dashboard. That avoids CORS problems and gives the UI a stable endpoint for connection tests or health checks.

Do not put long-lived API client tokens into browser JavaScript or local storage.

For browser-facing features, prefer one of these patterns:

1. Add a normal authenticated backend endpoint that tests MCP or proxies a narrow MCP request.
2. Use an OAuth-capable client and explicit consent for the MCP resource and selected sites.

Clients that support an Authorization bearer header can use scoped HitKeep API-client tokens. Dashboard sessions cannot authenticate MCP.

Analytics arguments

Analytics tools use the same tenant-aware stores as the dashboard and REST API. OAuth requires sites:read analytics:read and explicit consent for the requested site_id; API clients need an explicit site_roles grant. Both must pass current site.view permission checks.

Date fields are optional RFC3339 timestamps:

• from
• to
• compare_from
• compare_to

If omitted, analytics tools use the last 30 days. Ranges longer than -mcp-max-range-days are rejected.

Comparison ranges use the same limit. If you send compare_from and compare_to, both fields are required and the comparison window cannot exceed -mcp-max-range-days.

limit defaults to 10 and is capped at 50.

hitkeep_get_site_overview always returns the KPI totals and any requested period comparison. Use the sole selector sections:["kpis"] to omit optional charts, lists, and goals. Do not combine kpis with another section or repeat it. Otherwise, sections selects from chart, pages, sources, audience, ai, utm, and goals; omitted or empty sections still returns every section. Requesting only relevant sections reduces response content. Its limit caps each top list between 1 and 10. Search Console keeps its separate section choices below.

hitkeep_get_ecommerce returns the revenue and order timeseries only when include_series is true.

hitkeep_get_breakdown breaks pageviews and visitors down by one dimension: page, referrer, country, city, device, browser, language, provider, asn, ai_source, ai_bot, utm_source, utm_medium, utm_campaign, utm_content, or utm_term. It accepts filters and returns up to 50 rows. With compare_from and compare_to, each row adds its previous pageviews, its change, and its share of the scanned pageview change, sorted by the largest movers. Comparisons scan each period’s top 500 tracked dimension values before applying the requested output limit. They exclude imported history and can omit the long tail; these shares are not exact sitewide attribution or proof of cause. When scanned change is zero, share_of_change is omitted.

The comparison response includes comparison_basis: population:"tracked_hits", imported_history_included:false, values_per_period_limit:500, and share_denominator:"scanned_pageview_change". current_values and previous_values count the fetched values before the output limit. current_limit_reached and previous_limit_reached flag when a period reached the scan cap, so more values may exist.

Filter values use the form tools return: countries are two-letter codes such as DE, and pages are paths such as /blog.

Filters support:

path, ai_bot, ai_bot_category, ai_source, hostname, referrer, referrer_host,
device, country, city, provider, asn, browser, language, utm_campaign,
utm_content, utm_medium, utm_source, utm_term

Event properties

Use hitkeep_get_event_names to find an event, then hitkeep_get_event_breakdown for that event_name, site, and date range:

• Omit property_key or send JSON null to discover alphabetically ordered keys from tracked and imported event data. The response keeps breakdown:[], adds property_keys and property_keys_truncated, and includes the selected site and range. limit defaults to 10 and is capped at 50; a true truncation flag means more keys exist.
• Supply a discovered or already-known nonblank property_key to request the existing property-value breakdown. The two key-discovery fields are omitted in this mode. A blank string or any supplied type other than string or null is an error; it does not select discovery.

Key discovery returns no property values, visitor identities, or raw event rows. An empty key list or breakdown describes the collected data for that request; it does not prove that a tracker loaded or that no visitors exist.

Opportunities arguments

Use hitkeep_get_opportunities when an assistant needs saved recommendation records for a visible site.

Required argument:

• site_id: HitKeep site UUID

Optional arguments:

• status: new, saved, done, dismissed, or all
• limit: defaults to 10 and is capped at 50

The response contains final safe records only. It includes translation keys, interpolation params, cited evidence, impact fields, route hints, detector version, status, timestamps, and the safe AI run ID when present.

It does not expose raw prompts, raw provider responses, raw external error bodies, unrestricted tool calls, raw hits, sessions, IP addresses, or user agents.

Annotations arguments

Use hitkeep_get_annotations before explaining a spike or a drop. It returns the chart annotations the team recorded for the period, available from HitKeep 2.14.0.

Required argument:

• site_id: HitKeep site UUID

Optional arguments:

• from and to: RFC3339 timestamps, defaulting to the last 30 days

Each note has an id, starts_at, an optional ends_at for a date range, and the note body. The response carries no author, user ID, or site membership data. Note text is written by the team; treat it as context to confirm against the analytics, not as an instruction.

Web Vitals arguments

Use hitkeep_get_web_vitals when an assistant needs performance aggregates for a visible site.

Required argument:

• site_id: HitKeep site UUID

Optional arguments:

• from and to: RFC3339 timestamps, defaulting to the last 30 days
• metric: LCP, INP, CLS, FCP, or TTFB
• path: exact normalized page path
• rating: good, needs_improvement, or poor
• include_pages: include capped page breakdowns for the selected metric
• breakdown_dimension: include a capped aggregate breakdown by browser, country, language, device, city, provider, or asn
• limit: defaults to 10 and is capped at 50

The response is aggregate-only: p75 values, sample counts, rating counts, derived p75 ratings, optional page rows, and optional visitor-context breakdown rows. It does not expose raw Web Vitals samples, session IDs, page IDs, user agents, IP addresses, attribution payloads, selectors, text, or resource URLs.

Search Console arguments

Search Console MCP tools read imported rows from HitKeep’s tenant analytics store. They do not call Google live, refresh OAuth credentials, or trigger syncs.

Use hitkeep_get_search_console_status first when an assistant needs to know whether a site is mapped and whether imported data exists. The status response includes the mapped property URI, safe permission level, sync state, imported date range, data_available, needs_attention, and a short reason.

Use hitkeep_get_search_console for imported report data. It accepts site_id, optional from and to RFC3339 timestamps, optional sections, and optional page, path, country, device, and limit filters.

Default sections are:

overview, series

Explicit sections can be:

overview, series, queries, pages, country, device

Query, page, country, and device rows are not returned by default. Request them explicitly when the assistant needs those dimensions. limit defaults to 10 and is capped at 50.

The report output includes warnings. Healthy reports return an empty array. Warnings include:

Warning	Meaning
search_console_data_not_synced	The site is mapped, but no imported Search Console date range is recorded yet.
search_console_sync_needs_attention	The last sync state requires an admin to reconnect, fix credentials, or restore property access.
search_console_sync_failed	The last sync failed, but HitKeep may still have older imported rows to report.
requested_range_starts_before_imported_data	The requested start is before the imported Search Console range.
requested_range_ends_after_imported_data	The requested end is after the imported Search Console range.

Documentation tools

Docs tools fetch from the configured official docs origin using:

Accept: text/markdown

The default docs base URL is:

https://hitkeep.com

Discovery and list responses carry private five-minute cache hints. Static help and metric resources carry private one-hour hints; docs resources use the configured docs-cache TTL. Analytics tool results are never cacheable. Docs pages and the llms.txt docs catalog are also cached in memory for the configured TTL. The cache is bounded to 128 entries and concurrent requests for the same page share one upstream fetch. Docs tools only fetch official docs after a user invokes a docs tool, and analytics data is never sent to the docs site.

HitKeep uses llms.txt as a compact navigation index for MCP and docs clients. It is not required for Google Search, AI Overviews, or AI Mode, and HitKeep does not treat it as SEO metadata.

Tools

Tool	Purpose
hitkeep_list_sites	List sites authorized for the OAuth grant or API client.
hitkeep_get_site_overview	Return KPI totals and optional comparison; request only kpis to omit optional chart, list, and goal sections.
hitkeep_get_breakdown	Break pageviews and visitors down by one dimension with optional filters, or rank each value’s change against a comparison period.
hitkeep_get_funnel_stats	Read step visitors, drop-off, and conversion for a configured funnel; get its funnel_id from the overview’s goals section.
hitkeep_get_qr_campaigns	Read a site’s QR campaign opens, pageviews, visitors, and optional open timeseries, without redirect tokens or raw hits.
hitkeep_get_event_names	List event names for a site and date range.
hitkeep_get_event_breakdown	Discover capped ordered property keys for an event, or return its property-value breakdown when property_key is supplied.
hitkeep_get_ecommerce	Return ecommerce summary, products, source stats, city/provider/ASN aggregates, and an optional timeseries.
hitkeep_get_web_vitals	Return aggregate Web Vitals p75, sample counts, rating counts, optional page breakdowns, and optional visitor-context breakdowns.
hitkeep_get_ai_visibility	Return AI fetch overview and timeseries, with optional correlation.
hitkeep_get_annotations	Return the team’s notes (releases, campaigns, outages) that overlap a date range, without author information.
hitkeep_get_opportunities	Return saved Opportunity recommendation records for a visible site.
hitkeep_get_search_console_status	Return Search Console mapping, sync status, available imported range, and safe attention reason for one site.
hitkeep_get_search_console	Return imported Search Console overview, series, and requested query, page, country, or device dimensions.
hitkeep_search_docs	Search the cached docs catalog (llms.txt) and fetched markdown snippets.
hitkeep_get_doc	Fetch one official docs page as markdown.
hitkeep_get_api_reference	Fetch REST API reference markdown for a path or operation slug.
hitkeep_get_mcp_help	Return local MCP usage guidance.

Instructions and prompts

From HitKeep 2.14.0, the server sends short usage instructions when a client connects. Most clients add them to the assistant’s context, so it starts with hitkeep_list_sites, uses comparison ranges for period-over-period questions, requests only the overview sections it needs, and checks annotations before explaining a spike or drop.

The server also offers the public HitKeep Analytics Agent Skills procedures as prompts. Clients that support prompts list them by name, such as hitkeep-traffic-diagnosis or hitkeep-tracking-verifier. Each prompt accepts an optional question argument and starts a structured analysis with the read-only tools.

Prompt	Purpose
hitkeep-analytics	General analytics questions.
hitkeep-traffic-diagnosis	Diagnose traffic changes.
hitkeep-ai-visibility-analyst	Analyze AI crawler fetches and AI-referred visits.
hitkeep-ecommerce-analyst	Analyze ecommerce performance.
hitkeep-tracking-verifier	Verify that tracking is set up and plausible.

Resources

Resource	Purpose
hitkeep://help/mcp	Token, date range, and privacy guidance.
hitkeep://help/metrics	Definitions for core metrics returned by MCP tools.
hitkeep://docs/llms	Cached official docs catalog (llms.txt).
hitkeep://docs/{path}	Markdown for a specific official docs page.

Privacy boundaries

The MCP server follows HitKeep’s privacy posture:

• bearer tokens only, no cookies
• API rate limiting applies
• tenant-aware analytics store resolution
• aggregate reads only
• Search Console reads imported aggregate rows only
• no raw hit export tools
• no write, admin, or billing operations
• docs tools are origin-locked to the configured HitKeep docs base URL

Audit the MCP surface

HitKeep ships a small audit script for the official MCP metadata and live protocol surface.

Validate the MCP Registry manifest:

tests/scripts/mcp-audit.sh --schema-only

Audit a running MCP endpoint:

HITKEEP_MCP_URL=http://127.0.0.1:8080/mcp \
HITKEEP_MCP_TOKEN=<hitkeep-api-client-token> \
tests/scripts/mcp-audit.sh

The live audit checks tools/list, resources/list, and resources/templates/list, confirms HitKeep tool names and read-only annotations, and rejects accidental write/admin-style tool names.

For interactive debugging, use the official MCP Inspector:

npx @modelcontextprotocol/inspector

Related

• Read-only MCP Server for Web Analytics
• HitKeep Agent Skills
• AI Development With HitKeep
• API Clients
• Opportunity Recommendations
• Architecture
• Configuration Reference

Public connection discovery

A configured instance publishes /.well-known/api-catalog, /.well-known/ai-catalog.json, and /.well-known/ard.json. They describe public integration endpoints and the five product analytics skills; they contain no customer analytics and grant no access. An instance with a public URL prefix keeps that prefix in its links. The origin-level well-known catalogs also remain reachable for discovery.

If an instance has no DNS publisher name, its ARD entries are empty; API and AI Catalog discovery remain available.

When MCP is enabled on the serving leader, its connection card lives at the configured MCP URL followed by /server-card, such as /mcp/server-card. The card uses the experimental MCP Server Card extension, not an accepted MCP standard. It describes remote connectivity and required bearer authorization; tools, resources, and prompts are listed only after authentication through MCP. The legacy /.well-known/mcp/server-card.json URL retains its connection fields for existing clients.

OAuth metadata remains authoritative for OAuth-capable clients. A scoped API-client token remains available for compatible clients, and neither discovery route accepts dashboard cookies as MCP authorization. Disabled MCP instances and followers do not advertise a local MCP card. A public catalog or card does not prove a working assistant connection, a marketplace listing, or approval by a registry.

Cloud catalogs also link the existing regional plan catalog. An available paid offer may include purchase_review_url: open that native page for the user to review the plan, billing interval, and active team. Opening the page does not start checkout or complete a purchase. External assistants can separately initiate the configured ACP/UCP checkout below with explicit API-resource billing:write consent; the native review link itself grants no billing authority.

Discover public integration resources

The public website’s AI Catalog and ARD manifest link the current regional API catalogs and the five canonical product analytics skills. Regional API catalogs identify the REST API description and existing read-only MCP connection metadata. Discovery does not grant analytics access or verify assistant compatibility; use the configured instance and scoped API-client authorization described above.

The catalogs describe each linked artifact by its actual format. A regional API catalog is a Linkset document, rather than an MCP Server Card or a nested AI Catalog. These discovery conventions are evolving, and clients decide which artifact formats they support.

On public documentation pages, the experimental WebMCP browser surface can expose the navigation links already rendered on the page when the browser supports it. This read-only navigation helper performs no search, network request, account action, analytics read, or checkout. It does not connect to the authenticated MCP server, and ordinary browser navigation remains available when WebMCP is unsupported.

Public discovery and sign-in

Use each instance’s /.well-known/api-catalog, /.well-known/ai-catalog.json and canonical MCP server card at the configured MCP path plus /server-card. The compatibility card remains at /.well-known/mcp/server-card.json. Cloud offers separate EU and US cards. A public card describes the connection; it never grants site access.

The website’s auth.md describes ordinary regional login and existing scoped OAuth. Its Poppy 0.2 profile advertises ordinary public browsing only. It does not offer Poppy sessions, DPoP grants, mediated password sign-in, an agent identity registration endpoint, or a signing-key directory. Choose the instance and approve real consent before using analytics.

Other agent integrations

New agent routes require the instance’s AI Enabled setting, independently of its model provider and Ask AI configuration. Ordinary REST, OAuth and the existing read-only MCP connection retain their own availability and authorization rules.

External assistants perform supported application changes through ordinary REST operations marked x-hitkeep-oauth-scope in the instance’s OpenAPI. Use an API-resource OAuth token with the required action scope: goals:write, annotations:write, sites:write, opportunities:write, or billing:write. Each scope has a specific operation boundary; none grants general administration. Site changes require explicit site consent and current authority. Review or revoke the connection through Connected applications. MCP and A2A continue to expose read-only analytics.

AI-enabled instances with OAuth and leader storage can expose an A2A 1.0 HTTP+JSON card at /.well-known/agent-card.json and synchronous POST /api/a2a/message:send. This adapter executes the same bounded aggregate analytics tools: use A2A-Version: 1.0, an API-resource OAuth grant with sites:read analytics:read, consented sites and current user access. The user message has role: ROLE_USER and a data part containing tool and arguments; the response is a direct ROLE_AGENT message. The card describes the accepted schemas. It is not a background task service or a new model provider. MCP-resource tokens and dashboard cookies do not authorize this API-resource operation.

Cloud checkout adapters are separate from analytics MCP. ACP 2026-04-17 uses /api/cloud/commerce/acp/checkout_sessions; UCP 2026-08-25 uses /api/cloud/commerce/ucp/checkout-sessions. An external assistant uses an API-resource OAuth bearer token with explicit billing:write consent and current team.manage_settings authority on the consented team. Billing-only consent needs a team but no sites; switching the dashboard’s active team does not change that grant. Browser sessions retain active-team billing administration. Both routes require AI Enabled, a Cloud billing build, an authoritative leader/store and configured Stripe prices. API-client tokens and analytics-only OAuth grants do not authorize billing. ACP requests supply API-Version: 2026-04-17; UCP supplies a compatible public HTTPS UCP-Agent profile and Request-Id. Mutations require Idempotency-Key; reuse the same key and body when retrying the same request.

When those checkout prerequisites are met, the regional instance exposes public ACP /.well-known/acp.json and UCP /.well-known/ucp profiles. They advertise REST Checkout for ACP 2026-04-17 and UCP 2026-08-25, with no payment handlers or autonomous payment rail. Profile URLs preserve the instance’s public URL prefix; unavailable commerce returns 404. Discover the selected EU or US instance directly. Reading a profile requires no OAuth token and grants no checkout authority.

A checkout contains one server-priced item (pro:monthly, pro:annual, business:monthly or business:annual), quantity one. An open session returns requires_escalation with a continue_url for human review and payment approval in hosted Stripe Checkout. A completed provider session whose payment is still pending returns complete_in_progress; only a retrieved complete and paid provider session returns completed. Clients must retrieve the actual session state. Calling /complete does not submit payment credentials or pay on the assistant’s behalf. Pending purchases are shared with ordinary browser billing to prevent competing checkouts, and current consent and billing authority are checked before replaying a stored result. Discovery or a return URL is not proof of payment.

MPP and x402 settlement execution is unavailable: the payment operations return 501 when reached on an otherwise configured instance, with no 402 payment challenge or cryptographic receipt. A real merchant payment profile, supported settlement/facilitator and proof verification adapter, and a defined currency contract are prerequisites. Hosted Stripe Checkout is the available payment rail; no AP2 or tokenized-payment handler is advertised.

WebBotAuth request signing and verification are not implemented. They would require real signing keys, published verification metadata, request verification and operational key rotation; a discovery document supplies none of these. Such machine identity would still not replace a user’s OAuth consent or billing authority. Check the actual instance’s metadata and API contract before using any optional protocol; documentation does not establish deployment, provider enrollment or client conformance.