API Reference

MCPSpend API

Everything the proxy and dashboard use is also available to you. Stable URLs at https://api.mcpspend.com, JSON in, JSON out, Bearer-token auth, 429 with Retry-After on rate limits.

Base URL

api.mcpspend.com

Auth header

Authorization: Bearer mcps_live_…

Rate limit

1000 req / min / IP

Get an API key

Sign in → Dashboard / API Keys → "Create API key". Keys start with mcps_live_ on production, mcps_test_ for test mode. We hash with SHA-256 and never store plaintext — copy yours immediately.

Compatible MCP servers

MCPSpend wraps any MCP server you run locally — stdio or HTTP — including Figma, Gmail, Canva, Vercel, ClickUp, Google Drive/Calendar when you mount them as local HTTP MCPs. The proxy is transport-agnostic.

✓ Local stdio MCPs — automatic

One CLI command auto-detects and wraps. Works with anything that runs as a subprocess:

• npx servers (most npm MCPs)
• uvx / python / pipx
• docker run …
• node, bun, deno
• Absolute-path binaries
• Custom shell scripts

mcpspend add

✓ Remote HTTP MCPs — via bridge

For HTTP-only MCPs, our stdio↔HTTP bridge wraps the remote endpoint as if it were local. Verified with:

• Figma (mcp.figma.com)
• Vercel MCP
• Gmail / Google Drive / Calendar
• Canva MCP
• ClickUp MCP
• Any custom HTTP MCP

mcpspend wrap-http --url https://mcp.figma.com

⚠ Claude.ai web-only OAuth connectors

When you click "Connect Figma" inside the claude.ai web interface, nothing runs on your machine — everything is server-side at Anthropic.

Workaround: use the same provider as a local HTTP MCP (column 2) — fully observable.

Affects only OAuth connectors mounted inside claude.ai web (not Desktop, Cursor, Windsurf, VS Code, Claude Code — those all expose local MCP config we wrap).

Verified providers (across stdio + HTTP bridge):

filesystemgithubplaywrightpuppeteerfetchsqlitepostgresfigmafigma (HTTP)slackgmailgoogle-drivegoogle-calendarcanvavercelclickupnotionlinearjirastripememorysequentialthinkingtimebrave-searchtavilyfirecrawldockeraws-s3redis

Ingest

Submit tool-call events. Used by the proxy under the hood — you only call this directly if you build a custom integration.

POST/api/ingestBearer mcps_live_…

Submit one tool call or a batch (≤ 500).

Send an ARRAY for batch (faster). customerLabel is optional and lets you slice spend by your own end-customer.

curl -X POST https://api.mcpspend.com/api/ingest \
  -H "Authorization: Bearer mcps_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "serverName": "filesystem",
    "toolName": "read_file",
    "model": "claude-sonnet-4-6",
    "inputTokens": 240,
    "outputTokens": 50,
    "latencyMs": 120,
    "success": true,
    "customerLabel": "acme-corp"
  }'

Statistics

Read-only aggregates for dashboards and reporting.

GET/api/stats/overview?days=30&projectId=…Bearer mcps_live_…

KPIs, daily totals, top tools, top servers.

curl -H "Authorization: Bearer mcps_live_xxx" \
  https://api.mcpspend.com/api/stats/overview?days=30

GET/api/stats/customers?days=30&limit=10Bearer mcps_live_…

Top end-customers by cost (uses customerLabel from ingest).

GET/api/stats/forecastBearer mcps_live_…

End-of-month projection with uncertainty band (USD ± stddev).

Recency-weighted moving average + day-of-week seasonality. Returns linearProjectedUsd alongside the smart forecast so you can show both.

GET/api/stats/predict?serverName=…&toolName=…&model=…Bearer mcps_live_…

Estimate the USD cost of a specific tool call BEFORE invoking it. Pre-call cost prediction.

Returns median + P90 + average from your last 30 days. isUnknown=true when no baseline exists. Surfaced as the estimate_cost MCP tool so agents can self-throttle.

GET/api/stats/sessions?limit=20&offset=0Bearer mcps_live_…

List recent sessions.

GET/api/stats/sessions/:idBearer mcps_live_…

