finops-framework-mcp

Three unofficial MCP servers that give AI assistants a structured, sourced interface to published FinOps and AI-cost guidance, so an assistant answers with the publishers' actual text and formulas instead of improvising:

All three are read-only (an agent can read guidance, never change your practice or data) and offline once installed (no network access at runtime, no telemetry). Use any one on its own; together they cover what good looks like, which billing columns prove it, and what drives AI token cost.

Start here: the usage guide

aaronmsoto.github.io/finops-framework-mcp is a free, no-install walkthrough written for FinOps practitioners as much as engineers. It explains what each server does, connects them to Claude in a couple of minutes, and works through five examples, from a showback report to whether prompt caching is paying off. Every number and quote in it comes from a real run of these servers. See Documentation for the page list.

Related MCP server: cloud-finops-mcp

Why this exists

Ask an AI assistant "how mature is our Allocation practice?", "which FOCUS columns feed Effective Savings Rate?" or "is our prompt caching paying off?" without these servers, and it will happily improvise a plausible answer. With them, every response is the publisher's own text and formulas, structured for an assistant to read, with the source URL and license attached.

Anything a server had to work out itself is labeled, never passed off as published guidance:

• The FOCUS server's KPI-to-column mapping, computed KPI values and cross-version diff are marked UNOFFICIAL (official: false).

• The tokenomics server states each source's publication status on every answer, because most Tokenomics Foundation guidance is a working draft or release candidate. Its curated crosswalk is unofficial and only appears with FINOPS_MCP_EXPERIMENTAL=1.

• The framework server is official-only out of the box: no invented relationships between capabilities, no maturity levels beyond the Foundation's Crawl/Walk/Run.

Quickstart

All three are on npm, so there is nothing to clone or build. Each package ships its own data and runs offline. Node >= 22 is the only requirement.

npx -y finops-framework-mcp
npx -y finops-focus-mcp
npx -y tokenomics-overview-mcp

