mcpspend-cost-tracking

MCPSpend Cost Tracking Skill

Skill by ara.so — MCP Skills collection.

MCPSpend provides real-time cost observability for Model Context Protocol (MCP) tool calls. It wraps any MCP server as a transparent proxy, attributing spend per tool, project, and customer across Claude Desktop, Cursor, Windsurf, and VS Code.

Installation

One-command setup (recommended)

npx --yes @mcpspend/proxy@latest init --key mcps_live_YOUR_KEY

This auto-detects your MCP clients (Claude Desktop, Cursor, Windsurf, VS Code) and wraps all configured servers. It creates a .mcpspend.bak backup of your original config.

Manual installation

npm install -g @mcpspend/proxy
# or
pnpm add -g @mcpspend/proxy

Get API key

1. Visit mcpspend.com
2. Sign up (free tier: 25K calls/month)
3. Copy your API key from the dashboard

Configuration

Wrapping existing MCP servers

MCPSpend modifies your MCP client config to route through the proxy. Example transformation:

Before (Claude Desktop config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/docs"]
    }
  }
}

After (automatic wrapping):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@mcpspend/proxy@latest",
        "wrap",
        "--key",
        "mcps_live_YOUR_KEY",
        "--server",
        "filesystem",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/docs"
      ]
    }
  }
}

Environment variables

export MCPSPEND_API_KEY=mcps_live_YOUR_KEY
export MCPSPEND_API_URL=https://api.mcpspend.com  # optional, default

Client-specific config locations

Client	Config path
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.windsurf/mcp_config.json
VS Code (user)	~/.vscode/mcp.json
VS Code (workspace)	.vscode/mcp.json

CLI Commands

Initialize proxy wrapper

# Auto-detect and wrap all MCP servers
mcpspend-proxy init --key mcps_live_YOUR_KEY

# Specify client explicitly
mcpspend-proxy init --key mcps_live_YOUR_KEY --client cursor

# Dry run (preview changes)
mcpspend-proxy init --key mcps_live_YOUR_KEY --dry-run

Wrap individual server

mcpspend-proxy wrap \
  --key mcps_live_YOUR_KEY \
  --server my-server \
  -- \
  npx -y @some/mcp-server --arg value

Wrap HTTP/SSE remote servers

mcpspend-proxy wrap-http \
  --key mcps_live_YOUR_KEY \
  --url https://remote-mcp-server.com \
  --server remote-server

Unwrap (restore original config)

mcpspend-proxy unwrap --client claude

MCP Server for Usage Queries

Add the MCPSpend MCP server to query your usage from within any MCP client:

{
  "mcpServers": {
    "mcpspend": {
      "command": "npx",
      "args": ["-y", "@mcpspend/mcp-server"],
      "env": {
        "MCPSPEND_API_KEY": "mcps_live_YOUR_KEY"
      }
    }
  }
}

Available tools

// Get today's cost
{
  "name": "get_today_cost",
  "arguments": {}
}

// List top tools by cost
{
  "name": "list_top_tools",
  "arguments": {
    "limit": 10,
    "startDate": "2026-01-01",
    "endDate": "2026-01-31"
  }
}

// Get tool usage details
{
  "name": "get_tool_usage",
  "arguments": {
    "toolName": "filesystem_read",
    "days": 7
  }
}

// List recent sessions
{
  "name": "list_sessions",
  "arguments": {
    "limit": 20
  }
}

HTTP MCP Server (Remote Access)

Query usage via HTTP from any MCP client that supports HTTP transport:

Endpoint: https://api.mcpspend.com/api/mcp

Authentication: Bearer token

{
  "mcpServers": {
    "mcpspend-remote": {
      "url": "https://api.mcpspend.com/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer mcps_live_YOUR_KEY"
      }
    }
  }
}

Code Examples

TypeScript: Manual proxy integration

import { MCPSpendProxy } from '@mcpspend/proxy';

const proxy = new MCPSpendProxy({
  apiKey: process.env.MCPSPEND_API_KEY!,
  serverName: 'my-custom-server',
  organizationId: 'org_123', // optional, for multi-tenant
  metadata: {
    project: 'production',
    customer: 'acme-corp'
  }
});

// Wrap an MCP server process
await proxy.wrap({
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/data']
});

TypeScript: Programmatic usage query

import { MCPSpendClient } from '@mcpspend/proxy';

