Hardal MCP server
Commit Nov 15, 2026Allows an AI client to query Hardal analytics for traffic, event counts, acquisition, funnels, and campaign attribution using plain language.
Also known as usehardal/mcp
- Stars
- 0
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Hardal MCP?
Hardal allows an AI client to query Hardal analytics for traffic, event counts, acquisition, funnels, and campaign attribution using plain language. It exposes 6 tools, such as get_context, get_overview, get_breakdown.
Summary generated from the project's README
About Hardal MCP server
Querying Hardal analytics for traffic, event counts, and campaign attribution using plain language is what this remote MCP server enables. Developers and analysts can connect Claude, ChatGPT, or other MCP clients to their Hardal data to ask questions about acquisition, funnels, and visitor totals without writing complex queries. The server is hosted and requires no local installation, functioning as a streamable-HTTP connection.
Users connect via OAuth 2.1, meaning there are no API keys to manage manually. When setting up a client, you sign in through a browser and select specific workspaces to share, ensuring the server only accesses approved tenants. The available tools include get_overview for high-level metrics, get_breakdown for dimensional analysis, compare_periods for period-over-period comparisons, get_events for tracking specific actions, and get_funnels for conversion summaries. All data returned consists of read-only aggregates, ensuring no personal visitor records are exposed during the process.
Written from the project's README. Every use case is checked against a quote from it.
Hardal MCP tools 6
Detected from the READMEget_contextget_overviewget_breakdowncompare_periodsget_eventsget_funnels
Configuration
DATABASE_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableusehardal/mcp is public and reachablegithub.com/usehardal/mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/usehardal/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubA remote MCP server for querying your Hardal analytics from Claude, ChatGPT, or any other MCP client — ask about traffic, events, acquisition, funnels, and campaigns in plain language. You sign in with your own Hardal account, and the server only ever sees the workspaces you approve.
Connect
The server is hosted — there is nothing to install. Add it as a remote (streamable-HTTP) MCP server:
https://mcp.usehardal.com
- Claude (web, Desktop, Code) and ChatGPT: add the URL as a custom MCP connector. The client opens a browser, you sign in with Hardal and choose which workspaces (tenants) to share. Every request is then scoped to what you approved.
- A stdio-only client? Bridge it with
mcp-remote:
{
"mcpServers": {
"hardal": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.usehardal.com"]
}
}
}
There are no API keys or tokens to copy — sign-in and workspace access are handled through OAuth.
Tools
The report coverage matrix lists each tool variant, its Beacon endpoint, and the supported inputs.
Call get_context first to list your workspaces and pick a tenantId; the report tools take it from there.
| Tool | What it answers |
|---|---|
get_context |
Which organizations, tenants and sources you can query (with each tenant's report type and currency) |
get_overview |
What happened over a date range — visitor/session/page-view totals, bounce & consent rates, top pages/referrers/locations, and a time series |
get_breakdown |
Traffic broken down by one dimension — acquisition (channels/sources/campaigns), top pages, or events |
compare_periods |
Two date ranges side by side — e.g. this month vs last month |
get_events |
Which events fire and how often, with per-event counts, sessions and visitors |
get_funnels |
A tenant's saved funnels, or one funnel's conversion summary over a date range |
Every tool is read-only and returns aggregates only.
Response envelope
A successful call returns structuredContent as { schemaVersion: "1.0.0", ok: true, context, data }, and the same JSON as the second text block. data is the tool's report as before (report, appliedFilters and the variant fields such as reportType, dimension or mode); no field Beacon returns is removed or renamed, and the values are the ones the Hardal dashboard shows for the same tenant, source, date range and timezone. The one transformation: path values lose their query string and fragment, and context.redactedLabels counts them. context states what the numbers describe: tenant and source, the resolved date range and previous range, the timezone and whether it was explicit or the default, interval, applied filters (for Acquisition, the values Beacon applied, including the tenant's attribution settings), currency, completeness (returnedRows, limit, hasMore) and missingValues, one entry per column that contains nulls, so a missing value is never read as zero. Pagination objects keep limit, offset and total and add returnedRows, hasMore (null when continuation is unknown) and truncated.
A failed call returns isError: true with a text line code: message and a second text block { "schemaVersion": "1.0.0", "ok": false, "error": { "code", "message", "retryable", "retryAfterSeconds", "fields"? } } (fields lists the offending argument paths when the arguments were rejected). Codes follow the V1 tool contract (invalid-arguments, unsupported-filter, access-denied, quota-exceeded, upstream-unavailable, response-too-large, currency-unavailable, ...) and never include Beacon paths. Arguments the MCP SDK rejects against the input schema come back in the same envelope with invalid-arguments. The error envelope travels as text rather than structuredContent, because MCP SDK clients validate structuredContent against the success outputSchema.
Timezone
Every report tool accepts an optional timezone (an IANA name such as Europe/Istanbul or UTC). An explicit value always takes precedence. When it is omitted, every tenant defaults to Europe/Istanbul, and each answer states the timezone it used in its filters line — so the same question yields the same numbers whether or not you pass it.
V1 has no per-tenant timezone setting. If a workspace's Hardal dashboard is configured for a different timezone, day boundaries — and therefore totals — can differ between the dashboard and MCP answers; pass timezone explicitly to match the dashboard.
How it works
Hardal MCP signs you in through Hardal's own authorization server (OAuth 2.1): clients discover it via GET /.well-known/oauth-protected-resource and a 401 WWW-Authenticate challenge. The server validates your token and, to read your reports, exchanges it for a scoped Reports-API token — your token itself never reaches the reporting API. Access is limited to the tenants you consented to, and revoking the connection (or an admin revoking access) stops it on the next request.
Develop
bun install
cp .env.example .env
bun run service-identity:generate # writes keys/{public,private}.jwk.json
bun run dev # http://localhost:1922
Register the generated public key with a running Beacon:
# from the beacon/apps/api checkout
DATABASE_URL=<beacon db> bun run scripts/register-oauth-service-identity.ts \
--client-id hardal-mcp \
--name "Hardal MCP" \
--jwk <mcp>/keys/public.jwk.json \
--operations introspect,token_exchange
In production the service private key lives in Azure Key Vault (SERVICE_PRIVATE_JWK_VAULT_URL).
Privacy & Support
Every tool returns aggregates only — counts, totals, rankings, time series — never per-visitor records, so no personal data passes through this server. Access is read-only and scoped to the workspaces you approve.
Questions or a vulnerability to report: support@usehardal.com.
License
MIT — see LICENSE.
Hardal MCP questions
What tools does Hardal MCP provide?
It exposes 6 tools, including get_context, get_overview, get_breakdown, compare_periods, get_events.
Does this server require API keys?
No, sign-in and workspace access are handled through OAuth, so there are no API keys or tokens to copy.
What kind of data can I query?
You can query visitor and session totals, bounce rates, top pages, acquisition channels, event counts, and funnel conversion summaries.
Is my personal data safe?
Yes, the server only returns aggregates like counts and totals, never per-visitor records, ensuring no personal data passes through.