mpulse-mcp
The mpulse-mcp server wraps the Akamai mPulse Query API v2, enabling retrieval of loss-free, aggregate Real User Monitoring (RUM) data for performance analysis.
Core query tools:
get_summary(median, p95, p98, count),get_histogram(distribution buckets),get_timers(single‑metric per‑minute series),get_metrics(multi‑metric per‑minute series), and a genericquerytool for any known mPulse query‑type (e.g.,dimension-values,geography,page-groups,browsers).Batch aggregation:
get_aggregateruns a matrix of timers/metrics × periods × percentiles and returns a compact table of period aggregates.Meta discovery:
list_apps,list_query_types,describe_queryto discover apps, query‑types, and parameter details without hallucination.Rich filtering & time selection: Drill down by page group, browser, country, device type, AB test, etc. Query for a single calendar day (
date) or relative windows (date_comparator); timezone‑aware (default UTC).Loss‑free data: Numeric values are never rounded;
raw=truereturns untouched JSON,history_modecontrols time‑series detail (downsample/none/full).Smart input handling: Auto‑corrects timer/metric name casing/separators, rejects unknown names with suggestions, and guards against silent fallbacks.
Error resilience: Automatic token refresh, 429 retry with backoff, human‑readable errors (secrets masked), and 403 guidance (mPulse Lite).
Empty & truncation diagnostics:
empty_reasonheuristic, optionalprobe=trueto distinguish no‑traffic from unsupported combos; high‑cardinality results capped at 100 rows withtruncatedflag.
Provides tools to interact with the Akamai mPulse Query API, enabling retrieval of Real User Monitoring (RUM) aggregate data such as summaries, histograms, and per-minute time series for timers and metrics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mpulse-mcp Get the PageLoad summary for yesterday"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mpulse-mcp
An MCP (Model Context Protocol) server that wraps the Akamai mPulse Query API v2 and exposes it as tools for Claude Desktop (local stdio). It fetches mPulse RUM (Real User Monitoring) aggregate data — summaries, histograms, and per-minute time series — and returns loss-free numbers suitable for downstream p75 / statistical analysis.
Accuracy first — endpoints, parameters, and schemas were confirmed against the live mPulse docs before implementation (see Verified API contract).
Loss-free data — numeric values are never rounded, summarized, or dropped.
stdio-safe — nothing is ever written to stdout (that would corrupt the JSON-RPC stream); all logs go to stderr. Secrets are masked in logs.
Verified API contract
Fetched from techdocs.akamai.com/mpulse during implementation. The table below
records what was confirmed and any differences from the original brief's
assumed defaults.
Item | Confirmed value |
Query base host |
|
Query URL format |
|
Auth header |
|
Common param |
|
Token endpoint |
|
Token request body |
|
Token response |
|
Token lifetime | expires after 5 hours of inactivity |
Data characteristics | per-minute aggregation, one calendar day per query, timezone-dependent |
Confirmed query-type slugs → explicit tools
Tool | query-type slug | Response core |
|
|
|
|
|
|
|
|
|
|
|
|
Other confirmed slugs (reachable via the generic query tool):
dimension-values, dimension-over-time, metrics-by-dimension,
metric-per-page-load-time, sessions-per-page-load-time, app-error-summary,
page-groups, browsers, ab-tests, bandwidth, geography.
Confirmed parameters: timer (default PageLoad) / custom-timer,
metric (default Beacons), percentile (1–99, default 50), date
(YYYY-MM-DD), date-comparator (Last30Minutes, LastHour, Last24Hours,
ThisWeek, Last + trailing-seconds, Between + date-start/date-end),
timezone (Java TZ id, default UTC).
Confirmed drilldown params: page-group, browser, browser-family,
ab-test, country (ISO alpha-2), region, device-type, device-model,
device-manufacturer, os, os-family, connection-type, isp,
bandwidth-block, beacon-type, site-version, custom-dimension-{label}.
Unsupported drilldown combinations return empty data, not an error — the
server flags this in the result note.
Differences from the brief's assumed defaults
date_comparator→ wire namedate-comparator(hyphen). Tool arguments use underscores and are mapped to the hyphenated wire names automatically.Token lifetime is "5 hours of inactivity", not a very-short token. The server still refreshes proactively (soft 4h TTL) and reactively on a query
401, so correctness does not depend on the exact figure.Rate-limit numbers (concurrent 3 / 100 per-min / 10k per-hour / 50k per-day) could not be re-confirmed from the doc pages fetched. They are adopted from the brief and kept configurable as constants in
client.py(MAX_CONCURRENCY,PER_MINUTE_LIMIT, retry settings). The per-hour/per-day caps are advisory (not separately throttled).
Related MCP server: telemetry-mcp
Install
Requires Python 3.11+ and uv.
uv sync --extra devConfigure
Secrets go in the environment; the non-secret app registry goes in a JSON file.
Registry — copy the example and fill in your api keys / tenant:
cp mpulse_apps.example.json mpulse_apps.json{ "default_app": "app-a", "tenant": "your-tenant", "api_token_env": "MPULSE_API_TOKEN", "apps": { "app-a": { "api_key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX" }, "app-b": { "api_key": "YYYYY-YYYYY-YYYYY-YYYYY-YYYYY", "tenant": "override-if-different", "api_token_env": "MPULSE_API_TOKEN_APP_B" } } }Resolution: an app's
tenant/api_token_envoverride the top-level defaults;api_keyis required per app. The registry path is found viaMPULSE_APPS_CONFIG, else./mpulse_apps.json.Custom dimensions (optional). mPulse has no API to discover an app's custom dimensions, so declare them here to make them usable without guessing. Add a
custom_dimensionsobject per app (top-level entries are inherited by every app and merged with the app's own):"custom_dimensions": { "branch": { "display": "Branch" } }, "apps": { "app-a": { "api_key": "…", "custom_dimensions": { "mobile_speed": { "display": "mobile speed", "description": "effectiveType" }, "campaign": {} } }, "app-b": { "api_key": "…", "custom_dimensions": ["checkout_step"] } }Keys are the mPulse wire label (lowercased, spaces →
_); a value may benull, a{display, description, values?}object, or you may pass a plain list of names. Used as a split (metrics-by-dimension dimension=<label>) or a filter (custom-dimension-<label>=<value>). These are hints only (never used to reject), since the declared list may be incomplete.Secrets — set the pre-issued mPulse API token(s) (mPulse → your name → Account → Generate/Revoke API Token). See
.env.example:MPULSE_API_TOKEN=your-pre-issued-api-token # MPULSE_API_TOKEN_APP_B=... # only if an app overrides api_token_envThe short-lived security token used on each request is minted at runtime from the API token + tenant — you never manage it yourself.
Where does
.envgo? For local runs and the smoke test, place.envin the project root (the folder withpyproject.toml, i.e. the working directory). It is auto-loaded at startup — also from the directory ofMPULSE_APPS_CONFIG. Existing environment variables are never overridden. For Claude Desktop, do not use.env— put secrets in theenvblock ofclaude_desktop_config.json(below); that is what Claude Desktop injects, and it takes precedence over any.env.
Run
uv run mpulse-mcp # or: uv run python -m mpulse_mcpTransport is stdio; the process speaks MCP on stdout and logs to stderr.
Register in Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"mpulse": {
"command": "uv",
"args": ["--directory", "/Users/hyoon/Projects/mpulse-mcp", "run", "mpulse-mcp"],
"env": {
"MPULSE_API_TOKEN": "your-pre-issued-api-token",
"MPULSE_APPS_CONFIG": "/Users/hyoon/Projects/mpulse-mcp/mpulse_apps.json"
}
}
}
}Restart Claude Desktop; the mPulse tools appear in the tools menu.
Tools
Explicit (typed, validated): get_summary, get_histogram, get_timers
(single timer, per-minute), get_metrics (multiple timers/metrics, per-minute).
Each accepts app (optional → default app), exactly one of date
(YYYY-MM-DD) or date_comparator, optional timezone, drilldown filters
(page_group, browser, ab_test, country, device_type, …), and
raw (default false).
Batch: get_aggregate(metrics=[...], timers=[...], periods=[...], percentiles=[50,75], …) — a (metric|timer) × period × percentile matrix in
one call. Collapses the common reporting workflow (e.g. 3 metrics × 2 months ×
p50/p75 = 12 calls) into a small table of latest scalars (no history). Each
cell fails independently (errors[]); max_combos (default 24) caps the
fan-out; all calls share the rate limiter. See Batch aggregate.
Generic: query(query_type, app=None, params={...}, raw=False) — any
query-type with wire-name params, for cases the explicit tools don't cover.
Meta (anti-hallucination): list_apps, list_query_types,
describe_query(query_type, app=None) (pass app to include that app's custom
dimensions), list_custom_dimensions(app=None).
Output format
raw=false(default): a flat envelope —app,query_type,period,timezone,aggregation,drilldowns,empty,history_mode, andbody(the envelope-stripped data). Empty results are flagged, with a note when an unsupported drilldown combination is the likely cause.raw=true: mPulse's untouched JSON underdata.
history_mode — per-minute time-series volume (loss-free on demand). The
temporal query-types timers-metrics and by-minute return ~1,440 points/day,
of which the common workload uses only the period aggregate. history_mode
(on get_timers, get_metrics, and query) controls this:
mode | time series | always kept | ~size |
| ≤60 even-spaced points + |
| ~1/20 |
| dropped (endpoints only) |
| ~1/100 |
| every minute (loss-free) | everything | full |
The complete series is always recoverable via history_mode="full" or
raw=true. Aggregates are never reduced: latest (period value — read this
for monthly p75, don't average the history), mPulse statistics, histogram
buckets, and summary are kept in full regardless of mode. A peak
({index/x, value/y}) is added so "when did it spike?" survives downsampling.
timer/metric name resolution (input side). mPulse silently answers an
unrecognized timer/metric with a default (PageLoad) series instead of
erroring, so the explicit tools resolve these names against the catalog before
calling the API:
a casing/separator-only mismatch (
largest_contentful_paint→LargestContentfulPaint, endpoint-specific) is auto-corrected silently (zero extra round-trips); the fix is reported in acorrectionsfield;a genuinely unknown name is rejected with close suggestions (
Did you mean: …?) — the wrong name never reaches mPulse;custom timers/dimensions and the generic
querytool are left permissive (forward-compatible); if the catalog is unavailable, resolution is skipped.
Custom dimension support is endpoint-specific. A custom dimension (e.g.
branch) is accepted only by metrics-by-dimension (as its dimension
split value). dimension-values and dimension-over-time accept built-in
dimensions only — a custom name there returns empty/400 (a wasted call). The
query tool enforces this: a custom dimension on those two query-types is
rejected up front with a redirect to metrics-by-dimension, while a
built-in's casing is auto-corrected. describe_query reports
custom_dimension_supported per query-type so the model knows before calling.
For an app's declared custom dimensions (see Configure → Custom dimensions),
the query tool additionally normalizes the label to its wire form
(mobile speed → mobile_speed) for both the split value and
custom-dimension-<label> filters, and adds a soft dimension_notes advisory
when a name isn't in the declared set — but always passes it through (the
declared list may be incomplete). list_custom_dimensions(app) and
describe_query(query_type, app) expose the declared names so the model uses
the exact label instead of guessing.
Passing multiple values (mechanism differs per parameter). Verified against every endpoint's reference doc:
Comma-separated, one param — only
metricsonmetrics-by-dimension(plural param name; the singularmetricis silently ignored). Pass a pre-joined string:"metrics": "beacons,largest_contentful_paint".Repeated key —
metric/timerontimers-metricsand every drilldown filter (country,browser,ab-test, …) andcustom-dimension-<label>. Pass a JSON list and the client expands it to repeated query keys:"custom-dimension-branch": ["uk","us","sec"]→custom-dimension-branch=uk&…=us&…=sec(verified live). A Python-list-repr no longer leaks onto the wire.Single value —
dimension,percentile,metriconmetric-per-page-load-time(its own enum:BounceRate+CustomMetric0-9), etc.
describe_query surfaces a parameter_mechanics block (which params are
comma-separated vs repeat-key) plus an endpoint_params block — the
per-endpoint contract compiled from every reference page: value params with
defaults, special params (limit, sortby, interval, series-format) with
ranges, whether drilldown filters apply, and constraints. So the model knows,
before calling, e.g. that metrics-by-dimension takes native sortby/limit
(1-100, not valid for page_group/browser/country/bw_block/ab_test), computes
percentiles, and returns a {columnNames, data:[[…]]} table; that
dimension-values accepts no filters; that dimension-over-time has its own
dimension enum plus interval/limit (1-10); that metric-per-page-load-time
uses a distinct single metric; and that the report endpoints (geography,
page-groups, browsers, ab-tests, bandwidth) have no native
limit/sortby (use the client-side limit).
Silent-fallback warning (output side). As a backstop for cases input
resolution can't catch, when the series id/name echoed in the response does not
match the requested timer/metric, the result carries a warning so the
caller knows the data is not for the requested name. Casing/separator-only
differences are treated as a match and never warn. The warning is additive
metadata and appears in raw mode too (data stays untouched).
Payload instrumentation. Every successful query logs
payload app=… query=… bytes=… points=… to stderr, for measuring response
size / token cost (e.g. before/after future history-reduction work).
limit — high-cardinality caps. dimension-values, geography,
page-groups, browsers, … can return hundreds–thousands of rows (verified
live: ~215 countries for geography, ~1,400 values for dimension-values
browser). On the query tool these query-types are capped at 100 by default
(pass an explicit limit to change it); when trimmed, the result carries
truncated: {key, total, returned[, sorted_by]} so nothing silently disappears.
When the rows carry a count field (e.g. geography's timerN), they are sorted
by volume descending before trimming (sorted_by), so the top markets survive
rather than an alphabetical slice; rows without a count (dimension-values'
strings) keep their order. raw=true is never trimmed.
empty_reason + probe — why is it empty? An unsupported drilldown
combination and genuine no-traffic both come back empty. Every empty result now
carries an empty_reason heuristic (no_data / likely_no_traffic /
possibly_unsupported_combo) at zero cost. Pass probe=true (on the explicit
tools or query) to spend one extra drilldown-free query and get a
definitive unsupported_combo vs no_traffic, reported in a probe block.
Batch aggregate
get_aggregate runs a matrix of timers-metrics queries and returns only each
cell's period aggregate (latest) — the value you'd read for a monthly p75.
get_aggregate(
metrics=["TotalRequestCount", "TotalTransferSize"],
periods=[
{"date_comparator": "Between", "date_start": "2026-06-01",
"date_end": "2026-07-01", "label": "June"}, // date_end exclusive
{"date_comparator": "Between", "date_start": "2026-07-01",
"date_end": "2026-08-01", "label": "July"}
],
percentiles=[50, 75]
)
// -> { "table": [ {"target":"TotalRequestCount","period":"June",
// "percentile":75,"value":142}, … 8 rows … ],
// "percentiles":[50,75], "targets":[…] }Period objects are {date: "YYYY-MM-DD"} or {date_comparator: …} (Between
needs date_start+date_end; Last needs trailing_seconds); label names
the column. Names are validated/auto-corrected up front (one error, not N).
A cell that fails lands in errors[] with its coordinates while the rest
return; max_combos (default 24) guards targets × periods × percentiles.
Constraints surfaced to the model
One calendar day per query (ranges are rejected with guidance to split into per-day calls — the server does not fan out implicitly); per-minute aggregation; timezone-dependent; unsupported drilldown combinations return empty data.
Errors
401 → one automatic token re-issue + replay, then an auth error. 403 →
mPulse Lite / permission guidance (the Query API is not available on Lite).
429 → exponential backoff + jitter (up to 5 retries), then a rate-limit error.
Network/timeout/5xx → retried, then a friendly upstream error. Invalid
app/query-type/params → validation errors with hints. No error message ever
contains a secret.
Tests
uv run pytest # unit tests (respx-mocked; no network)Covers: token mint/cache/expiry/refresh + single-flight, Authentication
header, 401 replay, 429 backoff, 403→Lite mapping, loss-free normalization,
date/date_comparator mutual exclusivity, and multi-app / default fallback.
Manual smoke test against the real API:
export MPULSE_API_TOKEN=... # or rely on your .env / shell env
export MPULSE_APPS_CONFIG=/Users/hyoon/Projects/mpulse-mcp/mpulse_apps.json
uv run python tests/smoke.py # default app, yesterday
uv run python tests/smoke.py app-b 2026-08-01Project layout
src/mpulse_mcp/
server.py FastMCP instance + tool registration (entry point)
config.py app registry + credential loading
auth.py token mint/cache/refresh (single-flight)
client.py HTTP client + rate limiting + retries
query_types.py query-type / parameter metadata
formatting.py loss-free normalization + raw passthrough
errors.py typed exceptions + status mapping
tests/ unit tests + smoke.pyAvailable Tools
8 toolsdescribe_queryA
Describe a query-type: parameters, drilldowns, response shape, and caveats.
Pass a slug from list_query_types (e.g. summary, timers-metrics,
geography).
Inputs: query_type (required). Returns: object
get_histogramA
Distribution (histogram buckets) for one timer over the period.
mPulse query-type: histogram. Returns per-bucket counts plus median/p95/
p98. Time selection and drilldowns behave exactly as in get_summary
(single calendar day OR relative date_comparator).
Use raw=True for untouched mPulse JSON. Bucket counts are preserved
losslessly.
Inputs: app, raw, date, timer, +10 more. Returns: object
get_metricsA
Multiple timers/metrics by minute over time.
mPulse query-type: timers-metrics. metric defaults to Beacons, timer
to PageLoad. Returns values:[{id, history:[...per-minute...], latest}]
plus the data timezone.
Time selection and drilldowns behave as in the other tools (single calendar
day OR relative date_comparator). Numbers are preserved losslessly.
Inputs: app, raw, date, timer, +11 more. Returns: object
get_summaryA
Aggregate summary stats for one timer (median, margin-of-error, count, p95, p98).
mPulse query-type: summary. Data is per-minute aggregated over a single
calendar day in the given timezone (default UTC).
Time selection (exactly one required):
date— a single calendar day,YYYY-MM-DD.date_comparator— a relative window, e.g.Last24Hours,LastHour. A date range is not supported per call; split it into per-day calls.
Timer: timer (built-in, default PageLoad) OR custom_timer (a custom
timer name). percentile is 1–99 (default 50).
Drilldowns filter the data (e.g. page_group, browser, country,
device_type, ab_test). Unsupported combinations return empty data with a
note rather than an error.
Set raw=True to get mPulse's untouched JSON. Numeric values are never
rounded or summarized.
Inputs: os, app, raw, date, +14 more. Returns: object
get_timersA
A single timer's value by minute over time (time series).
mPulse query-type: by-minute. Best for one timer (built-in timer,
default PageLoad, or a custom_timer). For multiple timers/metrics at
once, use get_metrics (query-type timers-metrics).
Returns a series of {x, y} points at per-minute resolution for the selected
calendar day (or date_comparator window). Values are preserved exactly.
Inputs: app, raw, date, timer, +10 more. Returns: object
list_appsA
List registered mPulse apps and the default app.
Use this before other tools so you reference real app names. The app
argument on every tool is optional and falls back to the default.
Inputs: no named parameters. Returns: object
list_query_typesA
List the mPulse query-types this server knows about, with one-line summaries.
The explicit tools cover: summary→get_summary, histogram→get_histogram,
by-minute→get_timers, timers-metrics→get_metrics. Everything else is
reachable via the generic query tool.
Inputs: no named parameters. Returns: object
queryA
Call an arbitrary mPulse query-type with arbitrary parameters.
Use this for query-types not covered by the explicit tools (see
list_query_types), e.g. dimension-values, geography, page-groups,
app-error-summary.
params is a dict of mPulse wire parameter names (hyphenated), e.g.
{"date-comparator": "Last24Hours", "page-group": "Home", "timer": "PageLoad"}. format=json is added automatically. Remember the one-
calendar-day-per-query constraint.
raw=True returns mPulse's untouched JSON.
Inputs: query_type (required), app, raw, params. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clear, distinct role: summary/histogram/time-series/metrics cover different data shapes, query is explicitly for uncovered query-types, and list_apps/list_query_types/describe_query are discovery aids. No two tools appear interchangeable.
Tool names follow a predictable verb_noun pattern: get_* for data retrieval, list_* for enumeration, describe_* for details, and a single 'query' for generic access. The style is uniform and intuitive.
Eight tools is well-scoped for an analytics server: four query-specific getters, one generic fallback, and three utility/metadata tools. Each tool earns its place without redundancy or bloat.
The server covers the core mPulse analytics surface (summary, histogram, time series) and provides a generic query tool for any undiscovered query-type, plus list/describe tools for self-discovery. No obvious gaps; agents can handle arbitrary query-types without dead ends.
Related MCP Connectors
MCP server for the Seline Analytics API
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Access New Relic observability data through MCP - query metrics, logs, traces, entities, and more
MCP server for Riveter's enrichment, scraping, and monitoring API
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only MCP server for Umami analytics. It talks to the Umami REST API directly over HTTP, supporting self-hosted and cloud setups.88 npmMIT
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server for querying telemetry data from configurable backends. Provides tools to list sources, describe schemas, run bounded queries, and compute aggregates.MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for interacting with Rustici LRS via xAPI, enabling statement retrieval, analytics, and aggregation operations.-
- AlicenseNot gradedqualityDmaintenanceMCP server for Microsoft Clarity Data Export API, providing tools to retrieve traffic, popular pages, engagement metrics, and user behavior insights such as dead clicks, rage clicks, and script errors. Supports multiple projects with daily quota management and shared caching.MIT