If your MCP server doesn't hold a funded USDC wallet, paid tool calls will fail. Follow these seven steps to take an MCP bridge from an HTTP 402 PAYMENT-REQUIRED response to a settled, paid reply: wire an x402 client into the MCP tool, enforce local policy checks before signing, and fund a wallet with USDC on the networks your paid upstreams accept. The protocol uses PAYMENT-REQUIRED and PAYMENT-SIGNATURE headers so the bridge can create, sign, and retry requests with an on-chain stablecoin transfer, a flow described in the x402 documentation and in the Coinbase x402 guide. Start by preparing runtime and credentials, then test the sign-and-retry handshake against a known resource server.

If your MCP server doesn't hold a funded USDC wallet, paid tool calls will fail.

1. Prepare runtime and credentials

First, match the environment to the example implementations. Official guides list Node.js v20 or newer and Pnpm v10 as prerequisites for the sample MCP server projects. Have a private key available to the MCP process and fund the corresponding account with USDC on whatever networks your upstream paid APIs accept. The sample projects demonstrate support for Ethereum-family chains and Solana, so pick the chain or chains where you can reliably hold USDC.

Practically, that means three concrete actions. First, pick the wallet private key and back it with USDC on the networks you intend to use. Second, ensure your runtime can construct a signer from that private key; example code uses Viem for EVM account management. Third, install and pin the example packages you will use, notably the x402 core client plus the EVM and Solana scheme modules used for signing.

Worked example: an example repo converts a raw private key into a viem account, builds a signer, and registers that signer with an ExactEvmScheme implementation so the core x402 client can delegate EVM signing correctly.

2. Wire an x402-capable HTTP client into the tool

Wire the HTTP client so it detects HTTP 402 responses and runs the payment handshake automatically or manually. The simplest pattern from the examples is an axios wrapper that intercepts responses and performs sign-and-retry logic in blocking code paths. Other projects provide an x402 fetch helper that does the same. But the v2 core client examples show a manual pattern where you explicitly parse the 402, call helper methods, and reissue the request with the returned signature header.

In the manual pattern follow three steps. First, when the upstream returns the 402, parse the PAYMENT-REQUIRED header and the JSON body that describes price, accepted chain, and recipient address. Second, call the x402 client's helpers such as GetPaymentRequiredResponse and CreatePaymentPayload to build and sign the payment payload. Third, reissue the original HTTP request including the encoded PAYMENT-SIGNATURE header or whatever retry header the resource expects.

Worked example: the x402 core v2 client surfaces helpers named EncodePaymentSignatureHeader and CreatePaymentPayload. After you call them you reissue the HTTP GET or POST with the signature header and verify whether the upstream accepts the paid attempt.

3. Validate payment requirements against policy before signing

Every production MCP server must stop and ask permission before spending on behalf of an agent. Example test bridges often auto-approve payments, but the documentation insists on a local policy hook to validate each payment request. That hook should run before calling CreatePaymentPayload or otherwise signing.

At minimum check these items: 1. The maximum amount and currency, 2. The expected network and signing scheme, 3. The resource server or facilitator identity, 4. The named tool and requested operation, and 5. Per-user, per-agent, or per-session spending limits. Put in place these checks in the onPaymentRequested client hook or its equivalent so you can refuse unexpected or overly expensive calls.

Worked example: if an upstream returns a payment requirement denominated in USDC on an EVM chain, confirm the amount is within your per-agent daily cap and that the recipient address matches a known facilitator list before you create and sign the payload.

Mastheads

4. Handle multi-network, multi-scheme signing

The x402 client selects a signing scheme from the Network field in the payment requirements. EVM-family networks map to an EVM scheme while Solana-style networks map to an SVM scheme, according to the protocol documentation and the Coinbase x402 guide. You therefore must register the correct schemes and provide corresponding signers.

