This server provides read-only account-health intelligence through six MCP tools that pull from the same data pipeline as the dashboards.
Get health score: retrieve the operational health report for internal or customer audience (customer view is scrubbed of internal fields).
Get metric trends: query daily values plus last-7/first-7 means for any supported numeric metric (e.g. requests, latency, error rate, CSAT, spend).
Get claims check: verify the three headline claims against telemetry data.
Get risks: list top-N risks ranked by severity × likelihood, filtered by audience visibility.
Get expansion pipeline: see the ranked brand-expansion pipeline (internal details omitted for customer).
Get next actions: list joint or internal next actions visible to the requested audience.
Click on "Install 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., "@lodestar Show the account health score and top risks for Northstar."
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.
Account-health instrumentation for an AI support deployment: one core computes every number once, and two audience-scoped dashboards, an MCP server, a JSON API and an executive-brief generator all read from it, so the internal team, the customer's leadership and the executive brief tell one story from one telemetry file, and nothing internal reaches the customer by construction.
Built for the Fireworks AI take-home ("Northstar Retail Group: EBR, Internal QBR & Account Health"): one 31-day telemetry file for a fine-tuned customer-support deployment, three audiences, three coordinated deliverables.
Source code is private. This public repository carries the README, the measured results card, screenshots of both dashboards, the design documents, the executive brief, the assumptions register and the delivery evidence. The full repository (Python package, Streamlit app, MCP server, API, 251 tests, one check gate, CI) lives in a private repository and is shared with reviewers on request: roshan.s.rana@gmail.com.
The problem | Three audiences need the same evidence told three ways: a candid internal QBR, a polished customer account-health view, and an executive brief with a credible expansion case. Every figure has to agree, and internal judgement must never leak to the customer. |
What it does | A transparent five-pillar health score with published floors, targets and weights; a headline-claim checker that separates what telemetry proves from what needs a baseline; rolling-threshold incident detection; an audience-tagged risk register; a four-brand expansion model that ranks the pilot; an EBR generator on Fireworks (OpenAI-compatible) or Anthropic behind a leak guard, deterministic offline by default. |
Stack | Python 3.12, |
Validation | One gate: ruff, mypy strict (host and Linux target), pytest with an 80% floor (251 tests, 97% coverage), secrets scan, deterministic bench, README card drift check. CI runs the same gate. |
Related MCP server: Churn Solution MCP Server
Every figure below was observed by the offline bench in the private source repository (fixed seed, no API key) and written to metrics/headline.json, which is committed here. Every figure computed from the 31-day Northstar telemetry by the same functions that drive both dashboards, the MCP server and the EBR. Rows marked pending need hardware, data or a service the offline harness does not have; nothing here is estimated.
Metric | Value | How it was measured |
Operational health | 80.2 / 100 | Weighted L7 composite across five pillars; rated healthy. |
Headline claims | 1 of 3 from telemetry alone | 3 of 3 reproduce with the stated baselines (assumed, owner Northstar CX ops) |
Internal fields in customer view | 0 of 37 | Customer AccountView scrubbed of every internal-tagged field before it leaves AccountView.build. |
Incident days detected | 2 of 2 | Detector-flagged days matched against the dataset's own incident annotations. |
Weakest pillar | Spend efficiency 65.8 | Lowest-scoring of the five weighted pillars in the operational composite. |
Inference cost per automated ticket | $0.0124 | Month total spend divided by month total automated Tier-1 tickets. |
Pillar scores (L7 window)
Adoption |
| 80.2 / 100 |
Reliability |
| 87.2 / 100 |
Latency |
| 78.5 / 100 |
Quality |
| 83.1 / 100 |
Spend efficiency |
| 65.8 / 100 |
Evidence checked offline
Status | Evidence | |
MCP tools exercised | observed | 6 of 6 |
API routes | observed | 6 of 6 |
EBR sections present | observed | 8 of 8 |
Days below proposed SLO | observed | 27 of 31 at 99.9% |
Request vs automated growth | observed | requests ×1.45 vs automated tickets ×1.15 (L7/F7) |
Live provider narrative | pending | not run offline |
Customer · Account health (for Northstar's VP Customer Experience and VP Engineering): outcome tiles with their assumed-baseline caveats, the operational health score, usage and reliability trends with incident shading, quality trends, spend against budget, customer-visible risks and joint next steps, and the expansion opportunity. Zero internal fields reach this view; the bench measures it.
Internal · QBR (Fireworks account, engineering and leadership): internal composite with a relationship pillar, health breakdown with methodology, five trend charts, top-3 risks with evidence, expansion pipeline with confidence and blockers, dependencies, support burden, competitive notes, decisions needed, next actions with owners and dates, stakeholder coverage.
Every model field carries a visibility tag that fails closed (untagged means internal). One scrub() function drops internal fields for the customer audience, and the customer page, the JSON API, the six MCP tools and the EBR generator can only receive the scrubbed view. A recursive leak test walks every model reachable from the account view; the bench publishes the count (0 of 37 internal field definitions populated in the customer view) and CI fails if it changes. Model prose passes a deny-list guard for internal terms and internal figures before it is used, with an offline fallback. Residual risk, paraphrase, is disclosed in the threat model.
Last-7-day window scored against the first 7 days as trend reference. Each metric scores 0–100 by linear interpolation between a published floor and target; pillars average their metrics; the operational composite is the weighted sum (reliability 0.25, quality 0.25, adoption 0.20, latency 0.15, spend efficiency 0.15). Bands: healthy ≥ 80, watch 65–79.99, at risk < 65. On the shipped telemetry: 80.2, healthy, with spend efficiency the weakest pillar at 65.8. The full table and worked arithmetic are in docs/design-document.md.
Path | What |
Screenshots, audience and purpose of each view, metric choices, health-score arithmetic, internal vs customer differences, exclusions, trade-offs | |
Executive Business Review: narrative, metric context, expansion recommendation, scaling architecture, pilot, budget and timeline, talking points, biggest risk | |
Every assumption with value, basis, owner and where it surfaces | |
What it is and why; a guided tour with the commands (runnable against the private source) | |
Problem brief, requirements, HLD, threat model, LLD with frozen contracts, execution plan, ADRs | |
14 task packs, each with an independent verifier's verdict | |
Hash-chained gate and task evidence (25 entries) | |
Controls C-01..C-17 with evidence and live probes; what shipped, what was measured, what was not run | |
The code knowledge graph agents query instead of grepping, with three real queries | |
The observed figures the results card is rendered from | |
The three YAML context files (assumptions, brand profiles, account context); brand and relationship data are fictional and labelled as such |
Under a gated delivery lifecycle: design documents frozen before code, one task pack per change, every task implemented by one model context and verified by a fresh one in an isolated git worktree, a hash-chained evidence ledger, a security review with live probes, and a retrospective ADR. Design and orchestration ran on a frontier model; all implementation and verification ran on Sonnet-class models. No task needed a second attempt.
MIT. Brand profiles and account context are fictional; the telemetry was supplied with the exercise.
The three headline-claim checks (no internal fields exist on ClaimCheck).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. 'The three headline-claim checks' weakly implies a read-only retrieval, but the description does not disclose whether results are cached, computed on demand, require prior state, or return arbitrary historical data. The parenthetical about ClaimCheck internal fields is cryptic, not an informative behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main subject, but the parenthetical at the end is cryptic and adds little. It earns a middling score because it is compact yet not self-explanatory.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are no parameters, the tool is trivially callable/myfreecams, and the output schema is marked present, the main missing piece is a clear statement of what the three headline-claim checks are and when to use them. The parenthetical provides a small structural hint but does not explain return semantics or use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters defining a 100% schema coverage baseline, so the description is not required to explain parameter details. The brief mention of 'no internal fields' attempts to describe the shape of the returned ClaimCheck, but does not provide actionable parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the subject ('the three headline-claim checks') but never states an action—it is a noun phrase, not a sentence like 'returns' or 'retrieves'. It distinguishes the payload from sibling get_* tools by name, but not by explicit behavior. It contains a confusing parenthetical ('no internal fields exist on ClaimCheck') that is not explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to call this tool versus get_health_score, get_metric_trend, or get_risks. The description implies the tool returns claim checks, but it never states contexts, exclusions, or alternatives. There is no misleading guidance, but the agent is left to infer everything.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The ranked brand expansion pipeline, scrubbed of internal fields for customer.
| Name | Required | Description | Default |
|---|---|---|---|
| audience | No | customer |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose that the output is ranked and that customer-facing output is scrubbed of internal fields, which is useful behavioral context. However, it does not mention side effects, authorization, or any other operational traits; as a read-style tool this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, and the core resource phrase is front-loaded. It loses one point because the noun-phrase structure is slightly less actionable than a clear verb-led instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity—one optional enum parameter and an output schema present—the description is mostly adequate. It communicates the core product and the customer-scrubbing behavior, but lacks any usage context or sibling differentiation that would help an agent decide when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It hints at the audience parameter by saying the pipeline is 'scrubbed of internal fields for customer,' implying the customer variant differs from internal. But it never names the parameter or explicitly explains the internal/customer distinction, leaving part of the semantic burden on the enum labels alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific resource ('ranked brand expansion pipeline') and adds a scoping detail ('scrubbed of internal fields for customer'). The name's 'get' verb conveys retrieval, and the resource is distinct from siblings like get_risks and get_next_actions. It falls short of a 5 because it is phrased as a noun phrase rather than an explicit action statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus its siblings, and no conditions or exclusions are stated. The audience default is discoverable from the schema, but the description does not explain when the internal vs. customer variant is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The operational health report for audience, scrubbed of internal fields for customer.
| Name | Required | Description | Default |
|---|---|---|---|
| audience | No | customer |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It adds a meaningful behavioral detail—'scrubbed of internal fields for customer'—which tells the agent that output content changes by audience. It does not go further to discuss authentication, latency, or what 'operational health' includes, so transparency is only partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence that front-loads the tool's purpose before the parameter-specific scrub detail. Every word earns its place; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema available, the description covers the core purpose and the main behavior difference by audience. It omits sibling differentiation and explicit usage conditions, but the availability of an output schema reduces the burden of describing return shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description directly addresses the single `audience` parameter by tying it to the report and explaining that customer output is scrubbed of internal fields. This adds value beyond the raw enum values and default, though it doesn't explicitly define what an internal audience receives.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the tool produces an 'operational health report' scoped by `audience`, which identifies the resource and intent clearly. It distinguishes itself from trend/risks/claims siblings by naming a distinct report type, though it doesn't explicitly say 'returns' or 'gets' and doesn't name the alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives audience context and mentions scrubbing for customer, so there is an implied target use, but it provides no explicit when-to-use guidance or exclusions relative to siblings like get_metric_trend or get_risks. An agent is left to infer the right selection from the name and phrase 'operational health report.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily values for one numeric DayRow metric, plus the L7 (last 7) and F7 (first 7) means.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | ||
| audience | No | customer |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns daily values and L7/F7 means, which is a basic behavioral summary. However, with no annotations provided, the description carries the full burden and does not mention operational facts like computation of the means, time range, or output shape beyond the schema. It adds some value by defining what is returned, but not enough for a mutation-free read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, and it front-loads the principal output ('Daily values') before the aggregate details. Every phrase contributes to clarifying the data set. It is concise without losing useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description leaves important gaps: the 'audience' parameter is doubly unexplained (schema also has no description), the L7/F7 definitions are not expanded, and the expected date range is not indicated. The combination of a missing parameter explanation and no annotations makes the description incomplete for a confident invocation of this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the actual parameters: 'audience' is solely mentioned in the schema, and the description's phrase 'one numeric DayRow metric' maps vaguely to 'metric'. With schema description coverage at 0%, the description was responsible for compensating, but it does not define either parameter or how the audience filter affects the output. This leaves the agent unable to correctly choose the metric or understand the audience scope beyond guessing from enum names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's output ('Daily values' for a metric plus L7/F7 means), which maps to a specific verb-resource: retrieving a metric trend. It does not explicitly say 'returns' or 'retrieves', but the tool name and described outcomes make the purpose clear. It is also distinct from the sibling tools about health scores, claims, risks, and expansion, which improves clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus the sibling tools. It implies the result is daily metric data but never states 'use this when you need a daily trend' or names any alternative. An agent must infer that this is the only tool for metric trends, which is left to inference rather than explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The joint/internal next actions visible to audience.
| Name | Required | Description | Default |
|---|---|---|---|
| audience | No | customer |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, and the description does not disclose side effects, read-only guarantees, error behavior, or visibility semantics. 'Visible to audience' hints at filtering but does not explain what happens for each audience value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one compact, front-loaded sentence. No filler. It could be clearer, but it is efficiently structured and does not bury the key parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and an opaque 'joint/internal' qualifier, the description leaves too much unexplained: what makes an action 'joint' or 'internal', whether the output is a list or a single recommendation, and how `audience` affects results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description at least ties `audience` to the visibility of results, which adds some meaning beyond the raw enum. However, it does not clarify the 'internal' vs 'customer' values or the meaning of 'joint'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource ('joint/internal next actions') and ties it to the `audience` parameter, and the resource name distinguishes it from sibling tools like get_risks and get_expansion_pipeline. However, it is a noun phrase rather than an explicit action, and the term 'joint/internal' is ambiguous, so an agent cannot be certain what is being returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to prefer this tool over alternatives, how to choose between 'internal' and 'customer', or what qualifies as a 'next action'. The only usage hint is 'visible to audience', which is too weak to route an agent reliably.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The top top_n risks visible to audience, ranked by severity x likelihood.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | ||
| audience | No | customer |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that results are ranked and filtered by audience, which is useful. However, it does not explicitly state read-only behavior, authentication requirements, or any side effects, though the 'get' verb implies a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 13-word sentence with no waste, front-loaded with the main action and parameters. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two optional parameters) and the presence of an output schema, the description covers purpose, ranking, and filtering adequately. It lacks error conditions or prerequisites, but for a simple read operation this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains both parameters: top_n as the count and audience as the visibility filter. This adds meaning beyond the schema's types and defaults, effectively compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get'), resource ('risks'), and the ranking logic (severity x likelihood), clearly distinguishing it from siblings like get_health_score or get_metric_trend. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on what the tool returns but does not explicitly state when to use it over alternatives or when not to use it. No exclusions or comparisons are given, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_claims_checkget_expansion_pipelineget_health_scoreget_metric_trendget_next_actionsget_risksScored across 6 tools
Each tool returns a uniquely identifiable report or metric type (health, trend, claims, risks, pipeline, actions). No two tools appear to serve the same purpose, and the descriptor nouns clearly delimit their boundaries.
All tool names follow a uniform get_<report_noun> pattern. The naming is predictable and scannable, with no mixing of verb styles or casing conventions.
Six tools form a tight, well-scoped set for a read-only analytics reporting server. Each tool earns its place by exposing a distinct report surface without redundancy or bloat.
The set covers the primary report types implied by the server's purpose: health, trends, claims, risks, pipeline, and actions. A possible minor gap is an all-reports overview or metadata listing, but the core reporting surface feels complete for its domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only account intelligence for Customer Success and Account Management teams.
Inspect an approved ad account and first-party signal health, then propose policy-gated actions.
Read-only, deterministic AI triage and readiness tools implementing Sophon's published rubrics.
Read-only access to your VortexIQ store data: audits, KPIs, alerts, Brand DNA, reports, Ask VIQ.
