# Usage Lab

> Usage Lab is an MCP server for developer tools. Record idempotent usage events and read monthly per-customer rollups for billing. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Platforms:** API
- **Website:** https://usage-lab.pages.dev/docs/mcp/
- **MCP Registry name:** dev.pages.usage-lab/usage-lab
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [finance and payments](https://ai-powered.com/categories/finance-and-payments)
- **Listing updated:** 2026-11-14

## About

Usage-based billing needs events that are safe to retry, and this server is built around that. `record_usage_events` takes 1 to 100 events per call, each with its own idempotency key. Batches are all-or-nothing on validation errors; repeating a key with the same payload returns a duplicate, while the same key with a different payload is a conflict and the original is kept. `create_meter` defines a meter with an aggregation of sum, count or unique count.

Reads include `list_meters`, `get_meter_rollups` for a month and optional subscription, and `get_account` for plan, limits and event count. `get_docs` returns a quickstart without a key. The tools are thin wrappers over the public API, so limits and errors match, and API errors return as results with isError set.

It is a stateless remote server over Streamable HTTP; GET returns 405. A key is passed as a bearer token or X-Api-Key, and a free key is available at signup. Initialize, tools/list and get_docs work without one. Config is shown for Claude Code, Cursor, VS Code, Claude Desktop through mcp-remote, and the OpenAI Agents SDK.

## Features

- **Retry-safe events:** Each event carries an idempotency key, so retries never double count.
- **Batch recording:** Up to 100 events per call, validated all-or-nothing.
- **Meter management:** Create and list meters with sum, count or unique count.
- **Monthly rollups:** Per-customer totals for a month.
- **Account view:** Plan, limits and event count.
- **Keyless docs:** Handshake, tool list and quickstart need no key.

## Good for

- Let an agent meter API calls or tokens per customer
- Backfill usage events safely after a failure
- Read a customer's monthly total before invoicing
- Create a new meter for a feature

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http usage-lab https://usage-lab.pages.dev/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://usage-lab.pages.dev/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "usage-lab": {
      "url": "https://usage-lab.pages.dev/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "usage-lab": {
      "type": "http",
      "url": "https://usage-lab.pages.dev/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "usage-lab": {
      "serverUrl": "https://usage-lab.pages.dev/mcp"
    }
  }
}
```

### Grok Bot (Grok Bot desktop app → Connect apps → Add a custom connector)

```sh
https://usage-lab.pages.dev/mcp
```

Enter a Name (for example "Usage Lab"), choose Type: Remote HTTPS, paste this as the Server URL and choose Add plugin.

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "usage-lab": {
      "type": "http",
      "url": "https://usage-lab.pages.dev/mcp"
    }
  }
}
```

## Tools

- `get_docs`: Quickstart for keys, meters, idempotent events and rollups; needs no key.
- `list_meters`: Lists meters.
- `create_meter`: Creates a meter with sum, count or unique_count aggregation.
- `record_usage_events`: Records 1 to 100 usage events, each with an idempotency key.
- `get_meter_rollups`: Reads monthly per-customer rollups for a meter.
- `get_account`: Returns plan, limits and event count.

## FAQ

### How do I authenticate?

Send your API key as a bearer token or X-Api-Key; a free key is available at signup.

### What if I resend an event?

The same key and payload returns duplicate; a different payload under the same key conflicts and the original is kept.

### How many events per batch?

Between 1 and 100.

### Which aggregations exist?

Sum, count and unique count.

### How do I add Usage Lab to Claude Code?

Run this command in your terminal: claude mcp add --transport http usage-lab https://usage-lab.pages.dev/mcp

### What are the best alternatives to Usage Lab?

The closest alternatives to Usage Lab are MCP, Locus, API Meter, MCP Claude Usage Guard and Claude Usage.

## Where this comes from

- Description: written from the project's website.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [MCP](https://ai-powered.com/mcp/mcp-mwenpji1): MCP is an MCP server for finance and payments.
- [Locus](https://ai-powered.com/mcp/locus-2): Locus is a freemium MCP server for finance and payments.
- [API Meter](https://ai-powered.com/mcp/api-meter): API Meter is a freemium MCP server for analytics and data.
- [MCP Claude Usage Guard](https://ai-powered.com/mcp/mcp-claude-usage-guard): MCP Claude Usage Guard is an open-source MCP server for developer tools.
- [Claude Usage](https://ai-powered.com/mcp/claude-usage): Claude Usage is an open-source MCP server for ai models and llm tooling.
- [lake-meter](https://ai-powered.com/mcp/lake-meter): lake-meter is an open-source MCP server for developer tools.
- [RevClamp MCP Server](https://ai-powered.com/mcp/revclamp-mcp-server): RevClamp MCP Server is a freemium MCP server for finance and payments.
- [AI Usage](https://ai-powered.com/mcp/ai-usage): AI Usage is an MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/usage-lab
