opentel-mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.5.0
+
+### Added — Cost & Token Attribution
+
+- Span attributes, added on any tool call whose result carries recognizable
+  usage data: `mcp.tool.tokens.input`, `mcp.tool.tokens.output`,
+  `mcp.tool.tokens.total`, `mcp.tool.model`, `gen_ai.response.model`
+  (co-emitted alongside `mcp.tool.model` for GenAI-dashboard compatibility —
+  see README's "Cost & Token Attribution" section and the
+  `ATTR_GEN_AI_RESPONSE_MODEL` docblock in `src/attributes.js` for why this
+  is a pragmatic compatibility choice, not a spec-pure emission),
+  `mcp.tool.cost.usd`, and `mcp.tool.cost.currency`. All added by
+  `applyCostAttribution()` in `src/instrument.js`, wrapped in its own
+  try/catch — cost tracking can never break a span.
+- Two new metric instruments, via the same `@opentelemetry/api`-only
+  pattern as the four existing `mcp.tool.*` metrics: `mcp.tool.tokens.total`
+  (counter, unit `tokens`) and `mcp.tool.cost.total` (counter, unit `USD`),
+  both attributed by `gen_ai.tool.name` + `mcp.tool.model` (model only
+  added when detected, same optional-attribute pattern
+  `mcp.failure.category` already uses).
+- Per-session and per-tool budget guardrails (`costTracking.budget`,
+  `src/cost/budget.js`): in-memory cumulative-cost tracking, flags
+  `mcp.tool.cost.budget_exceeded` / `mcp.tool.cost.budget_scope`
+  (`"session"` | `"tool"`, session wins if both trip on the same call) on
+  the span once a configured `perSessionUsd`/`perToolUsd` limit is
+  crossed. **Observability only — never blocks or throws.** Calls with no
+  MCP session id (e.g. stdio transport) are skipped for session tracking
+  rather than lumped under a fallback key.
+- `DEFAULT_PRICING` (`src/cost/pricing.js`): a default pricing table
+  covering 15+ models across five providers — Anthropic, OpenAI, Google,
+  AWS Bedrock, and DeepSeek. **Last verified 2026-07-29 — provider pricing
+  changes frequently and this table is not guaranteed to stay current;
+  override `costTracking.pricingTable` for production accuracy.**
+- `defaultExtractor` (`src/cost/extractor.js`): recognizes Anthropic
+  (`usage.input_tokens`/`usage.output_tokens`), OpenAI
+  (`usage.prompt_tokens`/`usage.completion_tokens`), and Bedrock
+  (`usage.inputTokens`/`usage.outputTokens`) usage shapes, the MCP
+  `_meta.usage` extension point, and JSON-in-text inside
+  `content[0].text`. Never throws — unrecognized shapes resolve to `null`.
+  Pluggable via `costTracking.extractor` (type `UsageExtractor`) for
+  custom tool result formats.
+- `calculateCost()` (`src/cost/calculator.js`): normalizes a model name
+  (lowercase, strips a `provider/` prefix) and prices it against a
+  `PricingTable`. Returns `null` — never throws — for an unrecognized
+  model or invalid token counts.
+- `costTracking` option on `instrumentMcpServer()` (see `src/config.js`):
+  `{ enabled?: boolean; pricingTable?: PricingTable; extractor?:
+  UsageExtractor; budget?: { perSessionUsd?: number; perToolUsd?: number
+  } }`. Defaults to enabled, `DEFAULT_PRICING`, `defaultExtractor`, budget
+  tracking off. Any field can be overridden independently.
+
+### Public API additions
+
+Re-exported from the package root (`src/index.js` / `src/index.d.ts`):
+`DEFAULT_PRICING`, `defaultExtractor`, `calculateCost` (values), and
+`ModelPricing`, `PricingTable`, `UsageExtractor`, `TokenUsage`,
+`CostTrackingOptions` (types, from the new `src/cost/types.d.ts` —
+mirrors the `src/fingerprint/types.d.ts` pattern).
+
+### Docs
+
+- `gen_ai.tool.name`'s comment in `src/attributes.js` now explicitly notes
+  it's sourced from the OTel GenAI semantic conventions, not a custom
+  addition — the file already documented this at the module/section level,
+  but not on the constant itself, which read ambiguously next to the
+  custom attributes below it that do say so explicitly.
+- README: new "Cost & Token Attribution (v0.5.0)" section (motivation,
+  zero-config quick-start, advanced config example, span-attribute and
+  metric tables, pricing-accuracy note, extension points); intro tagline
+  and "Configuration"/"Semantic conventions"/"Roadmap"/"Compatibility"
+  sections updated to match.
+
 ## 0.3.0
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # opentel-mcp
 
 > Turn every MCP tool call into an OpenTelemetry trace — including the
