--- title: "HitKeep MCP Server for Read-Only Analytics | HitKeep" description: "Enable the optional leader-only HitKeep MCP server for governed, read-only analytics access from AI assistants and internal reporting tools." canonical: "https://hitkeep.com/guides/integrations/mcp/" --- # 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 only API client bearer tokens. It 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](https://hitkeep.com/use-cases/read-only-mcp-server-web-analytics/) for the exact exposed tools, screenshots, Search Console behavior, AI crawler analytics behavior, and permission boundary. **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: - visible sites for the 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 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. ## Create a token Use a scoped personal or team API client: 1. Open **Settings -> API Clients** for a personal token, or **Administration -> Team -> Settings** 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 does not accept dashboard cookies on MCP. This keeps MCP access explicit, revocable, and scoped through API client permissions. 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](https://hitkeep.com/guides/integrations/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](https://hitkeep.com/guides/integrations/ai-development/) to choose between MCP, Agent Skills, REST API, dashboard workflows, open exports, and optional AI model configuration. ## 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. Mint a very short-lived MCP token from a server-side session before making a browser request. AI clients such as Claude Desktop, Cursor, or internal assistants can use normal HitKeep API client bearer tokens directly. Browser sessions should not. ## Analytics arguments Analytics tools use the same tenant-aware stores as the dashboard and REST API. A `site_id` must be visible through the API client’s explicit `site_roles` grants and must pass `site.view`. 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`. Filters support: ``` path, hostname, referrer, referrer_host, device, country, city, provider, asn, browser, language, utm_campaign, utm_content, utm_medium, utm_source, utm_term ``` ## 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. ## 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 visible to the API client. | | hitkeep_get_site_overview | Return KPI totals, chart data, top dimensions, goals, and optional comparison. | | hitkeep_get_event_names | List event names for a site and date range. | | hitkeep_get_event_breakdown | Return a capped property breakdown for one event. | | hitkeep_get_ecommerce | Return ecommerce summary, products, source stats, and city/provider/ASN aggregates. | | 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_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. | ## 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= \ 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](https://hitkeep.com/use-cases/read-only-mcp-server-web-analytics/) - [HitKeep Agent Skills](https://hitkeep.com/guides/integrations/hitkeep-agent-skills/) - [AI Development With HitKeep](https://hitkeep.com/guides/integrations/ai-development/) - [API Clients](https://hitkeep.com/guides/security/api-clients/) - [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/) - [Architecture](https://hitkeep.com/reference/architecture/) - [Configuration Reference](https://hitkeep.com/reference/configuration/#optional-mcp-route) [Previous Signed webhooks](https://hitkeep.com/guides/integrations/webhooks/)[Next HitKeep Agent Skills](https://hitkeep.com/guides/integrations/hitkeep-agent-skills/)