Compute Finance Oracle

@compute-finance/mcp

[npm version] [npm downloads] [license]

Live AI compute pricing oracle — real-time LLM model prices across nine vendors (Anthropic, OpenAI, Google, DeepSeek, xAI and four more) via the Compute Finance Oracle.

A stdio MCP server. Works in any MCP client. Includes optional Claude Code skills for session cost analysis.

Quick start

Claude Code (recommended)

npx @compute-finance/mcp setup

This single command:

1. Registers the MCP server at user scope (claude mcp add)
2. Installs Claude Code skills (/cf-session-management, /cf-session-consumption, /cf-active-sessions, /cf-account)
3. Installs the cost hook — a UserPromptSubmit hook that injects session cost into Claude's context so every response can show how much you've spent

Restart Claude Code after setup.

To also answer for your own Compute Finance account, connect it once — see Your account.

Or register manually without skills/hook:

claude mcp add --scope user compute-finance -- npx @compute-finance/mcp

Cursor / VS Code / Any MCP client

Add to your MCP config (.cursor/mcp.json, VS Code settings, etc.):

{  "mcpServers": {    "compute-finance": {      "command": "npx",      "args": ["@compute-finance/mcp"]    }  }}

From source

git clone https://github.com/compute-finance/mcp.gitcd mcpnpm install && npm run buildnpx . setup

Tools

Tools are named by layer prefix and come in three groups. The public and local groups need no API key and no account.

The account_* tools are not listed below: the exchange publishes them, and this package copies none of them. See Your account.

Data (live oracle)

Models are identified by their canonical vendor-prefixed id — anthropic/claude-opus-4.8, openai/gpt-5.5, qwen/qwen-3.5-flash. Every tool taking a model also accepts the bare name (gpt-5.5) and answers with the canonical id. The vendor slug is not always the provider key (alibaba → qwen, xai → x-ai, moonshot → moonshotai), so reuse an id the API returned rather than assembling one. data_get_scu, data_get_breakdown and data_get_reconstitutions are the exception: they pass the attested manifest through verbatim and so report bare model keys, because a / is not a legal manifest key.

Cache pricing comes from the Compute Finance Oracle. Session and consumption reports show effective (cache-aware) cost when the oracle has published the relevant cache components; otherwise they show nominal cost (input rate applied to every input variant) and label effective as unavailable for that model.

Alongside cache, the oracle publishes a reasoning output price — reasoning.reasoningOutput, on the same base as every other component; the whole reasoning block is null for a model with no usable reasoning price. It is catalogue data. Session and consumption reports do not bill it: Claude Code transcripts count thinking blocks rather than reasoning tokens, and those tokens are already inside output_tokens.

Every price is reported on two bases: base_* is the provider list price, identical for every model the oracle tracks, and billed_* is what compute.finance charges — base × (1 + routing_fee_rate). Compare models on base_*, budget on billed_*. The rate ships once per response and billed_* is null when the oracle does not publish it. Session and consumption reports are on the base basis throughout.

Every current-price answer comes from one place: the live catalogue the exchange bills against. Index membership decides which models data_get_basket and compute_compare list, never what a model costs, so two models the catalogue prices alike quote alike. data_get_cpi is the exception by design — it serves the prices the latest on-chain revision attested, which change only when an operator publishes the next one and may therefore lag the catalogue. Read it as attestation history, not as a quote.

Some models get pricier past a context length. data_get_basket and data_get_price publish that as context_tiers, a ladder ascending by from_input_tokens and always at least one rung: the first starts at 0 and restates the flat rate, so a model priced the same at every size has exactly one rung and nothing has to branch on whether a model happens to be tiered. Rungs carry base_* and billed_* like every other price; only the flat rate enters the SCU index. compute_estimate and compute_compare pick the rung from the whole input side of the request — prompt plus cache reads plus cache writes, all charged at the full input rate there since neither tool applies a cache discount — over half-open ranges, so an input landing exactly on a threshold takes that rung, and both return the chosen rung as applied_context_tier so the rate behind the number is visible. data_get_catalog passes the oracle document through unchanged, so there contextTiers is absent rather than one-rung on a flat model.

