MCP Billing Spec v1

Abstract

This specification defines a standard schema for billing, metering, receipts, verification, and dispute resolution in MCP (Model Context Protocol) tool ecosystems. It is designed to be implementable by any billing provider, marketplace, or MCP server operator. The spec is bigger than any single implementation.

Status

Draft. Feedback welcome at GitHub Issues or agents@noui.bot.

1. Meter Event Schema

A meter event records a single tool invocation through a billing-aware proxy or middleware.

{
  "event_id": "evt_a1b2c3d4e5f6",
  "tool_id": "string (tool identifier)",
  "tool_name": "string (human-readable tool name)",
  "agent_id": "string (consumer/agent identifier)",
  "provider_id": "string (tool provider identifier)",
  "timestamp": "ISO 8601 datetime",
  "duration_ms": 234,
  "status": "success | error | timeout | rate_limited",
  "cost_microcents": 50000,
  "input_tokens": 150,
  "output_tokens": 420,
  "metadata": {}
}

Required Fields

• tool_id or tool_name — at least one must be present
• agent_id — identifies the consumer
• provider_id — identifies the tool operator
• timestamp — ISO 8601 with timezone
• status — one of: success, error, timeout, rate_limited

Optional Fields

• duration_ms — wall-clock execution time
• cost_microcents — cost in microcents (1 microcent = 1/10000 of a cent)
• input_tokens, output_tokens — token counts for LLM-backed tools
• metadata — arbitrary key-value pairs

Cost Precision

$0.05 per call = 500,000 microcents
$0.005 per call = 50,000 microcents
$0.0001 per call = 1,000 microcents

2. Receipt Schema

Every metered invocation SHOULD generate a signed receipt. Receipts provide tamper-proof evidence of tool calls for billing, auditing, and dispute resolution.

{
  "receipt_id": "rcpt_a1b2c3d4e5f67890",
  "tool_id": "string",
  "agent_id": "string",
  "provider_id": "string",
  "timestamp": "ISO 8601 datetime",
  "duration_ms": 234,
  "cost_microcents": 50000,
  "status": "success",
  "input_hash": "sha256:...",
  "output_hash": "sha256:...",
  "signature": "hex-encoded HMAC-SHA256",
  "verify_url": "https://provider.example/api/receipts/rcpt_..."
}

Receipt ID Format

Signature

canonical = receipt_id | tool_id | agent_id | provider_id | timestamp | cost_microcents | status

Fields are joined with the pipe character (|). The HMAC key is a server-side secret that MUST NOT be exposed to clients.

Verification

{
  "receipt": { "...full receipt fields..." },
  "verification": {
    "valid": true,
    "algorithm": "HMAC-SHA256",
    "verified_at": "ISO 8601 datetime"
  }
}

Privacy

3. Pricing Declaration Schema

Providers declare pricing per tool. This enables agents to make cost-aware decisions before invocation.

{
  "tool_id": "string",
  "tool_name": "string",
  "provider_id": "string",
  "pricing_model": "per_call | per_token | free",
  "price_per_call_microcents": 50000,
  "price_per_input_token_microcents": 10,
  "price_per_output_token_microcents": 30,
  "free_tier": {
    "calls_per_month": 100,
    "tokens_per_month": 10000
  },
  "currency": "USD"
}

Pricing Models

• per_call — flat rate per invocation
• per_token — rate per input/output token
• free — no charge (community/open-source tools)

Free Tiers

4. Verification Levels

Provider verification establishes trust in tool listings. Four levels, from no verification to full code ownership proof:

Email Verification

Domain Verification

_mcp-billing-verify.example.com TXT "mcp-billing-verify={provider_id_prefix}-{challenge_token}"

Code Verification

5. Dispute Schema

Disputes allow agents or providers to contest charges associated with a receipt.

{
  "dispute_id": "disp_a1b2c3d4e5f67890",
  "receipt_id": "rcpt_...",
  "filed_by": "string (agent_id or provider_id)",
  "filed_by_type": "agent | provider",
  "reason": "tool_error | overcharge | timeout | quality | other",
  "description": "Human-readable description",
  "evidence": {},
  "status": "filed",
  "created_at": "ISO 8601 datetime"
}

Dispute ID Format

Reasons

• tool_error — Tool returned an error but agent was charged
• overcharge — Charge exceeds declared pricing
• timeout — Tool timed out but agent was charged
• quality — Output quality does not match tool description
• other — Catch-all with required description

Status Flow

filed → under_review → resolved_refund | resolved_denied | resolved_credit

• filed — Dispute created
• under_review — Platform is investigating
• resolved_refund — Full refund issued to agent
• resolved_denied — Dispute rejected, charge stands
• resolved_credit — Partial credit or alternative resolution

6. Trust Score Schema

A composite score combining verification, reliability, and dispute history. Enables agents to make trust-aware tool selection.

{
  "provider_id": "string",
  "trust_score": 87,
  "badge": "verified",
  "components": {
    "verification": 25,
    "uptime": 24,
    "latency": 20,
    "disputes": 18
  }
}

Component Weights (100 points total)

Badges

7. Discovery

Billing-capable MCP servers SHOULD advertise their capabilities in /.well-known/agents.json:

{
  "billing": {
    "type": "mcp-billing-v1",
    "spec": "https://noui.bot/specs/mcp-billing-v1",
    "pricing_endpoint": "/api/pricing",
    "metering_endpoint": "/api/meter",
    "receipts_endpoint": "/api/receipts"
  },
  "trust": {
    "verification_endpoint": "/api/providers/verify",
    "trust_endpoint": "/api/providers/{id}/trust",
    "sla_endpoint": "/api/providers/{id}/sla",
    "disputes_endpoint": "/api/disputes"
  }
}

8. Conformance

An implementation is MCP Billing v1 conformant if it:

Partial conformance is acceptable. Implementations SHOULD document which sections they support.

Appendix A: Why an Open Spec?

The MCP ecosystem needs billing. Multiple providers are building it independently with incompatible schemas. This fragmentation hurts everyone:

• Agents must learn different billing APIs per provider
• Providers can't switch billing platforms without rewriting integrations
• Platforms compete on implementation details instead of value

Appendix B: Reference Implementation

The Agent Bazaar at noui.bot is the reference implementation of this spec.

• API: https://noui.bot/api/v1
• SDK: npm install @noui/bazaar-sdk
• OpenAPI: https://noui.bot/api/openapi.json
• GitHub: https://github.com/TombStoneDash/noui-bot