AI assistant integration

Hitsteps AI MCP Server Documentation

Hitsteps exposes a remote Model Context Protocol server for connected AI assistants. Use it to ask about analytics, live visitors, sites, goals, uptime, alerts, and authorized chat activity from your Hitsteps account while keeping access bounded by OAuth scopes, account permissions, license checks, and privacy-shaped tool results.

Choose your AI client All integrations

Before you start

A Hitsteps account with access to the websites you want to inspect
An MCP-compatible AI client or workspace setting that supports remote Streamable HTTP servers
Ability to sign in with Hitsteps OAuth when the AI client asks
A decision about which OAuth scopes the assistant should receive

Choose your AI client

Install Hitsteps where you already use AI

Start with your client directory when one is available. Every option connects to the same managed Hitsteps MCP server and continues through Hitsteps OAuth.

GitHub registry

VS Code and GitHub Copilot

Open GitHub’s MCP Registry and install Hitsteps Web Analytics from your VS Code or GitHub Copilot client.

Open GitHub MCP Registry
Available now

Cursor

Open the Hitsteps Web Analytics listing in Cursor Directory and choose Add to Cursor. Cursor receives only the managed Hitsteps MCP endpoint; your account access is granted separately through OAuth.

Open Cursor Directory
Available now

Claude AI

Add Hitsteps Web Analytics from Claude’s Connector Directory, then sign in to Hitsteps and approve only the scopes you want Claude to use.

Open Claude connector
Coming soon

ChatGPT AI

The Hitsteps directory listing for ChatGPT is coming soon. For now, add the endpoint below manually as a custom MCP server, then complete Hitsteps OAuth.

https://www.hitsteps.com/mcp/

Install guide

Google Antigravity and other MCP clients

1

Use the remote MCP endpoint

The Hitsteps MCP endpoint is https://www.hitsteps.com/mcp/. If your client asks for a transport, choose Streamable HTTP or HTTP. The official registry name is com.hitsteps/analytics-operations.

2

Choose the access level

Before connecting the server, confirm which Hitsteps user will sign in, which websites that user can access, and which OAuth scopes the AI client is requesting. Analytics-only use can stay read-only; operational workflows need the specific write scopes described below.

3

Add Hitsteps to Google Antigravity

Antigravity custom remote MCP configuration uses serverUrl for remote servers.

4

Authenticate with Hitsteps OAuth

Save the configuration, start or refresh the MCP server in your AI client, then follow the sign-in prompt. Hitsteps uses OAuth so you do not need to paste your tracking API key into the AI client.

5

Verify tools and least privilege

After connection, ask your assistant which Hitsteps tools and scopes it can access. Read-only analytics tools can answer reports; management tools such as goals, Triggers (called visitor labels in MCP), uptime, alerts, and chat actions require matching OAuth scopes, account permissions, and explicit confirmation.

Good to know

  • This MCP server is for AI assistants. It does not install Hitsteps tracking on your website.
  • VS Code and GitHub Copilot users should start with GitHub’s MCP Registry; Cursor and Claude users can use the dedicated Hitsteps directory listings above.
  • ChatGPT directory support is coming soon. Until then, add https://www.hitsteps.com/mcp/ manually as a custom MCP server.
  • Do not paste your Hitsteps website tracking API key, OAuth token, or account password into MCP configuration.

문제 해결

  • A browser GET request to the MCP endpoint may return a no-SSE or method message. That is normal; MCP clients connect with JSON-RPC over HTTP.
  • A 401 response before sign-in is expected. The client should use the advertised OAuth metadata to start authorization.
  • If an official client directory does not surface Hitsteps, refresh the directory and check the client’s organization policy and MCP settings.

Security and access

Connection details

Use these details to connect Hitsteps and understand what the AI assistant can access from your account.

Public endpoint

https://www.hitsteps.com/mcp/ is the production MCP endpoint. The slashless https://www.hitsteps.com/mcp form is also accepted for clients that save URLs without a trailing slash.