-> failures your logs won't show you.
+> failures your logs won't show you, and what it cost in LLM tokens.
 
 [![CI](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/opentel-mcp.svg)](https://www.npmjs.com/package/opentel-mcp)
@@ -9,10 +9,14 @@
 [![license](https://img.shields.io/npm/l/opentel-mcp.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/blob/main/LICENSE)
 
 opentel-mcp watches every tool call your MCP (Model Context Protocol)
-server handles: which tool ran, how long it took, and whether it worked.
-It reports that as OpenTelemetry (OTel) traces — the standard most
-dashboards already read. One function call; no changes to your tools'
-code.
+server handles: which tool ran, how long it took, whether it worked, and —
+when the tool result carries usage data — how many tokens it burned and
+what that cost. It reports all of that as OpenTelemetry (OTel) traces —
+the standard most dashboards already read. One function call; no changes
+to your tools' code.
+
+opentel-mcp is the only Node.js MCP instrumentation library that ties
+tool calls to LLM cost.
 
 ## The problem
 
@@ -288,6 +292,134 @@ examples/fingerprint-demo.js`). Not yet wired through
 `computeFingerprint` directly rather than configuring the automatic
 per-call-site wrapping; tracked in the roadmap below.
 
+## Cost & Token Attribution (v0.5.0)
+
+MCP tools increasingly wrap LLM calls themselves — a tool that
+summarizes a document, drafts a reply, or classifies a ticket usually
+does it by calling out to a model, and that call has a real dollar cost.
+Standard MCP/OTel instrumentation has no opinion on any of this: a trace
+shows a tool ran in 800ms and succeeded, with nothing about which model
+it used, how many tokens it burned, or what that cost. That's the AI
+FinOps gap in MCP observability today — cost and usage data exists
+inside the tool call, but nothing carries it out to your traces. opentel-mcp
+closes it: when a tool result carries recognizable usage data, the same
+span your other instrumentation already reads also gets token counts, the
+detected model, and an estimated USD cost.
+
+### Zero-config quick-start
+
+```js
+import { instrumentMcpServer } from 'opentel-mcp';
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  setupNodeSdk: true, // dev mode: prints traces to your terminal
+});
+```
+
+That's it — `costTracking` defaults to enabled. Any tool result whose
+usage data matches one of `defaultExtractor`'s recognized conventions
+(Anthropic's `usage.input_tokens`/`usage.output_tokens`, OpenAI's
+`usage.prompt_tokens`/`usage.completion_tokens`, Bedrock's
+`usage.inputTokens`/`usage.outputTokens`, the MCP `_meta.usage` extension
+point, or JSON-in-text inside `content[0].text`) automatically gets
+`mcp.tool.tokens.*` / `mcp.tool.model` / `mcp.tool.cost.*` span
+attributes, priced against `DEFAULT_PRICING`.
+
+### Advanced: custom pricing, a custom extractor, and a budget guardrail
+
+```js
+import { instrumentMcpServer, DEFAULT_PRICING } from 'opentel-mcp';
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  costTracking: {
+    // Extend or override DEFAULT_PRICING — e.g. price an internal model
+    // it doesn't know about, or correct stale numbers.
+    pricingTable: {
+      ...DEFAULT_PRICING,
+      'my-internal-model': { inputPer1M: 1.0, outputPer1M: 2.0, currency: 'USD' },
+    },
+    // Recognize your own tool result shape. Return null for anything you
+    // don't recognize — never throw (see src/cost/extractor.js).
+    extractor: (toolResult) => {
+      if (!toolResult?.tokenStats) return null;
+      const { in: inputTokens, out: outputTokens, modelId } = toolResult.tokenStats;
+      return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens, model: modelId };
+    },
+    // Observability guardrail, NOT enforcement — opentel-mcp never blocks
+    // or throws on a budget overrun, it just flags the span.
+    budget: {
+      perSessionUsd: 5, // flag once one MCP session's calls total > $5
+      perToolUsd: 1, // ...or once any single tool's calls total > $1
+    },
+  },
+});
+```
+
+### Span attributes
+
+| Attribute | Standard OTel? | Description | Example |
+|---|---|---|---|
+| `mcp.tool.tokens.input` | Custom | Input tokens consumed | 1000 |
+| `mcp.tool.tokens.output` | Custom | Output tokens produced | 500 |
+| `mcp.tool.tokens.total` | Custom | input + output | 1500 |
+| `mcp.tool.model` | Custom | Detected model name | "claude-sonnet-5" |
+| `gen_ai.response.model` | Standard (GenAI semconv)[^5] | Same value as `mcp.tool.model`, co-emitted for dashboard compatibility | "claude-sonnet-5" |
+| `mcp.tool.cost.usd` | Custom | Estimated cost, from `calculateCost()` | 0.0105 |
+| `mcp.tool.cost.currency` | Custom | Always `"USD"` today | "USD" |
+| `mcp.tool.cost.budget_exceeded` | Custom | `true` once a configured `costTracking.budget` limit is crossed | true |
+| `mcp.tool.cost.budget_scope` | Custom | Which budget scope tripped: `"session"` \| `"tool"` (session wins if both did) | "session" |
+
+[^5]: `gen_ai.response.model` is a real OTel GenAI semantic convention attribute ("the name of the model that generated the response") — but this span is an MCP tool-call span (`gen_ai.operation.name: execute_tool`), not a dedicated LLM request/response span, so co-emitting it here is a **pragmatic dashboard-compatibility choice, not a spec-pure emission**. It's set purely so off-the-shelf GenAI dashboards (Grafana, SigNoz, Honeycomb) that filter/group by `gen_ai.response.model` pick these spans up without any opentel-mcp-specific configuration. Full reasoning in `src/attributes.js`'s `ATTR_GEN_AI_RESPONSE_MODEL` docblock.
+
+The four token/model attributes are set together or not at all; the two
+cost attributes only appear when a model was detected *and* it resolves
+in the configured `pricingTable`; the two budget attributes only appear
+when a cost was calculated *and* a configured limit was crossed. Source
+of truth: `src/attributes.js` and `src/instrument.js`'s
+`applyCostAttribution()`.
+
+### Metrics
+
+Two more `mcp.tool.*` metrics, via the same API-only pattern as the four
+in "Metrics" above — nothing recorded until a `MeterProvider` is
+registered, `enableMetrics: false` opts out of these too.
+
+| Metric | Type | Unit | Attributes | Emitted when |
+|---|---|---|---|---|
+| `mcp.tool.tokens.total` | Counter | tokens | `gen_ai.tool.name`, `mcp.tool.model`[^6] | Usage detected in the tool result |
+| `mcp.tool.cost.total` | Counter | USD | `gen_ai.tool.name`, `mcp.tool.model`[^6] | Cost calculated (model resolved in `pricingTable`) |
+
+[^6]: `mcp.tool.model` is only added when a model was detected — the same optional-attribute cardinality pattern `mcp.failure.category` already uses on the other four metrics.
+
+### Pricing accuracy
+
+> **Pricing table last verified 2026-07-29.** Users **MUST** override
+> `pricingTable` for production accuracy — provider pricing changes
+> frequently and opentel-mcp does not guarantee `DEFAULT_PRICING` stays
+> current.
+
+`DEFAULT_PRICING` (`src/cost/pricing.js`) covers 15+ models across five
+providers — Anthropic, OpenAI, Google, AWS Bedrock, and DeepSeek — as a
+convenience default, not a maintained price list.
+
+### Extending it
+
+- `defaultExtractor` (also exported) recognizes the five conventions
+  listed under "Zero-config quick-start" above; pass your own
+  `costTracking.extractor` (a `UsageExtractor`: `(toolResult) =>
+  TokenUsage | null`, never throwing) to recognize anything else.
+- `calculateCost(inputTokens, outputTokens, model, pricingTable)` is also
+  exported directly, for recomputing cost outside the instrumentation
+  hot path (e.g. over historical spans).
+- Disable everything in this section with `costTracking: { enabled:
+  false }`; tracing, metrics, and fingerprinting are all unaffected.
+- Budget tracking (`costTracking.budget`) is in-memory and per
+  `instrumentMcpServer()` call — it resets on process restart, and
+  session-scoped limits are skipped gracefully (not enforced against a
+  fallback key) for transports with no session id, like stdio.
+
 ## Configuration
 
 All options passed to `instrumentMcpServer(server, options)`. Source of
@@ -301,7 +433,9 @@ truth: `src/config.js`.
 | `enabled` | boolean | `true` | `false` disables all instrumentation |
 | `enableMetrics` | boolean | `true` | `false` disables `mcp.tool.*` metrics only |
 | `fingerprinting` | boolean | `true` | `false` disables `mcp.failure.*` attributes |
+| `costTracking` | object | see below | Controls cost/token attribution[^9] — see "Cost & Token Attribution" above |
 
+[^9]: `{ enabled?: boolean; pricingTable?: PricingTable; extractor?: UsageExtractor; budget?: { perSessionUsd?: number; perToolUsd?: number } }`, all fields optional and individually defaulted — `{ enabled: true, pricingTable: DEFAULT_PRICING, extractor: defaultExtractor }` with budget tracking off.
 [^2]: Required only when `setupNodeSdk` is `true`. Has no effect otherwise — the host app's registered `TracerProvider` owns the resource; passing it anyway logs a one-time `diag.warn`.
 [^3]: Creates and registers a `NodeTracerProvider` that always prints to stderr (safe alongside stdio-transport servers — ADR 003), additionally exporting via OTLP/HTTP if `exporterUrl` is set.
 [^4]: Only takes effect when `setupNodeSdk` is `true`.
@@ -348,14 +482,21 @@ until `1.0`, tracked in release notes rather than silently shipped.
 
 opentel-mcp follows those conventions (published by the OTel GenAI SIG,
 moved there from the main `semantic-conventions` repo, where the MCP
-conventions are now deprecated) for everything they define, and adds two
+conventions are now deprecated) for everything they define, and adds
 namespaces of its own where they don't yet: `mcp.tool.*` (call-count and
-duration metrics) and `mcp.failure.*` (failure fingerprinting). Both are
+duration metrics, and — as of v0.5.0 — token/cost attribution and budget
+attributes) and `mcp.failure.*` (failure fingerprinting). Both are
 documented as non-spec at every attribute (`src/attributes.js`,
 `src/fingerprint/attributes.js`), and are candidates to fold into the
 spec's own metrics/error vocabulary if it grows an equivalent. Full
 reasoning: ADR 004 in `docs/adr/`.
 
+One exception, also in `src/attributes.js`: `gen_ai.response.model` *is*
+a real spec attribute, co-emitted alongside the custom `mcp.tool.model`
+purely for compatibility with GenAI dashboards that already query it —
+see the "Cost & Token Attribution" section above for why that's a
+pragmatic choice rather than a spec-pure one.
+
 ## Compatibility
 
 - Node.js 20+
@@ -364,16 +505,16 @@ reasoning: ADR 004 in `docs/adr/`.
 - Supports both low-level `Server` and high-level `McpServer` APIs
 - @modelcontextprotocol/sdk ^1.0.0
 - @opentelemetry/api ^1.9.0
-- 127 tests (`npm test`) — see `test/`
+- 288 tests (`npm test`) — see `test/`
 
 ## Roadmap
 
 - v0.4: Deep Failure Fingerprinting ✓ — see "Failure Fingerprinting" above
   and ADR 006.
-- v0.5: Failure clustering + regression detection
-- Future: recovery hints, root-cause chaining across parent spans,
-  alignment with the OTel GenAI SIG's MCP semantic conventions when
-  published
+- v0.5: Cost & Token Attribution ✓ — see "Cost & Token Attribution" above.
+- Future: failure clustering + regression detection; recovery hints;
+  root-cause chaining across parent spans; alignment with the OTel GenAI
+  SIG's MCP semantic conventions when published
 - Also still tracked, not silently dropped: exposing `computeFingerprint`'s
   `classifiers`/`stackFrames` options through `instrumentMcpServer()`
   itself; opt-in `gen_ai.tool.call.arguments` support with a redaction

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",

package/src/attributes.js

@@ -15,7 +15,15 @@
 /** Required. The JSON-RPC method name, e.g. "tools/call". */
 export const ATTR_MCP_METHOD_NAME = 'mcp.method.name';
 
-/** Conditionally Required (when the operation targets a specific tool). */
+/**
+ * Conditionally Required (when the operation targets a specific tool).
+ * Sourced from the OTel GenAI semantic conventions (`gen_ai.tool.name`),
+ * not invented by this package — MCP tool calls are GenAI `execute_tool`
+ * calls under the hood, so the MCP server span conventions reuse the
+ * existing `gen_ai.*` namespace rather than defining their own tool-name
+ * attribute. Contrast with the "Custom (non-spec) attributes" section
+ * below, where every entry explicitly says it's NOT part of the spec.
+ */
 export const ATTR_GEN_AI_TOOL_NAME = 'gen_ai.tool.name';
 
 /** Conditionally Required (when the client executes a request with a non-null id). */
@@ -35,6 +43,23 @@ export const ATTR_ERROR_TYPE = 'error.type';
  */
 export const ATTR_GEN_AI_OPERATION_NAME = 'gen_ai.operation.name';
 
+/**
+ * A real OTel GenAI semantic convention attribute ("the name of the model
+ * that generated the response") — but co-emitted here as a *pragmatic
+ * dashboard-compatibility* choice, not a spec-pure one. This span is an
+ * MCP tool-call span (`gen_ai.operation.name: execute_tool`), not a
+ * dedicated GenAI request/response span, so strictly speaking this
+ * attribute describes a model used *inside* the tool's implementation
+ * rather than the model that produced *this* span's own response. It's
+ * set to the same value as ATTR_MCP_TOOL_MODEL below, whenever
+ * applyCostAttribution() (instrument.js) detects one, purely so
+ * off-the-shelf GenAI dashboards (Grafana, SigNoz, Honeycomb) that filter
+ * or group by `gen_ai.response.model` pick these spans up without any
+ * opentel-mcp-specific configuration. See README's "Cost & Token
+ * Attribution" section for the full rationale.
+ */
+export const ATTR_GEN_AI_RESPONSE_MODEL = 'gen_ai.response.model';
+
 /**
  * Well-known error.type value for a JSON-RPC call that succeeded but whose
  * CallToolResult has isError: true — a tool-level failure, not a transport
@@ -85,3 +110,58 @@ export const MCP_TOOL_OUTCOME_ERROR = 'error';
 
 /** Well-known mcp.tool.outcome value: isError: true (see ERROR_TYPE_TOOL_ERROR above). */
 export const MCP_TOOL_OUTCOME_SILENT_FAILURE = 'silent_failure';
+
+// --- Cost & token attribution attributes (v0.5.0, non-spec) ---
+//
+// NOT part of the MCP semantic conventions — there is no spec-defined way
+// to report LLM token usage or cost on an MCP tool-call span. These are
+// opentel-mcp's own addition, populated by src/cost/extractor.js and
+// src/cost/calculator.js when a tool result carries recognizable usage
+// data (see instrument.js's applyCostAttribution()). All four token/model
+// attributes are set together or not at all; the two cost attributes are
+// only set when a model was detected *and* it resolves in the configured
+// pricing table (see calculateCost() in src/cost/calculator.js).
+
+/** Input tokens consumed by the tool call, as reported by the underlying model/provider. */
+export const ATTR_MCP_TOOL_TOKENS_INPUT = 'mcp.tool.tokens.input';
+
+/** Output tokens produced by the tool call. */
+export const ATTR_MCP_TOOL_TOKENS_OUTPUT = 'mcp.tool.tokens.output';
+
+/** input + output tokens for the tool call. */
+export const ATTR_MCP_TOOL_TOKENS_TOTAL = 'mcp.tool.tokens.total';
+
+/** Model name detected for the tool call (e.g. "claude-sonnet-5"), when the extractor found one. */
+export const ATTR_MCP_TOOL_MODEL = 'mcp.tool.model';
+
+/** Estimated cost of the tool call in ATTR_MCP_TOOL_COST_CURRENCY, from calculateCost(). */
+export const ATTR_MCP_TOOL_COST_USD = 'mcp.tool.cost.usd';
+
+/** Currency of ATTR_MCP_TOOL_COST_USD. Always MCP_TOOL_COST_CURRENCY_USD today. */
+export const ATTR_MCP_TOOL_COST_CURRENCY = 'mcp.tool.cost.currency';
+
+/** Well-known mcp.tool.cost.currency value — the only currency DEFAULT_PRICING and calculateCost() support. */
+export const MCP_TOOL_COST_CURRENCY_USD = 'USD';
+
+/**
+ * Set to true when this call's cost pushed a configured budget
+ * (costTracking.budget — see src/cost/budget.js) over its limit. Only set
+ * on the call that crosses the threshold and every call after — not
+ * retroactively on earlier, under-budget calls. Observability only: this
+ * package never blocks or throws on a budget overrun.
+ */
+export const ATTR_MCP_TOOL_COST_BUDGET_EXCEEDED = 'mcp.tool.cost.budget_exceeded';
+
+/**
+ * Which budget scope tripped: MCP_TOOL_COST_BUDGET_SCOPE_SESSION or
+ * MCP_TOOL_COST_BUDGET_SCOPE_TOOL. Only present alongside
+ * ATTR_MCP_TOOL_COST_BUDGET_EXCEEDED === true. When both scopes are over
+ * budget on the same call, session wins (see src/cost/budget.js).
+ */
+export const ATTR_MCP_TOOL_COST_BUDGET_SCOPE = 'mcp.tool.cost.budget_scope';
+
+/** Well-known mcp.tool.cost.budget_scope value: costTracking.budget.perSessionUsd was exceeded. */
+export const MCP_TOOL_COST_BUDGET_SCOPE_SESSION = 'session';
+
+/** Well-known mcp.tool.cost.budget_scope value: costTracking.budget.perToolUsd was exceeded. */
+export const MCP_TOOL_COST_BUDGET_SCOPE_TOOL = 'tool';

package/src/config.js

@@ -4,6 +4,23 @@
  */
 
 import { diag } from '@opentelemetry/api';
+import { DEFAULT_PRICING } from './cost/pricing.js';
+import { defaultExtractor } from './cost/extractor.js';
+
+/**
+ * @typedef {object} CostTrackingOptions
+ * @property {boolean} [enabled=true] - Set to false to disable cost/token span attributes and the
+ *   mcp.tool.tokens.total / mcp.tool.cost.total metrics entirely.
+ * @property {import('./cost/pricing.js').PricingTable} [pricingTable] - Overrides DEFAULT_PRICING
+ *   (src/cost/pricing.js). Supply your own table to price models DEFAULT_PRICING doesn't know about, or to
+ *   correct stale pricing — see that module's docblock.
+ * @property {import('./cost/extractor.js').UsageExtractor} [extractor] - Overrides defaultExtractor
+ *   (src/cost/extractor.js). Supply your own to recognize a tool result shape defaultExtractor doesn't.
+ * @property {import('./cost/budget.js').BudgetConfig} [budget] - Per-session and per-tool cumulative-cost
+ *   guardrails (src/cost/budget.js). Observability only — crossing a limit adds
+ *   mcp.tool.cost.budget_exceeded / mcp.tool.cost.budget_scope span attributes; it never blocks or throws.
+ *   Omit to disable budget tracking (the default).
+ */
 
 /**
  * @typedef {object} InstrumentOptions
@@ -33,6 +50,12 @@ import { diag } from '@opentelemetry/api';
  *   metrics (see src/fingerprint/attributes.js). computeFingerprint() never throws, so this only trades a
  *   small amount of per-failure CPU (see the p99 < 200µs budget in test/fingerprint/benchmark.test.js) for
  *   fingerprinting.
+ * @property {CostTrackingOptions} [costTracking] - Controls the mcp.tool.tokens.* / mcp.tool.model /
+ *   mcp.tool.cost.* span attributes, the mcp.tool.tokens.total / mcp.tool.cost.total metrics, and the
+ *   optional per-session/per-tool budget guardrail (see instrument.js's applyCostAttribution(),
+ *   src/metrics.js, and src/cost/budget.js). Defaults to `{ enabled: true, pricingTable: DEFAULT_PRICING,
+ *   extractor: defaultExtractor }` with budget tracking off; any fields you omit from a partial object fall
+ *   back to those defaults individually, so `{ enabled: false }` alone works.
  */
 
 // Guards the "serviceName has no effect" diagnostic below so it fires once
@@ -73,6 +96,8 @@ export function resolveOptions(options) {
     );
   }
 
+  const rawCostTracking = opts.costTracking ?? {};
+
   return {
     serviceName: opts.serviceName,
     exporterUrl: opts.exporterUrl,
@@ -80,5 +105,11 @@ export function resolveOptions(options) {
     enableMetrics: opts.enableMetrics ?? true,
     setupNodeSdk,
     fingerprinting: opts.fingerprinting ?? true,
+    costTracking: {
+      enabled: rawCostTracking.enabled ?? true,
+      pricingTable: rawCostTracking.pricingTable ?? DEFAULT_PRICING,
+      extractor: rawCostTracking.extractor ?? defaultExtractor,
+      budget: rawCostTracking.budget,
+    },
   };
 }

package/src/cost/budget.js

@@ -0,0 +1,113 @@
+/**
+ * @module cost/budget
+ * In-memory, best-effort budget guardrails for cost attribution.
+ *
+ * Observability only — this module never blocks a tool call and never
+ * throws. It exists so `applyCostAttribution()` (src/instrument.js) can
+ * flag a span when cumulative spend crosses a configured limit; enforcing
+ * that limit (denying the call, alerting, etc.) is left entirely to
+ * whatever consumes the resulting `mcp.tool.cost.budget_exceeded` span
+ * attribute (see src/attributes.js).
+ */
+
+/**
+ * @typedef {Object} BudgetConfig
+ * @property {number} [perSessionUsd] - Cumulative-cost limit per MCP session id. Calls with no session id
+ *   (e.g. stdio transport, which has none) are never tracked against this limit — see accumulate() below.
+ * @property {number} [perToolUsd] - Cumulative-cost limit per tool name.
+ */
+
+/**
+ * @typedef {Object} BudgetCheckResult
+ * @property {boolean} exceeded
+ * @property {'session' | 'tool' | null} scope - Which limit tripped on *this* call. null when `exceeded` is
+ *   false. When both scopes are over budget on the same call, "session" wins — matches
+ *   ATTR_MCP_TOOL_COST_BUDGET_SCOPE's documented precedence in src/attributes.js.
+ */
+
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value !== '';
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * Adds `amount` to `map.get(key)` (defaulting the prior total to 0) and
+ * returns the new running total. No-op — returns null — when `key` isn't
+ * a non-empty string or `amount` isn't a finite number, so a bad call
+ * neither throws nor silently poisons the map with NaN.
+ *
+ * @param {Map<string, number>} map
+ * @param {unknown} key
+ * @param {number} amount
+ * @returns {number | null}
+ */
+function accumulate(map, key, amount) {
+  if (!isNonEmptyString(key) || !isFiniteNumber(amount)) return null;
+  const total = (map.get(key) ?? 0) + amount;
+  map.set(key, total);
+  return total;
+}
+
+/**
+ * Creates a budget tracker scoped to one instrumented server (one call per
+ * `instrumentMcpServer()` invocation — see src/instrument.js). Holds two
+ * independent, unbounded-lifetime in-memory Maps: one keyed by MCP session
+ * id, one keyed by tool name. Neither is ever cleared — this mirrors the
+ * process-lifetime accumulation the "per session" / "per tool" limits are
+ * meant to describe; restart the process (or, for long-lived servers,
+ * build your own eviction on top) to reset.
+ *
+ * @param {BudgetConfig | undefined} budget - costTracking.budget from config.js. Omitted/undefined limits
+ *   mean that scope is never tracked or checked — recordAndCheck() becomes a pure no-op for it.
+ * @returns {{ recordAndCheck: (sessionId: unknown, toolName: unknown, costUsd: number) => BudgetCheckResult }}
+ */
+export function createBudgetTracker(budget) {
+  const perSessionUsd = isFiniteNumber(budget?.perSessionUsd) ? budget.perSessionUsd : undefined;
+  const perToolUsd = isFiniteNumber(budget?.perToolUsd) ? budget.perToolUsd : undefined;
+
+  /** @type {Map<string, number>} */
+  const sessionCostMap = new Map();
+  /** @type {Map<string, number>} */
+  const toolCostMap = new Map();
+
+  return {
+    recordAndCheck(sessionId, toolName, costUsd) {
+      try {
+        let sessionExceeded = false;
+        let toolExceeded = false;
+
+        if (perSessionUsd !== undefined) {
+          const total = accumulate(sessionCostMap, sessionId, costUsd);
+          // total is null when sessionId isn't usable (e.g. a stdio-transport
+          // call with no session id at all) — skip that scope silently
+          // rather than tracking against a made-up key.
+          if (total !== null) sessionExceeded = total > perSessionUsd;
+        }
+
+        if (perToolUsd !== undefined) {
+          const total = accumulate(toolCostMap, toolName, costUsd);
+          if (total !== null) toolExceeded = total > perToolUsd;
+        }
+
+        if (sessionExceeded) return { exceeded: true, scope: 'session' };
+        if (toolExceeded) return { exceeded: true, scope: 'tool' };
+        return { exceeded: false, scope: null };
+      } catch {
+        // Never throw — see module docblock. A tracking failure here must
+        // read as "no budget signal this call", not break the span.
+        return { exceeded: false, scope: null };
+      }
+    },
+  };
+}

package/src/cost/calculator.js

@@ -0,0 +1,55 @@
+/**
+ * @module cost/calculator
+ * Cost calculation for MCP tool-call token usage against a {@link
+ * import('./pricing.js').PricingTable}.
+ */
+
+/**
+ * Normalizes a model name for pricing-table lookup: lowercases it and
+ * strips a leading "provider/" prefix (e.g. "Anthropic/Claude-Opus-4-7"
+ * -> "claude-opus-4-7").
+ *
+ * @param {string} model
+ * @returns {string}
+ */
+function normalizeModelName(model) {
+  const lower = model.toLowerCase();
+  const slashIndex = lower.indexOf('/');
+  return slashIndex === -1 ? lower : lower.slice(slashIndex + 1);
+}
+
+/**
+ * Calculates the USD cost of a request from its input/output token counts,
+ * a model name, and a pricing table. Never throws: an unrecognized model or
+ * an invalid token count resolves to `null` rather than an exception,
+ * matching this library's fail-open philosophy (see instrument.js).
+ *
+ * @param {number} inputTokens
+ * @param {number} outputTokens
+ * @param {string} model - Matched against `pricingTable` after
+ *   lowercasing and stripping a "provider/" prefix.
+ * @param {import('./pricing.js').PricingTable} pricingTable
+ * @returns {number | null} Cost in USD rounded to 6 decimals, or `null` if
+ *   `model` isn't in `pricingTable` or a token count is negative,
+ *   non-numeric, or non-finite.
+ */
+export function calculateCost(inputTokens, outputTokens, model, pricingTable) {
+  if (
+    typeof inputTokens !== 'number' ||
+    typeof outputTokens !== 'number' ||
+    !Number.isFinite(inputTokens) ||
+    !Number.isFinite(outputTokens) ||
+    inputTokens < 0 ||
+    outputTokens < 0
+  ) {
+    return null;
+  }
+
+  const pricing = pricingTable[normalizeModelName(model)];
+  if (!pricing) {
+    return null;
+  }
+
+  const cost = (inputTokens / 1_000_000) * pricing.inputPer1M + (outputTokens / 1_000_000) * pricing.outputPer1M;
+  return Math.round(cost * 1e6) / 1e6;
+}

package/src/cost/extractor.js

@@ -0,0 +1,189 @@
+/**
+ * @module cost/extractor
+ * Best-effort token-usage extraction from MCP tool call results.
+ *
+ * MCP has no standard field for token usage — providers and tool authors
+ * report it differently, or not at all. This module recognizes several
+ * conventions seen in the wild and never throws: any result shape it
+ * doesn't recognize resolves to `null`, matching this library's
+ * instrumentation-must-never-break-the-host-app philosophy (see
+ * instrument.js and src/fingerprint/compose.js's computeFingerprint()).
+ */
+
+import { diag } from '@opentelemetry/api';
+
+/**
+ * @typedef {Object} TokenUsage
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {number} totalTokens
+ * @property {string} [model]
+ */
+
+/**
+ * @typedef {(toolResult: unknown) => TokenUsage | null} UsageExtractor
+ */
+
+/**
+ * Field-name pairs tried, in order, against a "usage-shaped" object:
+ * Anthropic (input_tokens/output_tokens), OpenAI (prompt_tokens/
+ * completion_tokens), then Bedrock (inputTokens/outputTokens).
+ */
+const TOKEN_FIELD_PAIRS = [
+  ['input_tokens', 'output_tokens'],
+  ['prompt_tokens', 'completion_tokens'],
+  ['inputTokens', 'outputTokens'],
+];
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * Reads `{inputTokens, outputTokens}` off a usage-shaped object, trying
+ * each known provider's field names in turn. Returns null if none match or
+ * the matched fields aren't finite numbers.
+ *
+ * @param {unknown} usage
+ * @returns {{ inputTokens: number, outputTokens: number } | null}
+ */
+function readTokenCounts(usage) {
+  if (!isPlainObject(usage)) return null;
+
+  for (const [inputKey, outputKey] of TOKEN_FIELD_PAIRS) {
+    const inputTokens = usage[inputKey];
+    const outputTokens = usage[outputKey];
+    if (isFiniteNumber(inputTokens) && isFiniteNumber(outputTokens)) {
+      return { inputTokens, outputTokens };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Picks the first string `model` found across the three conventional
+ * locations: `root.model`, `root.usage.model`, `root._meta.model`.
+ *
+ * @param {Record<string, unknown>} root
+ * @returns {string | undefined}
+ */
+function readModel(root) {
+  const candidates = [
+    root.model,
+    isPlainObject(root.usage) ? root.usage.model : undefined,
+    isPlainObject(root._meta) ? root._meta.model : undefined,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim() !== '') {
+      return candidate;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Builds a {@link TokenUsage} from a usage-shaped object plus the broader
+ * result it was found on (used only for model lookup). Returns null when
+ * `usage` doesn't contain a recognized token-count pair.
+ *
+ * @param {unknown} usage
+ * @param {Record<string, unknown>} modelRoot
+ * @returns {TokenUsage | null}
+ */
+function buildUsage(usage, modelRoot) {
+  const counts = readTokenCounts(usage);
+  if (!counts) return null;
+
+  const model = readModel(modelRoot);
+  return {
+    inputTokens: counts.inputTokens,
+    outputTokens: counts.outputTokens,
+    totalTokens: counts.inputTokens + counts.outputTokens,
+    ...(model !== undefined ? { model } : {}),
+  };
+}
+
+/**
+ * Safely parses the first text content block's `text` field as JSON.
+ * Returns null on any failure — missing/empty content array, non-text
+ * block, non-string text, or invalid JSON — rather than throwing.
+ *
+ * @param {Record<string, unknown>} result
+ * @returns {Record<string, unknown> | null}
+ */
+function parseTextContent(result) {
+  try {
+    const content = result.content;
+    if (!Array.isArray(content) || content.length === 0) return null;
+
+    const first = content[0];
+    if (!isPlainObject(first) || typeof first.text !== 'string') return null;
+
+    const parsed = JSON.parse(first.text);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Default {@link UsageExtractor}. Recognizes, in priority order:
+ *
+ *   1. `result.usage` in Anthropic, OpenAI, or Bedrock field-naming
+ *      conventions.
+ *   2. JSON-in-text: `result.content[0].text` parsed as JSON, then read
+ *      the same way — either a nested `usage` object, or the parsed
+ *      object itself treated as the usage object.
+ *   3. `result._meta.usage` — the MCP spec's `_meta` extension point.
+ *
+ * Model name is read from `result.model`, `result.usage.model`, or
+ * `result._meta.model` (first one found wins), resolved against whichever
+ * root produced the matched usage.
+ *
+ * Never throws: any unexpected shape — including one that throws on
+ * property access — is caught and logged at debug level, returning null.
+ *
+ * @type {UsageExtractor}
+ */
+export function defaultExtractor(toolResult) {
+  try {
+    if (!isPlainObject(toolResult)) return null;
+
+    const direct = buildUsage(toolResult.usage, toolResult);
+    if (direct) return direct;
+
+    const parsed = parseTextContent(toolResult);
+    if (parsed) {
+      const fromParsedUsage = buildUsage(parsed.usage, parsed);
+      if (fromParsedUsage) return fromParsedUsage;
+
+      const fromParsedRoot = buildUsage(parsed, parsed);
+      if (fromParsedRoot) return fromParsedRoot;
+    }
+
+    if (isPlainObject(toolResult._meta)) {
+      const fromMeta = buildUsage(toolResult._meta.usage, toolResult);
+      if (fromMeta) return fromMeta;
+    }
+
+    return null;
+  } catch (error) {
+    diag.debug('opentel-mcp: defaultExtractor failed to extract token usage, returning null', error);
+    return null;
+  }
+}

package/src/cost/pricing.js

@@ -0,0 +1,56 @@
+/**
+ * @module cost/pricing
+ * Static per-model token pricing used to estimate MCP tool-call cost.
+ *
+ * This module is data plus two shared type shapes — no network calls, no
+ * provider SDK dependency. `DEFAULT_PRICING` is a best-effort snapshot;
+ * pricing changes frequently and varies by region/contract, so callers who
+ * need accurate cost attribution should supply their own `PricingTable`
+ * rather than rely on this one being current.
+ */
+
+/**
+ * @typedef {Object} ModelPricing
+ * @property {number} inputPer1M - USD cost per 1,000,000 input tokens.
+ * @property {number} outputPer1M - USD cost per 1,000,000 output tokens.
+ * @property {'USD'} currency
+ */
+
+/**
+ * @typedef {Record<string, ModelPricing>} PricingTable
+ */
+
+// Prices in USD per 1M tokens. Last verified: 2026-07-29. Users should
+// override via config for accuracy — Anthropic does not guarantee this
+// table stays current.
+/** @type {PricingTable} */
+export const DEFAULT_PRICING = {
+  // Anthropic
+  'claude-opus-4-7': { inputPer1M: 5.0, outputPer1M: 25.0, currency: 'USD' },
+  'claude-opus-4-6': { inputPer1M: 5.0, outputPer1M: 25.0, currency: 'USD' },
+  'claude-sonnet-5': { inputPer1M: 3.0, outputPer1M: 15.0, currency: 'USD' },
+  'claude-haiku-4-5': { inputPer1M: 1.0, outputPer1M: 5.0, currency: 'USD' },
+  'claude-sonnet-4-6': { inputPer1M: 3.0, outputPer1M: 15.0, currency: 'USD' },
+  'claude-opus-4-5': { inputPer1M: 5.0, outputPer1M: 25.0, currency: 'USD' },
+
+  // OpenAI
+  'gpt-4o': { inputPer1M: 2.5, outputPer1M: 10.0, currency: 'USD' },
+  'gpt-4o-mini': { inputPer1M: 0.15, outputPer1M: 0.6, currency: 'USD' },
+  'gpt-5': { inputPer1M: 1.25, outputPer1M: 10.0, currency: 'USD' },
+  'gpt-5-mini': { inputPer1M: 0.25, outputPer1M: 2.0, currency: 'USD' },
+  o3: { inputPer1M: 2.0, outputPer1M: 8.0, currency: 'USD' },
+  'o3-mini': { inputPer1M: 1.1, outputPer1M: 4.4, currency: 'USD' },
+
+  // Google
+  'gemini-2-5-pro': { inputPer1M: 1.25, outputPer1M: 10.0, currency: 'USD' },
+  'gemini-2-5-flash': { inputPer1M: 0.3, outputPer1M: 2.5, currency: 'USD' },
+
+  // AWS Bedrock (Amazon Nova)
+  'amazon-nova-pro': { inputPer1M: 0.8, outputPer1M: 3.2, currency: 'USD' },
+  'amazon-nova-lite': { inputPer1M: 0.06, outputPer1M: 0.24, currency: 'USD' },
+  'amazon-nova-micro': { inputPer1M: 0.035, outputPer1M: 0.14, currency: 'USD' },
+
+  // DeepSeek
+  'deepseek-v3': { inputPer1M: 0.27, outputPer1M: 1.1, currency: 'USD' },
+  'deepseek-r1': { inputPer1M: 0.55, outputPer1M: 2.19, currency: 'USD' },
+};

package/src/cost/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared type definitions for the cost & token attribution feature.
+ *
+ * This is a hand-written declaration file, not a compiled build artifact —
+ * this project ships plain JS with no TypeScript build step (see
+ * CONTRIBUTING.md). It exists purely so TypeScript consumers (and editors)
+ * get accurate types; the `.js` files in this directory carry their own
+ * JSDoc `@typedef {import('./types.d.ts').Foo}` references back into this
+ * file, the same pattern `src/fingerprint/types.d.ts` and `src/index.d.ts`
+ * already use.
+ */
+
+/** One model's per-million-token pricing. See src/cost/pricing.js. */
+export interface ModelPricing {
+  /** USD cost per 1,000,000 input tokens. */
+  readonly inputPer1M: number;
+  /** USD cost per 1,000,000 output tokens. */
+  readonly outputPer1M: number;
+  readonly currency: 'USD';
+}
+
+/** Maps a normalized model name (see calculateCost() in src/cost/calculator.js) to its pricing. */
+export type PricingTable = Record<string, ModelPricing>;
+
+/** Result of a successful {@link UsageExtractor} call — see src/cost/extractor.js. */
+export interface TokenUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  /** inputTokens + outputTokens. */
+  readonly totalTokens: number;
+  /** Present only when the extractor found a model name (result.model / result.usage.model / result._meta.model). */
+  readonly model?: string;
+}
+
+/**
+ * Pulls token usage out of an MCP tool result. Must never throw — return
+ * `null` for any result shape you don't recognize. See
+ * `defaultExtractor` in src/cost/extractor.js for the reference
+ * implementation and the conventions it already recognizes.
+ */
+export type UsageExtractor = (toolResult: unknown) => TokenUsage | null;
+
+/** costTracking.budget — see src/cost/budget.js. Both limits are independent and both optional. */
+export interface BudgetConfig {
+  /** Cumulative-cost limit (USD) per MCP session id. Calls with no session id are never tracked. */
+  readonly perSessionUsd?: number;
+  /** Cumulative-cost limit (USD) per tool name. */
+  readonly perToolUsd?: number;
+}
+
+/** Options for {@link instrumentMcpServer}'s `costTracking` field. */
+export interface CostTrackingOptions {
+  /**
+   * Set to `false` to disable cost/token span attributes and the
+   * `mcp.tool.tokens.total` / `mcp.tool.cost.total` metrics entirely.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Overrides `DEFAULT_PRICING`. Supply your own table to price models it
+   * doesn't know about, or to correct stale pricing — see
+   * src/cost/pricing.js's docblock.
+   *
+   * @default DEFAULT_PRICING
+   */
+  pricingTable?: PricingTable;
+
+  /**
+   * Overrides `defaultExtractor`. Supply your own to recognize a tool
+   * result shape it doesn't.
+   *
+   * @default defaultExtractor
+   */
+  extractor?: UsageExtractor;
+
+  /**
+   * Per-session and per-tool cumulative-cost guardrails. Observability
+   * only — crossing a limit adds `mcp.tool.cost.budget_exceeded` /
+   * `mcp.tool.cost.budget_scope` span attributes; it never blocks or
+   * throws. Omit to disable budget tracking (the default).
+   */
+  budget?: BudgetConfig;
+}

package/src/index.d.ts

@@ -1,5 +1,6 @@
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CostTrackingOptions } from './cost/types.d.ts';
 
 /**
  * Options for {@link instrumentMcpServer}.
@@ -59,6 +60,14 @@ export interface InstrumentOptions {
    * @default false
    */
   setupNodeSdk?: boolean;
+
+  /**
+   * Controls the `mcp.tool.tokens.*` / `mcp.tool.model` / `mcp.tool.cost.*` span attributes, the
+   * `mcp.tool.tokens.total` / `mcp.tool.cost.total` metrics, and the optional per-session/per-tool budget
+   * guardrail. Any fields you omit from a partial object fall back to their defaults individually —
+   * `{ enabled: false }` alone works. See {@link CostTrackingOptions} (`src/cost/types.d.ts`).
+   */
+  costTracking?: CostTrackingOptions;
 }
 
 /**
@@ -125,3 +134,21 @@ export type {
 export { computeFingerprint } from './fingerprint/compose.js';
 export { toSpanAttributes, ATTRIBUTE_KEYS, METRIC_SAFE_ATTRIBUTES } from './fingerprint/attributes.js';
 export { DEFAULT_CLASSIFIERS } from './fingerprint/classify/index.js';
+
+// --- Cost & token attribution (src/cost/) ---
+//
+// Re-exported here so TypeScript consumers get these types/values from the
+// package root instead of reaching into src/cost/* directly. See
+// src/cost/types.d.ts for the full shape documentation.
+
+export type {
+  ModelPricing,
+  PricingTable,
+  UsageExtractor,
+  TokenUsage,
+  CostTrackingOptions,
+} from './cost/types.d.ts';
+
+export { DEFAULT_PRICING } from './cost/pricing.js';
+export { defaultExtractor } from './cost/extractor.js';
+export { calculateCost } from './cost/calculator.js';

package/src/index.js

@@ -3,3 +3,7 @@ export { instrumentMcpServer } from './instrument.js';
 export { computeFingerprint } from './fingerprint/compose.js';
 export { toSpanAttributes, ATTRIBUTE_KEYS, METRIC_SAFE_ATTRIBUTES } from './fingerprint/attributes.js';
 export { DEFAULT_CLASSIFIERS } from './fingerprint/classify/index.js';
+
+export { DEFAULT_PRICING } from './cost/pricing.js';
+export { defaultExtractor } from './cost/extractor.js';
+export { calculateCost } from './cost/calculator.js';

package/src/instrument.js

@@ -3,7 +3,7 @@
  */
 
 import { createRequire } from 'node:module';
-import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+import { trace, diag, SpanStatusCode, SpanKind } from '@opentelemetry/api';
 import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { NodeTracerProvider, SimpleSpanProcessor, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
@@ -14,13 +14,25 @@ import { StderrSpanExporter } from './exporters/stderr.js';
 import { setupMeter } from './metrics.js';
 import { computeFingerprint } from './fingerprint/compose.js';
 import { toSpanAttributes } from './fingerprint/attributes.js';
+import { calculateCost } from './cost/calculator.js';
+import { createBudgetTracker } from './cost/budget.js';
 import {
   ATTR_MCP_METHOD_NAME,
   ATTR_GEN_AI_TOOL_NAME,
   ATTR_GEN_AI_OPERATION_NAME,
+  ATTR_GEN_AI_RESPONSE_MODEL,
   ATTR_JSONRPC_REQUEST_ID,
   ATTR_MCP_TOOL_ARGUMENT_COUNT,
   ATTR_ERROR_TYPE,
+  ATTR_MCP_TOOL_TOKENS_INPUT,
+  ATTR_MCP_TOOL_TOKENS_OUTPUT,
+  ATTR_MCP_TOOL_TOKENS_TOTAL,
+  ATTR_MCP_TOOL_MODEL,
+  ATTR_MCP_TOOL_COST_USD,
+  ATTR_MCP_TOOL_COST_CURRENCY,
+  ATTR_MCP_TOOL_COST_BUDGET_EXCEEDED,
+  ATTR_MCP_TOOL_COST_BUDGET_SCOPE,
+  MCP_TOOL_COST_CURRENCY_USD,
   ERROR_TYPE_TOOL_ERROR,
   GEN_AI_OPERATION_NAME_EXECUTE_TOOL,
   MCP_METHOD_NAME_TOOLS_CALL,
@@ -137,6 +149,10 @@ export function instrumentMcpServer(input, options) {
 
   const tracer = setupTracer(server, resolved);
   const metricsRecorder = resolved.enableMetrics ? setupMeter(PACKAGE_VERSION) : null;
+  // One tracker per instrumented server, not per call — session/tool cost
+  // must accumulate across the server's whole lifetime (see
+  // src/cost/budget.js). A no-op tracker when costTracking.budget is unset.
+  const budgetTracker = createBudgetTracker(resolved.costTracking.budget);
   if (outer && server.shutdown) {
     outer.shutdown = server.shutdown;
   }
@@ -144,7 +160,14 @@ export function instrumentMcpServer(input, options) {
   const originalSetRequestHandler = server.setRequestHandler.bind(server);
   server.setRequestHandler = (schema, handler) => {
     if (schema === CallToolRequestSchema) {
-      handler = wrapToolCallHandler(handler, tracer, metricsRecorder, resolved.fingerprinting);
+      handler = wrapToolCallHandler(
+        handler,
+        tracer,
+        metricsRecorder,
+        resolved.fingerprinting,
+        resolved.costTracking,
+        budgetTracker,
+      );
     }
     return originalSetRequestHandler(schema, handler);
   };
@@ -229,6 +252,76 @@ function isToolResultError(result) {
   return result?.isError === true;
 }
 
+/**
+ * Best-effort cost/token attribution for one tool call's result, added on
+ * top of the span and metrics that always fire (see wrapToolCallHandler
+ * below). Runs `costTracking.extractor` (defaultExtractor by default — see
+ * src/cost/extractor.js) against `result`; if it finds recognizable usage,
+ * sets the three mcp.tool.tokens.* span attributes (+ mcp.tool.model and,
+ * for ecosystem-dashboard compatibility, gen_ai.response.model — see that
+ * constant's docblock in attributes.js for why both are set — when a model
+ * was detected) and records mcp.tool.tokens.total. If a model was
+ * detected, additionally runs calculateCost() (src/cost/calculator.js)
+ * against `costTracking.pricingTable` and, when it resolves (the model is
+ * in the table), sets mcp.tool.cost.usd / mcp.tool.cost.currency, records
+ * mcp.tool.cost.total, and runs `budgetTracker.recordAndCheck()`
+ * (src/cost/budget.js) — if that reports the call pushed a configured
+ * budget over its limit, sets mcp.tool.cost.budget_exceeded /
+ * mcp.tool.cost.budget_scope. An unrecognized model silently skips cost
+ * *and* budget attribution — the token attributes still land.
+ *
+ * No-op when `costTracking.enabled` is false. Called from both the
+ * isToolResultError and success branches below (there's a result to read
+ * usage from in either case); never from the thrown-exception catch block,
+ * since a thrown/rejected call never produced a result. The whole body is
+ * one try/catch — extractor.js, calculator.js, and budget.js already
+ * document themselves as never-throw, but span.setAttribute/
+ * metricsRecorder calls are outside their control, and this must never be
+ * why a tool call span fails to complete.
+ *
+ * @param {import('@opentelemetry/api').Span} span
+ * @param {ReturnType<import('./metrics.js').setupMeter> | null} metricsRecorder
+ * @param {string | undefined} toolName
+ * @param {string | undefined} sessionId
+ * @param {*} result
+ * @param {import('./config.js').CostTrackingOptions} costTracking
+ * @param {ReturnType<import('./cost/budget.js').createBudgetTracker>} budgetTracker
+ */
+function applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker) {
+  if (!costTracking.enabled) return;
+
+  try {
+    const usage = costTracking.extractor(result);
+    if (!usage) return;
+
+    span.setAttribute(ATTR_MCP_TOOL_TOKENS_INPUT, usage.inputTokens);
+    span.setAttribute(ATTR_MCP_TOOL_TOKENS_OUTPUT, usage.outputTokens);
+    span.setAttribute(ATTR_MCP_TOOL_TOKENS_TOTAL, usage.totalTokens);
+    if (usage.model) {
+      span.setAttribute(ATTR_MCP_TOOL_MODEL, usage.model);
+      span.setAttribute(ATTR_GEN_AI_RESPONSE_MODEL, usage.model);
+    }
+    metricsRecorder?.recordTokens(toolName, usage.model, usage.totalTokens);
+
+    if (usage.model) {
+      const costUsd = calculateCost(usage.inputTokens, usage.outputTokens, usage.model, costTracking.pricingTable);
+      if (costUsd !== null) {
+        span.setAttribute(ATTR_MCP_TOOL_COST_USD, costUsd);
+        span.setAttribute(ATTR_MCP_TOOL_COST_CURRENCY, MCP_TOOL_COST_CURRENCY_USD);
+        metricsRecorder?.recordCost(toolName, usage.model, costUsd);
+
+        const budgetResult = budgetTracker.recordAndCheck(sessionId, toolName, costUsd);
+        if (budgetResult.exceeded) {
+          span.setAttribute(ATTR_MCP_TOOL_COST_BUDGET_EXCEEDED, true);
+          span.setAttribute(ATTR_MCP_TOOL_COST_BUDGET_SCOPE, budgetResult.scope);
+        }
+      }
+    }
+  } catch (err) {
+    diag.debug('opentel-mcp: cost attribution failed, skipping mcp.tool.tokens.*/mcp.tool.cost.* attributes', err);
+  }
+}
+
 /**
  * Wraps a tools/call handler in a span covering its execution, plus the
  * mcp.tool.* metrics (see src/metrics.js). This sits as the innermost layer
@@ -253,18 +346,31 @@ function isToolResultError(result) {
  * threading the resulting failure category into the mcp.tool.errors /
  * mcp.tool.silent_failures / mcp.tool.duration metrics.
  *
+ * Cost/token attribution (see applyCostAttribution above and config.js's
+ * `costTracking` option) runs in both the isError and success branches,
+ * independently of fingerprinting — a tool call can carry token usage
+ * whether or not it ultimately succeeded.
+ *
  * @param {Function} handler
  * @param {import('@opentelemetry/api').Tracer} tracer
  * @param {ReturnType<import('./metrics.js').setupMeter> | null} metricsRecorder
  * @param {boolean} fingerprintingEnabled
+ * @param {import('./config.js').CostTrackingOptions} costTracking
+ * @param {ReturnType<import('./cost/budget.js').createBudgetTracker>} budgetTracker
  */
-function wrapToolCallHandler(handler, tracer, metricsRecorder, fingerprintingEnabled) {
+function wrapToolCallHandler(handler, tracer, metricsRecorder, fingerprintingEnabled, costTracking, budgetTracker) {
   return (request, extra) => {
     const toolName = request?.params?.name;
     const spanName = toolName ? `${TOOLS_CALL_METHOD} ${toolName}` : TOOLS_CALL_METHOD;
 
     return tracer.startActiveSpan(spanName, { kind: SpanKind.SERVER }, async (span) => {
       const argumentCount = Object.keys(request?.params?.arguments ?? {}).length;
+      // Transport-provided session id (undefined for stdio, which has no
+      // notion of a session) — see the sessionId param on the SDK's
+      // RequestHandlerExtra type. Only consumed by applyCostAttribution's
+      // per-session budget tracking (src/cost/budget.js); everything else
+      // in this function already worked without it.
+      const sessionId = extra?.sessionId;
 
       span.setAttribute(ATTR_MCP_METHOD_NAME, TOOLS_CALL_METHOD);
       span.setAttribute(ATTR_GEN_AI_OPERATION_NAME, GEN_AI_OPERATION_NAME_EXECUTE_TOOL);
@@ -290,6 +396,7 @@ function wrapToolCallHandler(handler, tracer, metricsRecorder, fingerprintingEna
             span.setAttributes(toSpanAttributes(failure));
             failureCategory = failure.category;
           }
+          applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker);
           metricsRecorder?.recordSilentFailure(toolName, failureCategory);
           metricsRecorder?.recordDuration(
             toolName,
@@ -299,6 +406,7 @@ function wrapToolCallHandler(handler, tracer, metricsRecorder, fingerprintingEna
           );
         } else {
           span.setStatus({ code: SpanStatusCode.OK });
+          applyCostAttribution(span, metricsRecorder, toolName, sessionId, result, costTracking, budgetTracker);
           metricsRecorder?.recordDuration(toolName, performance.now() - startTime, MCP_TOOL_OUTCOME_SUCCESS);
         }
         return result;

package/src/metrics.js

@@ -35,6 +35,7 @@ import {
   ATTR_GEN_AI_TOOL_NAME,
   ATTR_ERROR_TYPE,
   ATTR_MCP_TOOL_OUTCOME,
+  ATTR_MCP_TOOL_MODEL,
   MCP_METHOD_NAME_TOOLS_CALL,
 } from './attributes.js';
 import { ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
@@ -51,12 +52,22 @@ import { ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
  * enough to be metric-safe (see METRIC_SAFE_ATTRIBUTES); callers omit it
  * (or pass '') when fingerprinting is disabled or produced no category.
  *
+ * `model` (recordTokens, recordCost) follows the same optional-attribute
+ * pattern: added to the bag only when the cost extractor actually found a
+ * model name (see instrument.js's applyCostAttribution()), so a run with
+ * no model detection doesn't create a spurious `mcp.tool.model: undefined`
+ * time series. Model names are bounded in practice by how many distinct
+ * models a deployment actually calls, the same cardinality argument this
+ * package already relies on for `gen_ai.tool.name` on every other counter.
+ *
  * @param {string} packageVersion
  * @returns {{
  *   recordCall: (toolName: string | undefined) => void,
  *   recordError: (toolName: string | undefined, errorType: string, failureCategory?: string) => void,
  *   recordSilentFailure: (toolName: string | undefined, failureCategory?: string) => void,
  *   recordDuration: (toolName: string | undefined, durationMs: number, outcome: string, failureCategory?: string) => void,
+ *   recordTokens: (toolName: string | undefined, model: string | undefined, totalTokens: number) => void,
+ *   recordCost: (toolName: string | undefined, model: string | undefined, costUsd: number) => void,
  * }}
  */
 export function setupMeter(packageVersion) {
@@ -76,6 +87,14 @@ export function setupMeter(packageVersion) {
     description: 'Duration of MCP tool call execution.',
     unit: 'ms',
   });
+  const tokensTotal = meter.createCounter('mcp.tool.tokens.total', {
+    description: 'Total input + output tokens attributed to MCP tool calls (see src/cost/extractor.js).',
+    unit: 'tokens',
+  });
+  const costTotal = meter.createCounter('mcp.tool.cost.total', {
+    description: 'Total estimated cost of MCP tool calls (see src/cost/calculator.js).',
+    unit: 'USD',
+  });
 
   return {
     recordCall(toolName) {
@@ -104,5 +123,17 @@ export function setupMeter(packageVersion) {
         ...(failureCategory ? { [ATTRIBUTE_KEYS.CATEGORY]: failureCategory } : {}),
       });
     },
+    recordTokens(toolName, model, totalTokens) {
+      tokensTotal.add(totalTokens, {
+        [ATTR_GEN_AI_TOOL_NAME]: toolName,
+        ...(model ? { [ATTR_MCP_TOOL_MODEL]: model } : {}),
+      });
+    },
+    recordCost(toolName, model, costUsd) {
+      costTotal.add(costUsd, {
+        [ATTR_GEN_AI_TOOL_NAME]: toolName,
+        ...(model ? { [ATTR_MCP_TOOL_MODEL]: model } : {}),
+      });
+    },
   };
 }