The ladder comes from the catalog endpoint, and the two kinds of tool part ways whenever it cannot answer for a model — the read failed, or it succeeded and the model was not in it, which is upstream drift rather than a flat price. data_get_basket and data_get_price still serve their prices and set context_tiers to null — an unknown ladder, never a one-rung stand-in for a ladder nobody read. compute_estimate and compute_compare error instead: a cost quoted at the flat rate would understate exactly the long context the ladder exists to price.

max_input_tokens is the largest input a model accepts, null when the model declares no window of its own — not unbounded: the request-body ceiling still applies, there is just no per-model limit. Above a declared window the oracle refuses the request outright, so compute_estimate and compute_compare set exceeds_max_input_tokens. They still quote the cost: these tools are read-only and an agent sizing a context needs the number before it reshapes the request, but the flag says plainly that the request as supplied would be rejected.

Prices also carry a provenance mark saying how far the number has been checked: verified — an operator recorded a vendor source for it; inferred — derived from a sibling number or a vendor default, with no source recorded; promotional — a discounted list price that is expected to end. Every value bills as shown; the mark says how much to trust it, not what it costs. Marks are set by hand and hold as of the operator's last pass, not as a live check against the vendor. Every cache and reasoning component carries its own mark wherever it appears, and so does every base price: data_get_catalog marks currentPrice.provenance for every model, index member or not, while data_get_basket, data_get_price and compute_estimate carry the same pair as base_price_provenance. A rung follows the same rule: the first repeats the base price's mark, and a higher rung is always a catalogue number, marked in both directions with the single mark the vendor quotes it under. Session and consumption reports print each cache multiplier with its mark; when the oracle publishes no cache pricing for a model they say so and print no marks.

A price says what a model costs, never whether it can serve. data_get_model_availability answers that second question: the public pool's routability list — every catalogue model under its canonical id with a routable flag, plus the model auto points at. Call it before settling on a model, so one that cannot serve is ruled out before the request instead of by a 503 after it. The signal is advisory: true as of computedAt and only for ttlSeconds after it, capacity moves on its own, and a model reported routable can still fail the send — the caller still handles the error on the request itself. The answer is the exchange's own, served verbatim with no liveness computed here, so it cannot disagree with the router that has to honour it; it is cached for exactly the ttlSeconds published with it, and not at all when that figure is missing or unusable, rather than for the window every other read uses.

Private offers are not listed. A model a supplier offers to a private pool, under a handle/alias id, never enters the public catalogue: it is listed only once the pool's owner accepts the offer, and then only to API keys bound to that pool — and this server sends no such key, with or without a connected account. To see them, call GET /v1/models with a ct_live_* key bound to the pool.

Compute

Render (Claude Code skills)

Reports surface three orthogonal counts: prompts (what you typed), inferences (assistant replies — tool-loop sessions produce several per prompt), and tool calls (tool_use blocks). The triplet is identical across all three reports for the same session.

Analysis

The analyze_session counterfactual quotes each model's base rate and never a long-context rung. A rung is picked per request, and a session's summed input is not one giant request — a hundred 5k-token calls are not a single 500k-token one — so pricing the total on a higher rung would overcharge. Expect those rows to sit below compute_compare for a model that gets pricier past a context length.

History

Your account

Everything above is public data or local files. To ask what your Compute Finance account has spent, which of your keys are live, or how much headroom is left before a cap, connect the account with an app grant.

Connect

1. In compute.finance open Settings → Connected apps, press Grant access, name the app and choose what it may do: Read (see the account's balance, usage and history) and/or Act (manage the account's keys and limits). If you work in an organization, pick the account the grant acts on — the grant is pinned to it and no session elsewhere can redirect it.
2. Copy the cfa_live_… token. It is shown once.
3. Store it:

npx @compute-finance/mcp setup --account

Setup asks for the token on stdin — typing is hidden, and the token is never an argument, so it cannot land in your shell history or in an MCP config file. It is then stored in the credential store your OS already ships: macOS Keychain (security), Windows DPAPI (a blob under %APPDATA% only your Windows user can decrypt), or the Secret Service on Linux (secret-tool, from libsecret). No native npm dependency is added for any of them.

