@auvh/climeter-mcp

Wraps arbitrary MCP server tools with metering middleware that intercepts tool invocations without modifying the underlying tool logic. Uses a decorator/proxy pattern to inject usage tracking at the MCP protocol boundary, capturing invocation metadata (tool name, input size, execution time, output tokens) before passing through to the original tool handler. Maintains full MCP protocol compatibility while adding observability hooks for billing calculations.

Automatically extracts structured usage metrics from each MCP tool invocation, including execution duration, input/output token counts (if applicable), tool name, and invocation timestamp. Aggregates metrics across multiple invocations into usage events that can be exported for billing. Supports custom metric extractors for tool-specific billing dimensions (e.g., API calls made by a tool, database queries executed).

Converts metered usage data into billing-ready events that can be exported to external billing systems (Stripe, custom databases, data warehouses). Generates structured billing events with tool usage, metrics, timestamps, and optional customer/tenant identifiers. Supports batch export and streaming event emission for real-time billing pipelines. Events are formatted as JSON and can be written to files, HTTP endpoints, or message queues.

Provides mechanisms to tag and isolate usage metrics by tenant, customer, or API key, enabling accurate cost attribution in multi-tenant MCP deployments. Supports tenant context propagation through MCP request metadata or custom headers, ensuring each tool invocation is attributed to the correct billing entity. Enables per-tenant usage reports and cost breakdowns without cross-contamination of metrics.

Provides a plugin interface for defining custom metric extractors that can capture tool-specific billing dimensions beyond standard execution time and token counts. Extractors are functions that receive the tool invocation request/response and can compute arbitrary metrics (e.g., number of database queries, external API calls, data volume processed). Extracted metrics are included in billing events and usage reports, enabling fine-grained cost attribution based on tool behavior.

Enforces usage quotas and rate limits based on metered tool invocations, preventing over-consumption and enabling fair-use policies. Supports per-tenant quotas (e.g., max 1000 tool calls per month), per-tool rate limits (e.g., max 10 calls/second), and custom quota rules. Blocks or throttles tool invocations when quotas are exceeded, returning quota-exceeded errors to the caller. Quotas can be reset on configurable schedules (daily, monthly, etc.).