Usage Metering for MCP Servers: Track Every Tool Invocation

Your MCP server has users. But how many times are they actually calling your tools? Which tools are popular? Who's hitting their limits? Usage metering answers all of it.

Why metering matters

You can't improve what you don't measure. Without usage metering, you're flying blind:

Usage metering turns your MCP server from a black box into a product you can understand, optimize, and grow.

What Vend tracks

When you call guard.recordUsage(), Vend records:

All of this feeds into the Vend dashboard, where you can see top tools, invocation counts, and per-key usage at a glance.

Recording usage

The SDK makes usage recording a one-liner. By default it's fire-and-forget — the API call happens in the background so it doesn't slow down your tool response:

// Fire-and-forget (default)
guard.recordUsage('search');

// The tool response returns immediately
// Usage is recorded asynchronously

If you need to confirm the recording (for example, to check whether the user has exceeded their rate limit), you can await it:

const ok = await guard.recordUsage('search');

if (!ok) {
  return {
    content: [{
      type: 'text',
      text: 'You\'ve reached your daily limit. Upgrade for more.',
    }],
  };
}

Rate limiting by tier

Each tier in Vend can have a request limit — the maximum number of tool invocations per day. This is configured in the dashboard when you create a tier:

When a key exceeds its limit, the usage API returns a failure. You decide how to handle it — block the call, show an upgrade message, or degrade gracefully.

Vend also fires a usage.limit_reached webhook so you can trigger alerts, send upgrade emails, or log the event in your own systems.

Using the createToolGuard wrapper

If you want usage recording to happen automatically for every gated tool call, use the createToolGuard wrapper:

import { vendAuth, createToolGuard } from '@yawlabs/vend-mcp';

const guard = vendAuth({
  apiKey: process.env.VEND_API_KEY!,
  gates: {
    search:  'free',
    analyze: 'pro',
  },
});

const toolGuard = createToolGuard(guard);

// In your MCP handler:
server.setRequestHandler('tools/call', async (req) => {
  return toolGuard(req, async () => {
    // Your tool logic here
    // Usage is recorded automatically on success
  });
});

The wrapper validates the key, checks tier access, runs your handler, and records usage — all in one call. If the key is invalid or the tier is too low, it returns an appropriate error message without running your handler.

Analytics in the dashboard

The Vend dashboard surfaces your usage data in two views:

Usage tab shows the last 30 days of activity: total invocations, unique tools used, and a ranked list of your most popular tools with invocation counts. This tells you what your users actually care about.

Revenue tab connects usage to money: total sales, gross revenue, platform fees, and your net earnings. Cross-reference usage with revenue to understand which tools drive upgrades.

Observable hooks

For advanced observability, the SDK exposes hooks you can wire into your logging, metrics, or alerting system:

const guard = vendAuth({
  apiKey: process.env.VEND_API_KEY!,
  gates: { /* ... */ },

  onUsage(toolName, success) {
    metrics.increment('mcp.tool.invocation', {
      tool: toolName,
      success: String(success),
    });
  },

  onValidate(result, fromCache) {
    if (!result.valid) {
      logger.warn('Invalid key attempt', {
        reason: result.reason,
      });
    }
  },

  onError(operation, error) {
    sentry.captureException(error, {
      tags: { operation },
    });
  },
});

These hooks let you integrate Vend with whatever observability stack you already use — Datadog, Grafana, PagerDuty, or a simple log file.

What usage data tells you

Once you're collecting usage data, look for these signals:

Start tracking usage today. Create a Vend project, add guard.recordUsage() to your tools, and see what your users are actually doing.