mcpulse-typescript MCP server
Commit Oct 18, 2026Provides analytics for MCP servers to track tool usage, model understanding, and cross-tool data agreement.
Also known as getmcpulse/mcpulse-typescript
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 18, 2026
- License
- MIT
What is mcpulse-typescript MCP?
mcpulse-typescript provides analytics for MCP servers to track tool usage, model understanding, and cross-tool data agreement.
Summary generated from the project's README
About mcpulse-typescript MCP server
Developers building Model Context Protocol servers can use this TypeScript SDK to gain visibility into how their tools perform in real-world scenarios. It tracks tool usage, model understanding, and whether tool descriptions are effective, providing data that is typically invisible to server publishers. By integrating the watch function into a server setup, you can monitor call outcomes like successful runs, schema validation failures, tool errors, or crashes.
This SDK is designed to be lightweight and non-blocking, ensuring that analytics never delay a model's response or consume excessive memory. It works with both stdio and HTTP transport methods, requiring only a single ingest key provided via environment variables. A unique feature is the cross-tool agreement monitoring, which detects when two different tools return conflicting data for the same underlying field. This comparison happens locally within your process to ensure privacy, as only the final verdict is sent to the dashboard.
What you can do with it
- 1Monitor tool performanceTrack how many times specific tools are called and whether they return empty results that provide no value to the model.
- 2Detect data inconsistenciesIdentify when two separate tools provide different answers to the same question due to stale caches or version mismatches.
- 3Debug tool execution errorsDistinguish between a tool that intentionally returns an error and one that actually crashes during execution.
- 4Analyze model interactionDetermine if the model is successfully using your tools by monitoring argument validation and call outcomes.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
MCPULSE_KEY
Automated checks
Ran Nov 15, 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 reachablegetmcpulse/mcpulse-typescript is public and reachablegithub.com/getmcpulse/mcpulse-typescript ↗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-10-18github.com/getmcpulse/mcpulse-typescript ↗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 model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@mcpulse/sdk
Analytics for MCP servers. Tells you whether your tools actually work for the models calling them.
getmcpulse.com · Docs · Dashboard
You publish an MCP server and can see nothing: not how many people use it, not which tools get called, not whether the model understands your descriptions, not what your server costs the people running it. This package is how that data gets out.
Install
npm install @mcpulse/sdk
Use
One import, one wrap, after your tools are registered. watch returns the same
server, so nothing downstream changes.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { watch } from "@mcpulse/sdk";
const server = new McpServer({ name: "my-server", version: "1.0.0" });
// … your registerTool calls …
watch(server, { key: process.env.MCPULSE_KEY });
await server.connect(new StdioServerTransport());
Serving over HTTP
A streamable-HTTP server builds a fresh McpServer for every request, so there
is no long-lived instance to wrap. Wrap it inside the factory instead, beside
the tool registration:
function createServer() {
const server = new McpServer({ name: "my-server", version: "1.0.0" });
// … your registerTool calls …
return watch(server, { key: process.env.MCPULSE_KEY });
}
Calling watch once per request is expected and cheap. The session and its
buffer are shared for the life of the process, so your calls stay grouped into
one session rather than one per request — which is what keeps retries and
first-call success meaningful.
Get a key by creating an MCP at app.getmcpulse.com — it is shown once, at creation.
Options
| Option | Default | |
|---|---|---|
key |
— | Ingest key, mp_live_…. Without one the SDK does nothing. |
debug |
false |
Log what is sent, to stderr — never stdout, which is the transport. |
agree |
off | Fields that more than one tool returns. See below. |
agreeOptions |
— | windowMs (5 min) and tolerance (0.0001) for agree. |
watch(server, {
key: process.env.MCPULSE_KEY ?? "",
debug: true,
});
Cross-tool agreement
Opt-in, and it catches the failure every other metric here calls healthy.
Two tools return the same underlying field. A stale cache key, or a versioned key a cron did not follow, and they disagree for hours. Every number stays green the whole time — the calls succeed, the results are non-empty, there are no retries and the latency is fine. Callers get two different answers to one question and nothing reports it.
Name the value once, and say where each tool returns it:
watch(server, {
key: process.env.MCPULSE_KEY ?? "",
agree: {
global_liquidity: [
{ tool: "getGlobalLiquidity", path: "globalLiquidity.value_t" },
{ tool: "getPillars", path: "pillars.global_liquidity.value" },
],
vix: [
{ tool: "getVix", path: "vix.value" },
{ tool: "getPillars", path: "pillars.vix.value" },
],
},
agreeOptions: {
windowMs: 300_000, // how long a value stays comparable
tolerance: 0.0001, // relative, for floats
},
});
A map rather than a list of field names, because the same value routinely ships under a different name and a different shape in each tool — which is most of why two copies of it drift apart without anyone noticing.
The comparison happens in your process, and only the verdict is sent.
{
"v": 1,
"type": "agreement",
"session_id": "s_7f2a91",
"field": "global_liquidity",
"tool_a": "getGlobalLiquidity",
"tool_b": "getPillars",
"agreed": false,
"checked_at": "2026-09-11T14:22:31Z",
"window_ms": 300000
}
No value, no difference, no hash of a value. Hashing could not work anyway:
25.22, 25.220 and "25.22" are the same number and three different hashes,
so a server-side check would report every representation change as a divergence
forever. Comparing numerically needs the values, and comparing them where they
already are is the only way to have both.
Four things worth knowing before turning it on:
windowMsmust be shorter than your data's refresh interval. A window that outlives a refresh compares a figure against its own predecessor and calls a legitimate change a divergence. It also has to be long enough that both tools are plausibly called inside it.- Integers and strings are compared exactly.
toleranceis relative and applies to floats only — a count that is off by one is off by one. - Nothing is reported until both tools have been called inside one window.
A low-traffic tool can stay silently wrong for a long time, which is a limit
of the method rather than a clean result. Run once with
debug: trueafter setting it up: a path that never resolves says so there, which is how a typo'd declaration shows up as something other than a passing check. - The path is searched in
structuredContent, in the JSON of a text content part, and in the result itself, so it does not matter which envelope your tool returns.
What leaves your process
Per tool call:
{
"v": 1,
"type": "call",
"session_id": "s_7f2a91",
"tool_name": "search_orders",
"client_name": "claude-desktop",
"started_at": "2026-08-09T14:22:31Z",
"duration_ms": 240,
"outcome": "ok",
"response_bytes": 1420,
"is_empty": false,
"args_hash": "9c1b4e2f0a11"
}
And once at startup, the tool list with the byte size of each schema.
Never the arguments. Never the results. args_hash is twelve hex characters
of a SHA-256 over the arguments with keys sorted — enough to tell whether two
calls used the same arguments, and not enough for anything else. There is no
option that turns this off, because the guarantee is only worth something if it
cannot be switched off.
Outcomes
Every call ends as exactly one of these:
ok |
Ran and returned a result. |
bad_args |
Arguments failed schema validation — your handler never ran. |
tool_error |
Ran and returned isError: true. |
crashed |
Threw. |
Telling crashed from tool_error takes some doing. McpServer catches
everything a tool does and converts it into { isError: true }, so from outside
its request handler a crash, a returned error and a rejected set of arguments
are the same object. The SDK wraps your tool callbacks as well as the request,
so what actually happened is known rather than guessed from an error message.
is_empty marks a call that succeeded and returned nothing useful — an empty
array, an empty object, a blank string. Those are the failures nobody reports:
the protocol calls them success, the model gets nothing it can use, and you
never hear about it.
The three rules
- Never throw. Every entry point swallows. If MCPulse fails inside your tool call, your tool fails and you blame us — so if instrumentation cannot be attached, your server is handed back untouched and runs without analytics.
- Never block. Record, buffer, return. Nothing awaits the network on the path a model is waiting on.
- Never store customer data. Sizes and hashes only.
Payloads are batched and sent every 5 seconds or every 30 calls, whichever comes first, with a final flush on the way out. If the network is down the batch is dropped rather than retried — the buffer is capped at 1000 and sheds the oldest first, because your server running out of memory over our analytics is the one failure we must never cause.
Requirements
Node 20.12 or newer, and @modelcontextprotocol/sdk as a peer dependency —
whatever version your server already uses.
Try it
examples/test-server is a real MCP server with one tool per behaviour: fast,
slow, empty, error, crash, and one registered but never called so dead-tool
detection has something to find.
cd examples/test-server
pnpm install
MCPULSE_KEY=mp_live_… pnpm exercise
pnpm exercise drives every behaviour once through a real MCP client and waits
for the send. pnpm start runs the same server over stdio for a real client to
connect to.
Read it back in Claude
This package sends the data out. The dashboard is one way to read it and MCPulse's
own MCP server is another — connect it and an agent answers "how is
search_orders doing for Cursor" against your own account, with your own
window. It is on every plan, free included.
Sign-in is OAuth, so there is no key to copy or leak. Setup: docs.getmcpulse.com/mcp/connect, or add it from the Smithery listing.
Licence
MIT
mcpulse-typescript MCP questions
Does the SDK send sensitive tool arguments or results?
No, the SDK never sends arguments or results. It only sends metadata like tool names, durations, outcomes, and argument hashes.
How does the SDK handle cross-tool data agreement?
It allows you to opt-in to checking if two different tools return the same underlying value within a specified time window and tolerance.
What happens if the analytics network is down?
The SDK batches payloads and, if the network is unavailable, the batch is dropped to prevent memory issues on your server.