Skip to content
mcp-pay View on GitHub
advanced 30 minutes

Wire up a payment rail

mcp-pay is rail-agnostic. This guide covers adding a rail — starting with x402, which the reference server implements first — by declaring it in the manifest and configuring a facilitator.

  1. 1

    Declare the rail in accepts

    Add an entry to the manifest accepts array for the rail, including its network and settlement details.

    { "rail": "x402", "network": "eip155:8453", "asset": "USDC", "pay_to": "0x1234..." }
  2. 2

    Point the server at a facilitator

    Configure mcp-pay-server with the facilitator endpoint that can verify proofs for this rail.

  3. 3

    Declare a payment SLA (optional)

    Add per-rail settlement time and a refund policy so agents can choose a rail on latency.

    "payment_sla": { "settlement_time_seconds": { "x402": 2 }, "refund_policy": "full_refund_on_failure" }
  4. 4

    Exercise the flow

    Use mcp-pay-cli to run the full 402 handshake against the tool and confirm a valid proof is accepted.

Adding more rails later

  • ▸MPP, Lightning, and card are in the schema; the reference server implements x402 first and adds the others in later phases.
  • ▸A single manifest can list multiple rails, so agents pay on whichever one they carry.

More guides in the index, or read the architecture to see the full 402 handshake.