SYSTEM ACTIVE
m mcpmeter
Sign up
Sign up Sign in
HOME / DOCS / HEADERS
DOCS NAV · HEADERS ▾
GET STARTED
Quickstart Concepts
INTEGRATIONS
Clients & code samples
META
Changelog
DOC CORE

HEADERS

Every request and response header the proxy sets, plus what to do with them.

v0.1.0 UPDATED 2026-05-09 ~3 MIN READ

REQUEST HEADERS

You only need to set one header. Everything else flows through unchanged.

HEADERREQUIREDNOTES
Authorization YES Bearer key — Bearer mcpm_live_…. See authentication.
Content-Type — Set by your MCP client. application/json for HTTP transport.
Accept — For SSE transport, your client will set Accept: text/event-stream.
X-Mcpmeter-Project — Optional. Override the project bound to your key for this call (must belong to you). Used by multi-tenant clients.

RESPONSE HEADERS

Every proxied response — success or failure — carries metering metadata:

HEADERVALUEWHEN
X-Mcpmeter-Request-Id UUID v4 Always. Quote this when reporting issues to support.
X-Mcpmeter-Billed free or µ¢ amount Always on 200. free if the call hit the free tier; otherwise the integer µ¢ debited.
X-Mcpmeter-Duration-Ms integer Always. Total proxy latency including upstream round-trip.
X-Mcpmeter-Balance µ¢ remaining Always. Useful for surfacing balance in your client UI without hitting the dashboard.
Retry-After seconds Only on 429. Wait at least this long before retrying. See rate limits.
WWW-Authenticate Bearer Only on 401. RFC 6750.

EXAMPLE

A successful, paid call to weather.get_current:

response headersHTTP/1.1 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Mcpmeter-Request-Id: 7f3a4c1e-b2d5-4a8c-9f1e-2c7b8d4a5e6f
X-Mcpmeter-Billed: 200
X-Mcpmeter-Duration-Ms: 142
X-Mcpmeter-Balance: 999800

This call was billed 200 µ¢ ($0.0002), took 142 ms, and the consumer has 999,800 µ¢ ($0.9998) left.

FREE-TIER EXAMPLE

Same call, but within the publisher's free allowance:

response headersHTTP/1.1 200
HTTP/1.1 200 OK
X-Mcpmeter-Request-Id: 8b2c5e9f-…
X-Mcpmeter-Billed: free
X-Mcpmeter-Duration-Ms: 138
X-Mcpmeter-Balance: 1000000

No debit, balance unchanged. See free tier for how the allowance counter works.

READING HEADERS IN YOUR CLIENT

Most MCP clients abstract the HTTP layer away — you don't see headers from inside Claude Desktop or Cursor. The headers are useful when you're:

  • Debugging with curl or HTTPie (see clients for raw examples).
  • Building a custom MCP client and want to surface balance/cost in your UI.
  • Triaging a support issue — X-Mcpmeter-Request-Id lets us find the call in O(1).