Example projects register mappings such as Eip155:* to an ExactEvmScheme and attach an EVM signer created from a private key. Solana schemes are registered separately. Because published examples differ on the exact networks listed, decide early which chains you will support and fund the wallet on those chains. The x402 documentation and some examples name Base Sepolia and Base Mainnet plus Solana Devnet/Mainnet. The Coinbase guide enumerates a broader set of EVM networks including Polygon, Arbitrum, and an entry referred to as World Mainnet.

Worked example: register an ExactEvmScheme for eip155:1 and eip155:11155111, register an SVM scheme for solana:devnet and solana:mainnet, then provide a viem-backed signer for the EVM schemes and the appropriate signer for Solana.

Do you let a wrapper automatically handle payments, or do you put in place the flow manually?

The x402 ecosystem offers both. Official examples mention an axios wrapper and an x402 fetch helper for automatic handling, while the v2 core client API often requires manual handling because HTTP client interfaces changed between versions.

Match the approach to the package version you install. If you use a wrapper, test it thoroughly so you understand how it handles retries, error propagation, and blocking behaviour. If you follow the manual route, write robust retry logic and error handling around the helper calls: parse the payment requirements, call the x402 client to create the payload, attach the encoded payment signature header, and reissue the request yourself.

Worked example: when running the core v2 client, the repo examples show calling GetPaymentRequiredResponse followed by CreatePaymentPayload, then passing the encoded signature into a fresh axios request. That manual reissue path makes it explicit where policy checks and logging must occur.

Most documentation uses PAYMENT-REQUIRED as the 402 header and PAYMENT-SIGNATURE for the retry header. One community explainer used X-Payment for the retry header in a conceptual walkthrough. Treat header-name variance as an implementation detail: confirm what the actual resource server expects during integration testing and code to that surface.

Log every step. At minimum log 1. The moment you receive a 402, 2. The parsed payment requirements, 3. Creation of the payment payload, 4. The encoded signature header sent to the upstream, and 5. Whether the paid retry was accepted or rejected. When payment is rejected return or surface the raw upstream error so operators can diagnose failed on-chain verification or signature problems.

Measure settlement times too. Different chains confirm transfers at different latencies. Example projects and the GitHub engine that aggregates public pay-per-call endpoints document order-of-magnitude differences between EVM testnets, Solana Devnet, and other settlement networks. Those differences matter when you set timeouts and when you estimate per-call user experience.

Worked example: if you see that Solana Devnet settles in a few seconds while an EVM testnet takes tens of seconds, adjust HTTP timeouts and user-facing expectations accordingly and surface a clear message when a paid call is still awaiting on-chain confirmation.

Once your MCP server can handle 402 sign-and-retry flows locally, register it with the host agent configuration so tool calls route correctly. Example instructions show adding an MCP server entry to the host config and restarting the host so the server is discovered. For local testing, some example projects provide a development bypass secret that simulates payments without on-chain settlement. Don't use bypass modes in production.

Also build operational controls around funding and budgets. The GitHub example engine lists public pay-per-call endpoints and shows many per-call prices in the low fractions of a dollar, which makes funding and per-call budget controls relevant. Enforce per-user and per-agent spending limits, monitor total wallet balance, and provide clear alerts when USDC runs low.

Worked example: add an admin endpoint that reports the funded wallet balance on each registered chain, a per-agent spend counter, and a toggle to disable paid calls for a given tool if the operator wants to pause exposure.

Throughout this guide I will save you the trouble: wire an x402 client into your tool implementation, test the sign-and-retry flow end to end, and stop to validate every payment against local policy before signing. That single rule prevents surprise spending and keeps agent behaviour within operator intent.

Related Articles

Start the x402-compatible resource server or point the MCP server at the URL configured in RESOURCE_SERVER_URL, add the MCP server to your host agent configuration, ensure your wallet private key is available to the MCP server process and funded with USDC on the chosen networks, then restart the agent host and invoke the example tool to observe the 402 handshake and the paid response.

This article was created with AI assistance.