Single session header + all its tool calls.

Export

CSV exports for offline analysis. Requires Pro plan or higher.

GET/api/export/tool-calls.csv?days=30&projectId=…User JWT

Stream tool calls as CSV. Cursor-paginated internally, supports up to 1M rows per export.

Streams up to 1,000,000 rows. Header: calledAt, project, server, tool, model, inputTokens, outputTokens, costUsd, latencyMs, success, errorCode, sessionId.

Organizations

Manage org-level settings, members, and billing context.

GET/api/organizationsUser JWT

List orgs the current user belongs to.

POST/api/organizationsUser JWT

Create a new organization.

GET/api/organizations/currentBearer mcps_live_…

Current org details + month-to-date spend.

PATCH/api/organizations/currentUser JWT

Update org name, Slack webhook, monthly $ budget.

OWNER/ADMIN only. Slack webhook URL is encrypted at rest with AES-256-GCM.

GET/api/organizations/current/membersUser JWT

List members.

Projects

Group tool-call data by team, environment, or initiative.

GET/api/projectsBearer mcps_live_…

List projects in the current org.

POST/api/projectsUser JWT

Create a project. FREE plan: 1 project max.

DELETE/api/projects/:idUser JWT

Delete a project (cascades all data).

API Keys

Manage your mcps_live_… keys for proxy authentication.

GET/api/keysUser JWT

List API keys (prefix only, never plaintext).

POST/api/keysUser JWT

Create a new API key — response includes plaintext ONCE.

Keys are SHA-256 hashed on the server. Save the plaintext immediately; you cannot retrieve it later.

POST/api/keys/:id/revokeUser JWT

Revoke a key. Future requests with it will 401.

Account (GDPR)

Self-serve data export and deletion per GDPR Art. 15 / 17 / 20.

POST/api/account/data-exportUser JWT

Download a JSON dump of every piece of personal data we hold about you.

POST/api/account/deleteUser JWT

Anonymise + delete the account. Body: {"confirm":"DELETE"}

If you are the sole OWNER of an org, transfer ownership first. See https://mcpspend.com/legal/data-rights.

Slack slash commands

Query MCPSpend from any Slack channel. Setup: Slack workspace → Add app → Slash Command → URL points at /api/slack/cmd?key=mcps_live_xxx. No OAuth dance.

POST/api/slack/cmd?key=mcps_live_…Bearer mcps_live_…

Slash command endpoint. Subcommands: today, top [days], budget, help.

Slack posts form-encoded; we respond with Block Kit JSON within 3s. Use a dedicated API key per workspace if you want to revoke independently.

GitHub Action

Drop-in workflow that posts an MCPSpend cost summary on every PR — the team sees agent spend at the same place they review code.

GETandreisirbu91-lab/mcpspend-action@v1Public

Composite GitHub Action — see /packages/github-action in the repo.

Add to .github/workflows/mcpspend.yml — needs MCPSPEND_API_KEY secret + pull-requests: write permission. Idempotent: updates the existing comment on push instead of stacking new ones.

MCP (HTTP)

JSON-RPC endpoint compatible with the MCP HTTP transport. Query your usage from any MCP client.

POST/api/mcpBearer mcps_live_…

JSON-RPC: initialize / tools/list / tools/call.

Public tool try_demo works without auth — used by Smithery preview.

GET/.well-known/mcp/server-card.jsonPublic

MCP server discovery card (RFC-style).

GET/.well-known/oauth-protected-resourcePublic

OAuth 2.0 Protected Resource Metadata (RFC 9728).

Errors

All errors return a JSON body with an error string. Common codes:

400	Validation error in payload
401	Missing / invalid / revoked key
402	Plan does not include this feature — body has `upgradeUrl`
403	Insufficient role (OWNER/ADMIN required for destructive ops)
404	Resource not found in your org
409	Conflict (e.g. duplicate invite, sole-owner deletion)
429	Rate-limited or quota exceeded — see `Retry-After`
5xx	Upstream issue — retries are safe (ingest is idempotent)

Need an OpenAPI spec or SDK?

Email support@mcpspend.com and we'll prioritise it. TypeScript & Python SDKs are on the Q3 2026 roadmap.