# How to Sell a Paid MCP Tool With x402 and Pyrimid

This guide uses the live CobroClaro MCP/x402 service as a reproducible example. The pattern works for any small MCP tool or HTTP API that can return a useful JSON result after payment.

## What You Need

- A public HTTPS endpoint.
- A Base wallet address for USDC settlement.
- A machine-readable MCP or API descriptor.
- An x402 resource server that returns HTTP 402 until payment is supplied.
- A Pyrimid catalog entry or product page that points agents to the paid endpoint.

Pyrimid reference: https://pyrimid.ai/quickstart

## Live Working Endpoint

CobroClaro exposes a paid MCP endpoint here:

```text
POST https://cobroclaro.netlify.app/mcp
```

Free discovery methods:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
```

```json
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
```

Paid tool call:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "cobroclaro_custom_reminder",
    "arguments": {
      "clientName": "Acme Ltd",
      "invoice": "INV-2026-045",
      "amount": "EUR 500",
      "dueDate": "2026-05-01",
      "language": "en"
    }
  }
}
```

Price: 0.002 USDC on Base.

## Expected HTTP 402 Response

An unpaid `tools/call` should return HTTP 402 with x402 payment requirements. The exact encoded payment header can vary by library version, but the response needs to expose these fields either in a payment header or JSON body:

```json
{
  "error": "payment_required",
  "protocol": "x402",
  "network": "eip155:8453",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "2000",
  "currency": "USDC",
  "payTo": "0xd81898Ae4a78Dc78E5aFde24fe99187DC9C8FeBD",
  "facilitatorUrl": "https://facilitator.openx402.ai",
  "resource": "https://cobroclaro.netlify.app/mcp"
}
```

For a lower-friction HTTP API, CobroClaro also exposes:

```text
GET https://cobroclaro.netlify.app/api/paid-subject-lines
```

That endpoint costs 0.001 USDC and returns a paid subject-line pack after settlement.

## Catalog Metadata

Publish metadata that lets agents understand the product before paying:

```json
{
  "id": "cobroclaro-reminder-mcp",
  "name": "CobroClaro paid invoice reminder MCP",
  "description": "Generate overdue-invoice reminder subject lines and friendly, firm, and final collection copy.",
  "category": "business-productivity",
  "endpoint_url": "https://cobroclaro.netlify.app/mcp",
  "method": "POST",
  "input_format": "jsonrpc",
  "output_format": "json",
  "price": "0.002",
  "currency": "USDC",
  "chain": "base",
  "network": "eip155:8453",
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0xd81898Ae4a78Dc78E5aFde24fe99187DC9C8FeBD",
  "facilitatorUrl": "https://facilitator.openx402.ai",
  "tags": ["mcp", "x402", "invoice", "payment-reminder", "base-usdc"]
}
```

CobroClaro also publishes a full x402 manifest:

```text
https://cobroclaro.netlify.app/.well-known/x402
```

And MCP metadata:

```text
https://cobroclaro.netlify.app/mcp.json
```

## Minimal Server Pattern

1. Keep `initialize` and `tools/list` free.
2. Gate only `tools/call` or paid HTTP routes.
3. Register an x402 exact EVM scheme for Base.
4. Use USDC on Base:

```text
chain: eip155:8453
asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
```

5. On unpaid requests, return 402 with payment requirements.
6. On paid requests, verify and settle through the facilitator.
7. Return the paid JSON result with settlement metadata.

## Reproduce the Flow

Discover tools:

```bash
curl -s https://cobroclaro.netlify.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Trigger the payment-required response:

```bash
curl -i https://cobroclaro.netlify.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cobroclaro_subject_lines","arguments":{}}}'
```

List the product for discovery:

```bash
curl -s https://cobroclaro.netlify.app/.well-known/x402
```

Submit to a marketplace or Pyrimid catalog with the metadata above. A buyer agent can then discover the product, receive the 402 response, pay 0.002 USDC on Base, retry with the x402 payment proof, and receive the MCP tool result.

## Why This Works

The buyer does not need an account, invoice, or subscription. The paid endpoint itself is the checkout. The server only fulfills after payment verification, so the same URL handles discovery, payment, and delivery.

Pyrimid can sit in front of this as a catalog and distribution layer: agents discover the product in Pyrimid, route to the x402 endpoint, and the vendor receives on-chain USDC when the paid call settles.