Setup checks the token with the exchange before storing it: a token the exchange refuses is not stored. If the exchange cannot be reached, setup warns and stores the token anyway, so a token typed while offline is checked on the server's first start instead. On a system with none of these stores, setup stores nothing and points you at CF_APP_GRANT_COMMAND (below).

Restart your MCP client. The account_* tools appear; with no credential they are simply not registered and the oracle and session tools behave exactly as before.

Where the server looks for the token

At startup, in this order, stopping at the first that answers:

Wherever it came from, the token is only ever sent to an https origin — or to http on a loopback host, so a local API still works. CF_API_BASE pointing anywhere else is refused at startup and the token is not sent.

What a grant can and cannot do

• A grant is limited to the operations you ticked when you created it, on the one account you pinned it to. It can never take money out of the account — no withdrawal, no transfer, and no action that needs a wallet signature. Those stay with your wallet.
• Act access is not harmless. An app holding it can create an API key that spends the account's balance, change or clear the budget caps that bound that spending, and configure automatic top-up. Automatic top-up always applies to your own personal account, even when the grant is pinned to an organization. Tick Act only for an app you would trust with those three; grant Read alone otherwise.
• The exchange decides what each grant may call. GET /v1/account-tools returns only the tools that grant holds the access for, with their descriptions and input schemas; a call goes through POST /v1/account-tools/call. This package copies none of those contracts, so a change on the exchange's side reaches you without a release here.
• A refusal is a refusal. When the exchange declines — the grant is frozen, revoked, or lacks the access a tool needs — the tool returns the exchange's own wording naming what is missing. It is never rewritten into an empty balance, an empty key list or a guess. A grant refused at startup registers a single account_status tool carrying that wording, rather than reporting no account at all.

Revoke

Revoking is done where the grant was made: Settings → Connected apps → Revoke. Revocation is permanent and takes effect at once; your own session and every other app are unaffected. Freeze suspends a grant instead, and can be lifted.

Remove the local copy of the token afterwards:

npx @compute-finance/mcp setup --forget-account

This clears the OS credential store only. A token supplied through CF_APP_GRANT_COMMAND or CF_APP_GRANT lives wherever you put it; remove it there.

Cost hook

The setup command installs a UserPromptSubmit hook into ~/.claude/settings.json. Every time you send a message, the hook reads the current session transcript, prices it against the live oracle, and injects a cost summary into Claude's context via additionalContext. Claude then appends a 💰 Compute.Finance · … line at the end of its response.

Guards — the hook fires only when all three conditions are met:

• Session cost exceeds $1
• Session has at least 5 user prompts
• At least 10 minutes since the last fire (per session)

On any failure (oracle down, transcript missing, parse error) the hook exits silently — it never blocks your prompt.

Manual installation

If setup can't write to settings.json, add the hook manually:

{  "hooks": {    "UserPromptSubmit": [      {        "matcher": "",        "hooks": [          {            "type": "command",            "command": "npx @compute-finance/mcp hook-prompt"          }        ]      }    ]  }}

Uninstall

Remove the UserPromptSubmit entry from ~/.claude/settings.json.

Privacy

All data stays on your machine. Without a connected account the only network calls are unauthenticated GETs to api.compute.finance — the oracle endpoints under /v1/oracle/* and the OpenAPI document at /openapi.json, read once at startup to document oracle response shapes. Session logs (~/.compute-finance/sessions.jsonl, ~/.compute-finance/inferences.jsonl) are never uploaded.

With an account connected, the grant token is sent to api.compute.finance as an Authorization: Bearer header on /v1/account-tools and /v1/account-tools/call, and nowhere else. It is never written to a config file, never passed as a process argument, and never printed to stdout, stderr or a tool answer — including in diagnostics, which are redacted before they are written. Session logs still carry only local measurements and are still never uploaded.

Links

• Compute Finance
• Oracle API
• OpenAPI spec
• npm package