const client = new MCPSpendClient(process.env.MCPSPEND_API_KEY!);

// Get usage for date range
const usage = await client.getUsage({
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  groupBy: 'tool'
});

console.log(usage.totalCost);
console.log(usage.topTools);

// Export to CSV
const csv = await client.exportCSV({
  startDate: '2026-01-01',
  endDate: '2026-01-31'
});

JavaScript: Simple wrapper script

#!/usr/bin/env node
const { spawn } = require('child_process');
const { MCPSpendProxy } = require('@mcpspend/proxy');

const proxy = new MCPSpendProxy({
  apiKey: process.env.MCPSPEND_API_KEY,
  serverName: 'filesystem',
  metadata: {
    environment: process.env.NODE_ENV || 'development'
  }
});

proxy.wrap({
  command: process.argv[2],
  args: process.argv.slice(3)
}).catch(console.error);

Common Patterns

Per-customer attribution

{
  "mcpServers": {
    "customer-fs": {
      "command": "npx",
      "args": [
        "-y", "@mcpspend/proxy@latest", "wrap",
        "--key", "mcps_live_YOUR_KEY",
        "--server", "filesystem",
        "--metadata", "{\"customer\":\"acme-corp\",\"project\":\"website\"}",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/customer-data"
      ]
    }
  }
}

Budget alerts

Set up in dashboard at mcpspend.com/dashboard/alerts:

• Daily/weekly/monthly thresholds
• Per-tool or per-project limits
• Slack/email notifications
• Auto-pause on budget exceeded

Multi-environment tracking

# Development
MCPSPEND_API_KEY=mcps_live_DEV_KEY \
MCPSPEND_METADATA='{"env":"dev"}' \
mcpspend-proxy wrap --server dev-fs -- npx ...

# Production
MCPSPEND_API_KEY=mcps_live_PROD_KEY \
MCPSPEND_METADATA='{"env":"prod"}' \
mcpspend-proxy wrap --server prod-fs -- npx ...

Filtering and querying

// Query specific tool usage
const fsUsage = await client.getToolUsage('filesystem_read', {
  startDate: '2026-01-01',
  metadata: {
    customer: 'acme-corp'
  }
});

// Get aggregated stats
const stats = await client.getAggregatedStats({
  groupBy: ['tool', 'model'],
  startDate: '2026-01-01',
  endDate: '2026-01-31'
});

Troubleshooting

Proxy not reporting data

Check API key:

curl -H "Authorization: Bearer mcps_live_YOUR_KEY" \
  https://api.mcpspend.com/api/health

Verify proxy is active:

# Check if config was modified
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | grep mcpspend

# Check for backup
ls -la ~/Library/Application\ Support/Claude/.mcpspend.bak

Enable debug logging:

export MCPSPEND_DEBUG=1
# Restart your MCP client

Config not auto-detected

# Manually specify config path
mcpspend-proxy init \
  --key mcps_live_YOUR_KEY \
  --config /path/to/mcp.json

Tool calls not attributed correctly

Ensure --server name matches your config:

{
  "mcpServers": {
    "my-server-name": {  // ← This must match --server flag
      "command": "npx",
      "args": ["@mcpspend/proxy", "wrap", "--server", "my-server-name", ...]
    }
  }
}

High latency

The proxy adds ~1-5ms overhead per tool call. If experiencing issues:

# Check proxy version
npx @mcpspend/proxy --version

# Update to latest
npm update -g @mcpspend/proxy

Rate limits

Free tier: 25K calls/month. If exceeded:

• Upgrade at mcpspend.com/pricing
• Check current usage: mcpspend-proxy usage
• Set up budget alerts in dashboard

Unwrap servers

# Restore from backup
mcpspend-proxy unwrap --client claude

# Or manually restore
cp ~/Library/Application\ Support/Claude/.mcpspend.bak \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json

Privacy & Security

• No tool arguments or responses are sent to MCPSpend servers
• Only metadata tracked: tool name, server name, model, latency, success, approximate token count
• API keys stored as SHA-256 hashes
• EU-hosted (GDPR compliant)
• Self-serve data export/deletion at mcpspend.com/dashboard/account/privacy

Resources

• Dashboard: mcpspend.com/dashboard
• API docs: mcpspend.com/docs
• npm package: @mcpspend/proxy
• GitHub: andreisirbu91-lab/MCPSpend
• Support: support@mcpspend.com