AI-Assisted Analytics Development with HitKeep

Use HitKeep’s AI surfaces according to the job. Production MCP is for governed aggregate analytics and docs lookup. Analytics Agent Skills teach external assistants how to reason about that data. Ask AI uses the same transport-neutral analytics procedures with an internal tool bridge. Contributor skills and the local hk developer MCP are for changing HitKeep itself.

Check OAuth release availability and instance support before connecting an OAuth-capable assistant with explicit consent for the MCP resource and selected sites. For an instance or client without OAuth, create a scoped API-client token, keep it in the assistant’s secret store, and grant only the sites it should query. Do not give assistants dashboard cookies or raw exports just because they are convenient.

Route production AI through a gateway

HitKeep has a rudimentary global AI request and token limiter. It is a coarse process-level safeguard, not per-user, per-site, per-provider-key, or a security policy engine. For production use, route model traffic through an AI gateway or provider policy layer that can enforce detailed quotas, model allowlists, key isolation, audit logging, redaction, and network controls. See GoAI’s supported provider options and generic OpenAI-compatible provider docs for the underlying base URL, token, header, and custom endpoint patterns.

Choose The Right Surface

Surface	Use it for	Do not use it for
MCP server	Read-only aggregate analytics, imported Search Console rows, Web Vitals aggregates, saved Opportunities, and official docs lookup.	Site creation, goal mutation, billing, token management, raw hit exports, or dashboard session access.
Analytics Agent Skills	Teaching an external assistant HitKeep’s analytics workflow, metric caveats, and privacy boundary.	Repository setup, contributor QA, or storing credentials and customer data.
Ask AI shared procedures	Grounding the dashboard assistant in the same transport-neutral analytics reasoning through its internal tool bridge.	MCP token setup or external-client instructions.
Contributor Agent Skills	Operating the repository-owned hk CLI and local developer MCP for setup, workspaces, QA, and localization.	Customer analytics or production deployment operations.
REST API	Normal application automation and bounded external-assistant actions with API-resource OAuth consent and current authority.	Treating a site or billing grant as unrestricted administration.
A2A analytics	Synchronous structured aggregate reads with an API-resource analytics grant, when advertised by the instance.	Writes, billing, background tasks or autonomous payments.
Dashboard	Human setup, admin review, visual investigation, and workflow checks.	Reusing dashboard cookies in an AI client.
Open exports and takeout	Portable owned files, offline analysis, account-level export workflows, and audit handoff.	Live assistant queries that only need aggregate answers.
AI model configuration	Enabling optional HitKeep product features that need structured model output.	Running a general chat assistant inside HitKeep.

Build An Analytics Assistant

For live analytics assistant workflows, use MCP and Agent Skills together:

1. Install the HitKeep Agent Skills in the assistant client.
2. Enable the HitKeep MCP server on the HitKeep leader if it is not already enabled.
3. Configure the assistant with the canonical HTTPS MCP URL, including any deployment prefix or custom MCP path.
4. If the instance advertises OAuth and the client supports it, approve sites:read analytics:read for one team and only the sites it needs. Open the header user menu and choose Connected applications to review the grant.
5. Otherwise, create a dedicated personal or team API-client token with explicit grants for those sites and configure the assistant to send it as a bearer token.
6. Ask the assistant to name the site, date range, comparison range, and data source it used.

MCP answers should stay aggregate. If the assistant needs raw files for a one-off audit, use takeout or open exports instead of expanding the MCP token.

Dashboard localization is contributor work. Use the hitkeep-i18n skill from .agents/skills for UI copy, Transloco keys, locale JSON files, OptimusUI locale behavior, and localized formatting. It uses hk for QA and does not need production MCP access.

Keep MCP Changes Safe

If you contribute to HitKeep’s MCP server, keep the public contract stable:

• tools remain read-only and aggregate-only
• each tool sets a read-only annotation
• analytics tools stay closed-world
• docs tools are the only tools that fetch official docs markdown
• authenticate with scoped API-client bearer tokens or resource-bound OAuth access tokens, with explicit site grants and current user authority
• raw hit exports, write workflows, billing, token management, takeout, and dashboard sessions stay outside MCP

Use hk to select and run the current production-MCP gates when MCP behavior changes:

./hk qa changed --gate mcp-audit --gate mcp-schema

The public HitKeep Agent Guide explains the repository-level contributor rules for MCP, Agent Skills, AI output validation, docs, and tests.

Keep both skill packs aligned

The analytics pack is canonical under skills/:

• keep the five public analytics skill identities independently installable;
• keep each SKILL.md as the production-MCP adapter;
• keep each references/procedure.md transport-neutral because Ask AI embeds it;
• keep current tool names and mutable schemas in the live tool surfaces and docs, not copied into procedures;
• do not include credentials, private analytics, private URLs, or customer screenshots
• update skills/README.md and this public guide when the analytics pack shape changes.

The contributor pack is canonical under .agents/skills/. Keep hitkeep-development, hitkeep-workspace, hitkeep-qa, and hitkeep-i18n focused on hk and repository policy. Never copy these bodies under skills/ or embed them into Ask AI.

Optional AI Model Features

HitKeep’s optional AI provider route is for product features, not for unrestricted assistant access. Provider credentials configure model requests; an assistant’s OAuth grant authorizes scoped access to HitKeep data. Ask AI uses the signed-in user’s site permissions and its internal tool bridge, so connecting an external assistant neither configures the provider nor enables Ask AI.

Opportunity Recommendations are the first model-backed workflow. HitKeep reads aggregate analytics, runs deterministic detectors, and asks the configured model for a small structured response. HitKeep validates the response before storage.

HitKeep should not store raw prompts, raw provider payloads, raw external error bodies, provider headers, or provider secrets. Saved AI output should contain safe product fields such as localization keys, interpolation params, cited evidence IDs, detector metadata, status, and audit metadata.

If you change GoAI-backed Opportunity generation, keep the saved output contract key-based and deterministic. New saved fields, message keys, interpolation params, action types, or evidence shapes should have validator coverage before they are accepted.

Use the repository-owned QA planner for AI provider, Opportunity, storage, and MCP exposure changes:

./hk qa plan changed --output json
./hk qa changed

Use AI Model Configuration for provider setup and Opportunity Recommendations for the customer-visible behavior.

When REST API Or Exports Are Better

Use the REST API when you are building a product integration that needs explicit request and response contracts. API clients, site grants, and normal server permissions still apply. For an external assistant, use Authorization Code with PKCE S256 for the exact API resource and the operation’s advertised OAuth scope. The action scopes are goals:write, annotations:write, sites:write, opportunities:write and billing:write; they require AI Enabled and do not grant arbitrary dashboard access. Site actions require explicit site consent. Billing-only consent selects a team without sites, and all requests remain subject to current permissions and grant revocation.

On a configured Cloud instance, the assistant can initiate an ACP/UCP checkout with billing:write and current team billing administration. It returns continue_url for the user to approve payment in hosted Stripe Checkout; the assistant retrieves provider state instead of assuming a redirect or /complete call proves payment. MCP and A2A remain read-only analytics. MPP/x402 settlement and WebBotAuth signing/verification are unavailable; see the actual checkout boundaries and prerequisites.

Use open exports or takeout when the user needs portable files, raw records that are available through export workflows, or a compliance/audit handoff. MCP intentionally avoids raw hit export tools because assistant access should remain scoped, revocable, and aggregate by default.

Related

• Official MCP Server
• HitKeep Agent Skills
• AI Model Configuration
• API Clients
• Open Exports and Takeout
• Facts and Limits