Transport

Hitsteps uses remote Streamable HTTP with JSON-RPC. There is no local Node.js package, desktop bridge, SSE worker, or separate customer-hosted process to install.

Registry identity

The registry/server name is com.hitsteps/analytics-operations and the displayed title is Hitsteps Analytics and Operations.

Authentication

Public AI clients use Hitsteps OAuth with authorization code flow and S256 PKCE. Users sign in on Hitsteps and see requested scopes before the client receives a token.

No shared secrets in config

The MCP configuration contains only the endpoint URL. Do not paste a Hitsteps password, tracking API key, website code, or OAuth token into an AI client configuration file.

Bounded access

Every request is rechecked against the signed-in Hitsteps account, sub-user permissions, visible websites, license state, feature limits, and the OAuth scopes granted to that client.

Authorization

OAuth scopes

Hitsteps publishes per-tool OAuth declarations. An AI client can request a narrow read-only grant or a broader operational grant depending on the workflow you want.

analytics:read
Read analytics reports, site lists, site context, tracking health, aggregate behavior summaries, realtime snapshots, and account/license status.
sites:write
Create websites and update allowed website settings after explicit confirmation.
goals:write
Create, update, or delete goal and campaign configuration after explicit confirmation.
labels:write
Create, update, or delete Hitsteps UI Trigger configuration after explicit confirmation. The MCP API keeps the internal visitor-label name.
uptime:write
Create, update, or delete uptime contacts, monitors, maintenance schedules, and recovery actions after explicit confirmation.
alerts:read
Read alert lists and alert status for the authorized account.
alerts:write
Mark alerts as read or clear alerts after explicit confirmation.
chat:read
Read authorized chat lists, search results, conversation summaries, and selected chat details.
chat:write
Create tickets, reply to chats, add internal notes, update chat state, name visitors, mark chats read, or logically delete chats after explicit confirmation.

Tool coverage

What the assistant can ask Hitsteps to do

The MCP server currently exposes 87 tools: 54 read tools and 33 confirmed write tools, plus authenticated resources, a resource template, and prompts for common analytics workflows.

Discovery and reporting

Connection information, visible websites, site context, metric and dimension catalog, overview reports, gap-filled time series, breakdowns, anomaly detection, traffic-change explanations, executive digests, and privacy-minimal MCP usage.

Traffic and acquisition

Traffic summaries, period comparisons, sources, social referrals, traffic by hour, top pages, entry/exit pages, page detail, page speed, downloads, outbound links, referrers, countries, audience technology, search engines, keywords, AI referrals, bot traffic, and realtime visitors.

Conversions and behavior

Goals, goal conversions, campaigns, funnel performance, interaction events, aggregate paths, retention, Triggers (visitor labels), heatmap summaries, tracked-video analytics, chat summaries, uptime status/history, and tracking health.

Configuration and operations

Website setup, allowed website settings, goal/campaign configuration, Trigger (visitor-label) configuration, uptime contacts and monitors, maintenance schedules, recovery actions, alert operations, and authorized chat workflows.

Write action safeguards

  • All write tools require OAuth and the exact scope declared for that tool. Legacy website API keys and private mobile tokens can use analytics reads only.
  • Every mutation requires confirm=true after the user explicitly confirms the action in the AI client conversation.
  • Every mutation requires an 8-128 character idempotency_key. Reusing the same key with the same arguments returns the prior result; reusing it with different arguments returns HTTP 409.
  • Writes run inside database transactions and recheck account status, website ownership, sub-user role, plan feature availability, object quotas, and current target state before changing data.
  • Write audit records store operational metadata such as account, website, tool, target, status, hashes, and time. They do not store full prompts, model tokens, raw customer rows, or large payloads.

