Page 3 of 7 · Server reference
finops-focus-mcp
An agentic interface to the FOCUS™ specification (the FinOps Open Cost & Usage Specification): every column and cross-cutting attribute, pinned at two spec versions, with normative requirements, keyword search, an unofficial cross-version diff, and an unofficial layer mapping FinOps Framework KPIs onto the FOCUS columns that compute them.
focus · list_versions {}
Version model
Two spec versions are pinned and served side by side. The server's own index call states the shape directly:
1.2 (latest): 57 columns, 9 attributes (source v1.2)”
| Version | Source tag | Data version | Latest? | Columns | Attributes |
|---|---|---|---|---|---|
| 1.0 | v1.0 | 1.0.1 | — | 43 | 9 |
| 1.2 | v1.2 | 1.0.1 | latest | 57 | 9 |
Every version-aware tool takes an optional
version string parameter ("1.0" or "1.2") that
defaults to "1.2" when omitted — so a first-call agent that never passes
version always lands on the current spec, and must opt in explicitly to see
the 1.0 shape of a column, attribute, or requirement. compare_versions is the
one exception: it has no version parameter because it always compares the two
pinned versions (1.0 → 1.2) in a fixed direction.
focus · list_versions {} → structuredContent.latest, structuredContent.versions[]
Tool tour
9 tools, grouped by what they're for. Names and parameters below are verified against
the live tools/list response (source: docs/mcp-surface.md,
re-checked against a live probe for this page).
| Tool | Purpose | Key params |
|---|---|---|
| list_versions | Every FOCUS spec version served, with source git tag and column/attribute counts. Start here to discover valid version values. | — (no params) |
| Tool | Purpose | Key params |
|---|---|---|
| get_column | Full record for one column: description, content constraints (type, feature level, nulls, data type, value format), allowed values, normative requirements, introduced-in version. | column (required, ID or slug); version (default "1.2") |
| list_columns | All columns for one version, optionally filtered by feature_level or column_type. Default limit returns the full list in one call (43 in 1.0, 57 in 1.2). | version (default "1.2"); feature_level: Mandatory|Conditional|Recommended|unknown; column_type: Metric|Dimension|unknown; limit (≤100, default 100); cursor |
| get_attribute | Full record for one cross-cutting attribute (naming/formatting conventions like currency codes, datetime format, key-value format): description, normative requirements, exceptions. | attribute (required, ID or slug); version (default "1.2") |
| Tool | Purpose | Key params |
|---|---|---|
| get_requirements | The normative MUST/SHOULD bullets for one column, verbatim from the spec text — nothing else (use get_column for the full record). | column (required, ID or slug); version (default "1.2") |
| Tool | Purpose | Key params |
|---|---|---|
| search_focus | Ranked keyword search over one version's columns and attributes. Returns slug + uri per hit — feed into get_column/get_attribute. | query (required, len ≥2); version (default "1.2"); entity_types: column|attribute; limit (≤50, default 10); cursor |
| Tool | Purpose | Key params |
|---|---|---|
| compare_versions UNOFFICIAL | The 1.0→1.2 column diff — an unofficial derivation computed by this server from the two tagged releases, source-cited per entry. Without column: the full diff (14 added, 0 removed, 43 changed). With column: that one column's status and detail. | column (optional, narrows to one column) |
There is no get_changelog tool on this server
(that name belongs to the framework server's crawl-changelog tool). What this server calls
a "changelog" is the upstream FOCUS project CHANGELOG, exposed per version as the
focus://spec/{version}/changelog resource — verbatim upstream
text, including the materiality caveat used to judge whether a "changed" entry from
compare_versions is actually semantic. See Prompts
& resources below.
| Tool | Purpose | Key params |
|---|---|---|
| get_kpi_mapping UNOFFICIAL | Derived mapping from framework KPIs (effective savings rate, commitment discounts, forecast accuracy, unit economics, allocation) to the FOCUS columns needed to compute each, with a FOCUS-terms formula translation. Not published or endorsed by the FinOps Foundation or the FOCUS project. | kpi, capability (filters); version (default "1.2") |
| calculate_kpi UNOFFICIAL | Computes one mapped KPI using this server's own derived formula, over a bundled sample dataset (official FOCUS 1.0 sample where available, else this project's seeded synthetic sample) — never user-supplied data. Not every mapped KPI has a registered formula; unsupported ones error with guidance instead of guessing. | kpi (required); version (default "1.2"); sample: official|synthetic |
A live example of the mapping tool, at 1.0, for the KPI this page's worked demo doesn't otherwise touch:
focus · get_kpi_mapping {kpi: "effective-savings-rate-percentage", version: "1.0"}
Prompts & resources
Prompts (3)
| Prompt | Purpose | Arguments |
|---|---|---|
| explain-focus | Guided orientation to FOCUS: what it standardizes, how versions differ, how to look up columns. | version (optional; default latest) |
| map-column-across-versions | For one Column ID, shows its record in each served version and the 1.0→1.2 diff status, citing sources. | column (required) |
| map-kpi-to-focus-columns UNOFFICIAL | Guides computing a framework KPI from FOCUS data: which columns it needs, the FOCUS-terms formula, and (where a formula is registered) the computed value over bundled sample data. | kpi, capability (optional filters); version (optional; default "1.2") |
focus · list-prompts (live probe, verbatim descriptions/arguments above)
Resources — focus://spec/…
3 fixed resources plus 4 URI templates (125 concrete resources listed when templates are expanded across both versions' columns and attributes, plus per-version glossary and changelog).
| URI | What it is | Type |
|---|---|---|
| focus://spec/overview | Start here: what this server covers, how to navigate its version-pinned tools | fixed |
| focus://spec/versions | Every FOCUS spec version served, with source tag and counts (JSON) | fixed, JSON |
| focus://spec/changes/1.0-1.2 UNOFFICIAL | Unofficial column diff between the two pinned spec versions, source-cited — the resource form of compare_versions {} | fixed |
| focus://spec/{version}/columns/{slug} | Full column record: description, content constraints, allowed values, normative requirements | template, completable |
| focus://spec/{version}/attributes/{slug} | Full attribute record: description, normative requirements, exceptions | template, completable |
| focus://spec/{version}/glossary | Term glossary for one spec version | template, completable |
| focus://spec/{version}/changelog | The upstream FOCUS project CHANGELOG for one spec version, verbatim — includes the upstream materiality caveat for judging whether a change is semantic | template, completable |
focus · list-resources · list-resource-templates (live probes, verbatim titles/descriptions/mimeTypes above)
Worked demo: BilledCost deep-dive
The chain an agent walks to understand one column across the spec's lifetime:
get_column for the 1.0 record, get_requirements for the 1.2
normative text, then compare_versions to see exactly what moved between them
— landing on the same column used in the demo.
get_column, version 1.0 official
BilledCost — Metric, feature level Mandatory, data type Decimal, introduced in spec version 0.5, nulls not allowed.
Its three 1.0 requirements, verbatim:
- The BilledCost column MUST be present in the billing data and MUST NOT be null.
- This column MUST be of type Decimal, MUST conform to Numeric Format, and be denominated in the BillingCurrency.
- The sum of the BilledCost for rows in a given billing period MUST match the sum of the invoices received for that billing period for a billing account.
focus · get_column {column: "BilledCost", version: "1.0"}
get_requirements, version 1.2 official
By 1.2 the requirement list has grown from three bullets to eight — new content, not just rewording. All eight, verbatim:
- BilledCost MUST be present in a FOCUS dataset.
- BilledCost MUST be of type Decimal.
- BilledCost MUST conform to NumericFormat requirements.
- BilledCost MUST NOT be null.
- BilledCost MUST be a valid decimal value.
- BilledCost MUST be 0 for charges where payments are received by a third party (e.g., marketplace transactions).
- BilledCost MUST be denominated in the BillingCurrency.
- The sum of the BilledCost for a given InvoiceId MUST match the sum of the payable amount provided in the corresponding invoice with the same id generated by the InvoiceIssuer.
That last bullet is new in substance: FOCUS 1.0 had no InvoiceId column at all — the reconciliation requirement that ties BilledCost to a specific invoice only becomes expressible once 1.2 adds InvoiceId as one of its 14 new columns (see step 3).
focus · get_requirements {column: "BilledCost", version: "1.2"}
compare_versions, full diff UNOFFICIAL
BilledCost itself is one of the 43 changed columns — changed_fields: ["description_md","requirements"] — which matches exactly what steps 1 and 2 just showed: the description was refined and the requirement list grew from 3 to 8 bullets, including the new InvoiceId-reconciliation bullet.
The 14 added columns, verbatim IDs from added_columns:
Zero removed columns means every 1.0 pipeline's column list still resolves in 1.2 — the risk in an upgrade is entirely in the 43 changed entries' requirements/description_md/ allowed_values fields, which is exactly why the tool's own caveat insists on checking materiality per column rather than treating "changed" as a breaking-change signal by default.
focus · compare_versions {} → structuredContent.added_columns (14), .removed_columns (0), .changed_columns (43)
What this demo shows
Three tool calls, zero invented data: one column's full 1.0 record, its expanded 1.2 normative text (including a requirement that is only possible because of a column FOCUS 1.2 introduced), and the server's own accounting of exactly what changed spec-wide between the two versions — with the materiality caveat surfaced, not hidden, so "43 changed" reads as "go check", not "43 breaking changes."
Next: see this server paired with finops-framework-mcp in the Rate Optimization (ESR) worked example, or jump to Showback for a columns-driven reporting walkthrough.