How to make an MCP server payable with x402

Server responsibilities

The server defines requirements for the protected resource, verifies a signed payload, performs the work only after valid payment and returns the resource with settlement evidence. A facilitator can handle verification and settlement, but the resource server remains responsible for enforcing the route correctly.

MCP-specific discovery

For paid MCP tools, the discovery extension should name the tool, describe its purpose, declare transport, include a usable input schema and provide a safe example. This allows directories and agents to understand the capability before paying. Invalid custom fields can prevent Bazaar discovery.

• Keep read-only and mutating tools clearly distinguished.
• Provide realistic example arguments that do not touch private data.
• Document whether a failed tool execution is charged or refunded.

Test the buyer path

Run the official client example or equivalent x402-aware bridge with a limited test wallet. Confirm the initial 402, selected scheme, signed retry, returned MCP content and settlement. Then repeat from the exact client instructions shown in your documentation; a server is not easy to adopt if only its author can connect it.

Choose the architecture before choosing packages

There are two common shapes. In the first, a local MCP bridge exposes tools to an MCP client and pays a separate x402 HTTP API on the user's behalf. In the second, the provider protects MCP tool calls themselves with an x402 payment wrapper. Both can be described as x402 plus MCP, but the signer, trust boundary and discovery metadata live in different places.

Use a bridge when an existing paid API needs to become available to ordinary MCP clients. Protect MCP tools directly when you own the tool server and want each invocation to carry payment requirements. Draw the request path on paper; if it is unclear which process holds the wallet and which process receives funds, implementation should not begin.

Define the commercial contract at the tool boundary

Decide what one payment buys before adding middleware. A tool that returns one weather report is easy to price per call. A research tool that launches a long-running job needs clearer rules: whether polling is free, when work begins, how maximum usage is expressed and what happens if the upstream service fails. The payment unit should match something the buyer can understand before signing.

Classify each tool as read-only, idempotent or mutating. For mutating tools, payment is not user consent. Require appropriate authentication and confirmation, and design duplicate protection so a retried signed request does not repeat an irreversible action.

Build the unpaid and paid paths separately

The unpaid path should return HTTP 402 with current, machine-readable requirements and enough discovery information for a buyer to understand the resource. It must not perform the paid work first. The paid path validates the signature, verifies and settles through the configured mechanism or facilitator, then invokes the tool and returns normal MCP content.

Keep tool errors distinct from payment errors. An unsupported network, failed settlement, invalid argument and upstream timeout need different machine-readable responses. This lets a buyer fix a request without repeatedly authorizing money and gives operators a useful failure rate for each layer.

• Return requirements before expensive or mutating work begins.
• Bind payment to the exact resource and intended amount.
• Invoke the tool only after the payment path succeeds.
• Return a documented MCP result or a specific tool error.

Write discovery metadata for a model that has never seen your product

A tool name such as get_data is not enough. Name the object and action, state the important limit and describe every required input. Add constraints such as formats, maximum lengths or allowed values. Provide one safe public example that validates against the schema and an output example that reflects the real MCP content.

Do not fill the description with positioning language. The agent needs to know whether get_weather returns current conditions, a forecast or historical observations, for which locations and at what granularity. Specific metadata improves discovery and reduces paid calls made with invalid or disappointed expectations.

Test on a non-production network from a clean buyer setup

Run the server with testnet requirements, then start a buyer using only the instructions you plan to publish. Confirm tool discovery, the initial 402, requirement selection, signer behavior, retry, settlement and final MCP content. Also test an unsupported network, insufficient funds, invalid input, provider timeout and duplicate retry.

A clean setup matters because the author's machine may contain linked packages, cached configuration or wallet state missing from the documentation. Record the supported runtime and package versions. Move to mainnet only after the test wallet can complete the full path without manual code changes.

Production readiness is more than a successful demo

Use a stable public endpoint, TLS, request correlation, rate limits and logs that exclude private keys and reusable payment signatures. Monitor unpaid challenges, verification failures, settlements, tool outcomes and latency as separate metrics. A spike in 402 responses may be healthy demand; a spike in signed retries followed by tool errors is a product incident.

Publish price, network, supported transport, charging semantics and a minimal buyer example. Re-run that example after upgrading MCP, x402 packages or the facilitator. If a tool is retired, remove its discovery metadata and return a clear status instead of leaving agents to pay for a dead capability.

Related directory entries

Sources and methodology

TOLL·402 distinguishes public claims, registry discovery, unpaid quote checks and settled paid-call verification. Sources below support the visible claims; presence in a registry is not treated as verification.

1. Official MCP with x402 guide — Current end-to-end MCP bridge example.
2. x402 seller quickstart — Current server wrapper and accepted requirements.
3. x402 Bazaar documentation — Discovery extension behavior.