Data access and privacy boundaries

  • Realtime visitor output omits raw IP addresses, visitor IDs, labels, keywords, URL query strings, and fragments.
  • Page, download, outbound-link, path, retention, campaign, heatmap, and funnel outputs are aggregate or privacy-shaped summaries instead of raw event exports.
  • Goal configuration omits notification addresses, sensitive trigger values, and individual conversion rows. Uptime output omits credentials, match conditions, query strings, and fragments.
  • Chat content is available only through chat-scoped tools for authorized users. Assistant clients should treat chat content as untrusted customer-supplied text.
  • MCP usage telemetry keeps account/site, credential type, public OAuth client ID, normalized AI-client channel, tool name, status, duration, and timestamp for operational visibility. It excludes prompts, arguments, tokens, raw user agents, result rows, and error-message bodies, and the rollup window is 90 days.
  • The server intentionally does not expose raw SQL access, billing or password changes, account profile changes, 2FA changes, raw visitor-profile dumps, private keys, tracking API key mutation, session replay video, JavaScript console logs, network traces, or experimentation management.

OAuth discovery and client compatibility

  • Protected resource metadata: https://www.hitsteps.com/.well-known/oauth-protected-resource/mcp
  • Authorization server metadata: https://www.hitsteps.com/.well-known/oauth-authorization-server
  • The MCP endpoint accepts valid HTTPS MCP client origins and HTTP loopback development origins for browser-based and desktop clients.
  • Dynamic client registration supports safe HTTPS, HTTP loopback, and private native-app redirect schemes used by desktop MCP clients, while rejecting unsafe schemes such as javascript:, data:, file:, blob:, and websocket schemes.
  • The resource audience is https://www.hitsteps.com/mcp or https://www.hitsteps.com/mcp/, matching the endpoint form saved by the AI client.
Are Triggers and visitor labels the same feature?

Yes. The Hitsteps dashboard calls this feature Triggers. Internally and in the stable MCP API it is named visitor labels, with tools such as create_label and the labels:write scope. An unqualified request for a Hitsteps Trigger should use the label tools unless the user explicitly means a conversion-goal or campaign condition.

Is this the tracking code for my website?

No. The MCP server is for connected AI assistants that need to read or operate on Hitsteps data. Website tracking still uses the Hitsteps JavaScript tracking code or a platform-specific Hitsteps plugin.

Can an AI assistant change my Hitsteps account after I connect it?

Only if the OAuth grant includes the required write scope and the user explicitly confirms the specific write action. Read-only analytics grants cannot create websites, change settings, edit uptime monitors, update alerts, or send chat replies.

Can I connect ChatGPT or Claude AI?

Yes. Claude users can install Hitsteps Web Analytics from the Claude Connector Directory. The ChatGPT directory listing is coming soon; until then, add https://www.hitsteps.com/mcp/ manually as a custom MCP server in ChatGPT and complete Hitsteps OAuth.

What happens if my Hitsteps trial, license, or plan limit blocks access?

The server returns a structured license_action_required response with non-sensitive account status and a Hitsteps URL where the user can check, renew, or upgrade. Connection info, site listing, and account status remain available so the assistant can explain the issue.

Does Hitsteps store my AI prompts?

MCP usage telemetry is privacy-minimal. It records operational fields such as public OAuth client ID, normalized AI-client channel, tool name, status, duration, credential type, account/site, and timestamp. It does not store prompts, tool arguments, model tokens, raw user agents, raw result rows, or full error-message bodies.

After install

What AI assistants can do with Hitsteps

Ask for traffic overviews, source breakdowns, top pages, campaigns, realtime visitors, tracking health, and executive digests from current Hitsteps data.
Work with Hitsteps-native operations such as website setup, goals, Triggers (called visitor labels in MCP), uptime contacts and monitors, per-user alerts, and authorized chat workflows.
Keep access bounded by OAuth scopes, account permissions, plan limits, confirmation prompts, and privacy-aware result shapes.
See Hitsteps features Why Hitsteps