Official MCP Server

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.

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, and source stats
• Web Vitals p75, sample counts, rating counts, and optional page 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.

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. This keeps MCP access explicit, revocable, and scoped through API client permissions.

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 to the API client 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, 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
• limit: defaults to 10 and is capped at 50

The response is aggregate-only: p75 values, sample counts, rating counts, derived p75 ratings, and optional page 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

Docs pages and llms.txt are 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.

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, and source stats.
hitkeep_get_web_vitals	Return aggregate Web Vitals p75, sample counts, rating counts, and optional page 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 llms.txt catalog 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 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

• MCP Analytics Access
• API Clients
• Opportunity Recommendations
• Architecture
• Configuration Reference