(-y skips npx's first-run install prompt, which can hang non-interactive MCP clients. Pin a version with, for example, npx -y finops-focus-mcp@0.2.)

Claude Code:

claude mcp add finops-framework -- npx -y finops-framework-mcp
claude mcp add focus-spec -- npx -y finops-focus-mcp
claude mcp add tokenomics-overview -- npx -y tokenomics-overview-mcp

Claude Desktop (claude_desktop_config.json), or a project-scoped .mcp.json, or any stdio MCP client:

{
  "mcpServers": {
    "finops-framework": {
      "command": "npx",
      "args": ["-y", "finops-framework-mcp"]
    },
    "focus-spec": {
      "command": "npx",
      "args": ["-y", "finops-focus-mcp"]
    },
    "tokenomics-overview": {
      "command": "npx",
      "args": ["-y", "tokenomics-overview-mcp"]
    }
  }
}

Environment variables (all optional):

Each server also accepts the data directory as its first CLI argument, and answers --version with its package version plus its data version (FOCUS: the spec versions it serves).

How to use them

Start a session with each server's entry point, then follow its suggestions:

Questions each one answers well:

• Framework: "What does Walk-level Forecasting require?", "Which KPIs does the Foundation feature for Rate Optimization?", "Who does what in Anomaly Management?"

• FOCUS: "What does BilledCost mean in 1.2, and what changed since 1.0?", "Which columns do I need to compute Effective Savings Rate?"

• Tokenomics: "Which layer owns model routing and AI gateways?", "How does this agent's token use scale with autonomy?", "Our cache read, write and uncached input tokens were X, Y, Z: is caching saving money?"

Using them together. The servers ship separately and never call each other. Instead, answers hand off by URI: each of the tokenomics server's 35 get_crosslinks links is backed by a verbatim quote from the Tokenomics Foundation page, and carries a finops://framework/… or focus://spec/… URI for the agent to read with the other two servers. FOCUS 1.5 working-draft names, which no ratified release contains yet, come back with no URI. The prompt-caching example walks one question through all three.

Server surfaces

• finops-framework-mcp: 11 tools — get_framework_info (entry point), search_framework, list_capabilities, get_capability, get_maturity_assessment, get_kpis, assess_maturity_path, map_personas, get_entity, get_maturity_model, get_changelog — plus finops://framework/… resources and 4 prompts (explain-framework, assess-capability-maturity, plan-maturity-roadmap, map-personas-to-capabilities). Data: 6 Principles, 3 Phases, 4 Domains, 22 Capabilities, 11 Personas, 5 Technology Categories, the Scopes concept, and an 88-entry KPI library.

• finops-focus-mcp: 9 tools for column and attribute lookup, normative requirements, search, the 1.0 → 1.2 diff, and unofficial KPI-to-column mappings with sample-data KPI calculation, plus focus://spec/… resources and 3 prompts. See packages/finops-focus-mcp.

• tokenomics-overview-mcp: 20 tools across documents, the Seven-Layer Stack, Big-T notation, levers, metrics (with a cache-metrics calculator), personas, value classification, the FOCUS 1.5 AI-cost capabilities and cross-links, plus tokenomics://overview/… resources and 3 prompts (optimize_consumption, assess_prompt_caching, bigt_review). Data: 14 source documents, 7 layers, 6 Big-T classes, 32 levers, 7 metrics, 12 personas, 35 stated cross-links. See packages/tokenomics-overview-mcp.

The full prompts, resources and tools of all three servers (names, arguments, URIs, defaults and limits) are generated from live MCP output in docs/mcp-surface.md.

Remote option: the Cloudflare Worker

All three servers can also run over Streamable HTTP from one bundled Cloudflare Worker (src/workers/, endpoints /mcp/framework, /mcp/focus and /mcp/tokenomics; see docs/deploy-worker.md). Any MCP client that speaks Streamable HTTP can connect to a deployed Worker, for example:

claude mcp add --transport http tokenomics-overview "$WORKER_URL/mcp/tokenomics"

The Worker is stateless and serves each server's default surface (no experimental tools). demo/ is a static browser page with two walkthroughs through it: "Is prompt caching paying off?" (all three servers, on your own token counts) and Rate Optimization (framework and FOCUS).

How it's built

Every server is the same three decoupled parts, so a content refresh never needs a code change:

crawler ──▶ data artifact ──▶ MCP server (stdio)
src/crawlers/<name>   data/<name>/   src/servers/<name>

for <name> in framework, focus and tokenomics. The framework and tokenomics crawlers go fetch → parse → compose → derive → validate → emit: content/markdown/ is the canonical intermediate, composed from parsed HTML, and every JSON file is regenerated from it by an offline derive step, so a schema or JSON-only fix never needs a re-crawl. Their artifacts carry JSON Schemas and a sha256 manifest, and each server validates its artifact at startup and refuses to start on a bad one. The FOCUS crawler instead ingests each pinned spec release by git tag into data/focus/<version>/, with the derived diff and KPI mapping under data/focus/derived/.

The framework server's early capability relationship graph (get_prerequisites/get_related) was built, evaluated and deleted because its edges didn't clear the accuracy bar; see .agents/specs/v1-official-only.md.

Refreshing the data

npm run build
npm run refresh                                   # framework: crawl → artifact + diff report
node dist/crawlers/focus/cli.js                   # FOCUS: ingest the pinned spec tags (1.0, 1.2)
node dist/crawlers/tokenomics/cli.js refresh      # tokenomics: Tokenomics Foundation pages
node dist/crawlers/framework/cli.js derive        # framework: offline markdown → JSON, byte-identical
node dist/crawlers/tokenomics/cli.js derive       # tokenomics: same, for data/tokenomics

Crawls are polite, cached and robots-honoring. No upstream changes produce a byte-identical artifact and no version bump; content changes produce a changelog entry and a semver bump of the data version. The tokenomics refresh also lists pages it found but doesn't ingest (for example working-group drafts) under unregistered in its manifest. A scheduled refresh workflow is provided at docs/proposed/refresh-data.yml; .github/workflows/ is a protected path here, so the owner installs it:

git mv docs/proposed/refresh-data.yml .github/workflows/refresh-data.yml

Data versioning policy

Consumers pin a data version by pinning a package version or a git ref of this repo. Each manifest.json carries data_version, schema_version, crawled_at, per-file sha256 and entity counts; derived/changelog.json records what changed between versions (served by the framework server as get_changelog). Schema-breaking changes bump schema_version and require a server release. Releases are cut from a v* tag; see docs/release-runbook.md.

License and attribution

Code: MIT (see LICENSE). Content, each CC BY 4.0, restructured and adapted — see NOTICE.md for the required attribution and modification notices:

• data/framework/**: © FinOps Foundation

• data/focus/**: © FinOps Foundation / FOCUS project contributors

• data/tokenomics/**: © Tokenomics Foundation (a Series of LF Projects, LLC)

FinOps™, FinOps Foundation™ and FOCUS™ are trademarks of the FinOps Foundation. This project is independent and not affiliated with or endorsed by the FinOps Foundation, the FOCUS project, or the Tokenomics Foundation.

Documentation

docs/guide/ is the usage guide: nine self-contained pages in which every number, quote and transcript was captured from a live probe of these servers or computed from the committed sample data. It is also the published site: .github/workflows/pages.yml deploys docs/guide/, and only that directory, to https://aaronmsoto.github.io/finops-framework-mcp/ on every push to main that touches it (setup and smoke test in docs/deploy-pages.md).

Every page opens over file:// too; the guide has no external assets. Guide pages are rich HTML by design, an intentional exception to this repo's markdown-for-docs convention recorded in .agents/memory/decisions.md.

Development

• Agent instructions: AGENTS.md · design: docs/architecture.md (adversarial reviews: docs/critique-1.md, docs/critique-2.md, docs/critique-3-publish-gate.md, docs/critique-4-focus-gate.md, docs/final-status-review.md) · tokenomics design: docs/designs/tokenomics-overview-mcp.html

• Gates: ./scripts/agentic gates · tests: npm test (fixture-based, no network) · evals: evals/framework/ (docs/eval-results.md)

• Working in a clone: the checked-in .mcp.json loads all three servers into MCP clients that read it, running the published packages via npx so a fresh clone works with no build. To exercise your working tree instead, cp .mcp.json.example .mcp.json and build first (dist/ is gitignored), then restart the client; clients read MCP config only at startup. See CONTRIBUTING.md.

• Releasing: docs/release-runbook.md.