Server half of the x402 MCP transport: gates a tool handler behind payment.

call/3 inspects an MCP tool-call request for a payment in _meta["x402/payment"] and drives the full verify → execute → settle flow against an X402.Facilitator:

1. No payment → the payment-required tool result (isError: true with the PaymentRequired object in structuredContent and content[0].text).
2. Invalid payment (wrong version, accepted not matching the advertised requirements, extension echo mismatch, failed verification) → the same payment-required result with the rejection reason.
3. Valid payment → the wrapped handler runs; on success the payment is settled and the receipt is attached to result _meta["x402/payment-response"]. When settlement fails after execution, only the payment error is returned — never the tool's content.

The module is MCP-library agnostic: requests and results are plain maps in the shapes MCP libraries already use, so the wrapper drops into any tool dispatch function. See the MCP guide for integration snippets.

Example

config =
  X402.MCP.Server.init(
    tool: "premium_search",
    accepts: [
      %{
        price: "10000",
        network: "eip155:84532",
        asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        pay_to: "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
        extra: %{"name" => "USDC", "version" => "2"}
      }
    ],
    facilitator: MyApp.Facilitator
  )

X402.MCP.Server.call(request, config, fn _request ->
  %{"content" => [%{"type" => "text", "text" => "results..."}]}
end)

Replay protection

Pass payment_identifier_cache: (an X402.Extensions.PaymentIdentifier.ETSCache server, the same option X402.Plug.PaymentGate takes) to atomically claim each payment proof before settlement, rejecting concurrent or repeated submissions of the same signed payment. The claim is released when the handler fails or settlement fails, so the client may retry with the same payment.

Payment identifier

Advertise the payment-identifier extension with extensions: %{"payment-identifier" => X402.Extensions.PaymentIdentifier.extension(required: true)}. The id echoed under extensions["payment-identifier"]["info"]["id"] must be 16–128 characters of [A-Za-z0-9_-] (otherwise the payment-required result carries invalid_payload); with required: true a missing id yields payment_identifier_required. When a cache is configured, the id is bound to a fingerprint of the matched requirements and the tool name (X402.Extensions.PaymentIdentifier.fingerprint/2) under a "pid:" key: reusing it for a different request yields payment_identifier_conflict, the same request proceeds normally. The pre-0.7.0 "paymentIdentifier" format is still accepted but deprecated (removed in 1.0.0) and emits [:x402, :payment_identifier, :legacy].

Builder code

A payment echoing the builder-code extension — whether or not extensions advertises it with X402.Extensions.BuilderCode.extension/2 — is checked with X402.Extensions.BuilderCode.validate_echo/2: malformed codes or more than ten service codes yield invalid_payload, and an app code that differs from the advertised one is an extension echo mismatch. The codes travel to the facilitator inside the payload.

Lifecycle hooks

The :hooks module may define the optional resource-server callbacks of X402.Hooks. X402.Hooks.on_protected_request/2 runs on every call with an X402.Hooks.RequestContext (transport: :mcp, the request, the tool name, and the advertised requirements and extensions) before the payment is inspected: it may continue with replaced requirements or extensions, halt with {:halt, {status, body}} (answered as an isError result carrying body in structuredContent), or halt with {:halt, :skip_payment} to run the handler unpaid (emitting [:x402, :mcp, :pass_through] with reason: :hook_skipped). X402.Hooks.on_verified_payment_canceled/2 runs when a verified payment is not settled: the handler returned an error result (reason: :handler_failed), the handler raised or threw (reason: :handler_raised, with :error), or settlement failed (reason: :settlement_failed, with :error).