Monetizing a Research MCP Server with x402: Complete TypeScript Implementation

An MCP tool becomes commercially useful when an AI agent can discover it, understand its input and output contract, pay a known price, and receive a result through the same tool call. This article builds that path around one concrete tool: research_digest.

The tool accepts a research topic and returns a short structured digest. The price is $0.01 per call on a configured test network. The MCP server exposes the tool, an x402-protected HTTP resource performs the paid request, the agent wallet signs the payment after a policy check, and the resource server verifies payment before running the research function.

The important architectural choice is where payment happens. The MCP protocol remains the tool interface. x402 protects the HTTP resource behind that interface. This mirrors the current x402 MCP reference pattern: an MCP server or bridge calls a paid API, handles the 402 handshake, and returns the paid data to an MCP-compatible client.

The Reference Architecture: MCP on Top, x402 at the Resource Boundary

The complete path has five components:

The request direction is:

1. The MCP host asks the bridge to call research_digest.

2. The bridge sends an HTTP request to the paid research resource.

3. The resource returns HTTP 402 with payment requirements when no valid payment is present.

4. The bridge checks the amount, network, scheme, tool identity, and local spending policy.

5. The wallet creates and signs a payment payload.

6. The bridge retries the HTTP request with the payment signature.

7. The resource server verifies the payload through a facilitator or local implementation.

8. The resource executes the research function only after its payment gate passes.

9. The bridge converts the JSON result into an MCP tool result.

10. The MCP host returns the result to the agent or user.

This separation makes the system easier to operate. The same paid HTTP resource can serve an MCP bridge, a direct API client, or another programmatic consumer. The MCP layer remains responsible for tool discovery and result formatting; the resource layer remains responsible for payment and fulfillment.

Define the Paid Tool Before Writing Middleware

Start with a contract that an agent can evaluate before it spends.

Tool name: research_digest

Input:

Output:

{
  "topic": "Bitcoin-secured agent infrastructure",
  "summary": "...",
  "keyPoints": ["..."]

{
  "topic": "Bitcoin-secured agent infrastructure",
  "summary": "...",
  "keyPoints": ["..."]

{
  "topic": "Bitcoin-secured agent infrastructure",
  "summary": "...",
  "keyPoints": ["..."]

Price: $0.01 per successful call.

The price must be server-authoritative. The MCP description can state the expected price, but the x402 payment requirement returned by the resource is what the wallet policy should evaluate. The server should also specify the network, scheme, receiving address, expiration, and response MIME type.

For this example, the research function is deliberately deterministic and local. Replace it with a real search, indexing, or model pipeline only after adding upstream timeouts, output validation, rate limits, and a durable request record. Payment verification should not be confused with factual quality or successful upstream execution.

The Complete Request Trace

Before payment, the MCP host sends a normal tool call. A simplified MCP call looks like this:

The bridge maps that call to an HTTP request:

The first HTTP response is a payment challenge:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded payment requirements>

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded payment requirements>

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded payment requirements>

The requirements describe the accepted scheme, network, amount, and destination. The bridge does not sign automatically just because a 402 was returned. It checks the requirement against code-level policy first.

After signing, the bridge retries with a payment signature header. The resource server verifies the payload. When the verification result is valid, the resource server runs research_digest, serializes the result, and returns it. The bridge then places that JSON inside the MCP response content array.

The facilitator can verify and settle payment, but the resource server still decides whether to fulfill the request. That is why tool execution belongs after the payment gate, and why a production system should retain a payment reference and a tool request ID separately.

Project Setup and Environment

The following reference uses Node.js, TypeScript, Express, the MCP SDK, and the x402 TypeScript packages. The network and addresses below are placeholders for a test configuration. Use the current x402 documentation and the selected facilitator for exact network support before running it.

Install dependencies:

Suggested environment file:

The public x402 facilitator URL is suitable for the documented testnet quickstart path, not an assumption about production mainnet operations. Never commit a private key. In production, use a custody or signing design with spending policy, key rotation, audit logging, and restricted network access.

Code 1: The x402-Protected Research Resource

Create src/resource-server.ts. This process owns the paid HTTP resource and the research function. The x402 middleware returns the payment requirement when the request has no valid payment. When the middleware allows the request through, the route executes the tool and returns JSON.

import "dotenv/config";
import { randomUUID } from "node:crypto";
import express from "express";
import {
  HTTPFacilitatorClient,
  x402ResourceServer,
} from "@x402/core/server";
import {
  ExactEvmScheme,
} from "@x402/evm/exact/server";
import { paymentMiddleware } from "@x402/express";

const app = express();
app.use(express.json());

const payTo = process.env.RESOURCE_PAY_TO;
const network = process.env.NETWORK ?? "eip155:84532";
const facilitatorUrl =
  process.env.FACILITATOR_URL ?? "https://x402.org/facilitator";

if (!payTo) {
  throw new Error("RESOURCE_PAY_TO is required");
}

const facilitator = new HTTPFacilitatorClient({
  url: facilitatorUrl,
});

const resourceServer = new x402ResourceServer(facilitator)
  .register(network, new ExactEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /research/digest": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.01",
            network,
            payTo,
          },
        ]

import "dotenv/config";
import { randomUUID } from "node:crypto";
import express from "express";
import {
  HTTPFacilitatorClient,
  x402ResourceServer,
} from "@x402/core/server";
import {
  ExactEvmScheme,
} from "@x402/evm/exact/server";
import { paymentMiddleware } from "@x402/express";

const app = express();
app.use(express.json());

const payTo = process.env.RESOURCE_PAY_TO;
const network = process.env.NETWORK ?? "eip155:84532";
const facilitatorUrl =
  process.env.FACILITATOR_URL ?? "https://x402.org/facilitator";

if (!payTo) {
  throw new Error("RESOURCE_PAY_TO is required");
}

const facilitator = new HTTPFacilitatorClient({
  url: facilitatorUrl,
});

const resourceServer = new x402ResourceServer(facilitator)
  .register(network, new ExactEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /research/digest": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.01",
            network,
            payTo,
          },
        ]

import "dotenv/config";
import { randomUUID } from "node:crypto";
import express from "express";
import {
  HTTPFacilitatorClient,
  x402ResourceServer,
} from "@x402/core/server";
import {
  ExactEvmScheme,
} from "@x402/evm/exact/server";
import { paymentMiddleware } from "@x402/express";

const app = express();
app.use(express.json());

const payTo = process.env.RESOURCE_PAY_TO;
const network = process.env.NETWORK ?? "eip155:84532";
const facilitatorUrl =
  process.env.FACILITATOR_URL ?? "https://x402.org/facilitator";

if (!payTo) {
  throw new Error("RESOURCE_PAY_TO is required");
}

const facilitator = new HTTPFacilitatorClient({
  url: facilitatorUrl,
});

const resourceServer = new x402ResourceServer(facilitator)
  .register(network, new ExactEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /research/digest": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.01",
            network,
            payTo,
          },
        ]

The example uses the x402 Express middleware and exact EVM scheme documented in the seller quickstart. The route function is intentionally small. In a real tool, use a durable request ID and idempotency record before starting expensive work, and decide whether settlement should occur only after a successful response according to the selected middleware and payment mode.

Code 2: The MCP Client Bridge

Create src/mcp-bridge.ts. This process is the MCP server visible to Claude Desktop or another MCP host. It exposes research_digest, calls the paid HTTP resource, and uses an x402 client wrapper to handle the 402 challenge.

The exact hook names can vary across SDK versions, so pin and test the x402 packages together. The important security property is not the hook's spelling: the payment requirement must be checked in executable code before the wallet signs. A model instruction such as “never pay more than one cent” is not a spending control.

Why Payment Must Be Checked Before Tool Execution

The protected resource should not execute the research function on the first unpaid request. Its order is:

1. Parse the HTTP request and identify the resource.

2. Return the declared payment requirement if no valid payment is present.

3. Verify the payment payload against amount, asset, network, recipient, scheme, and expiry.

4. Record the payment or request identifier.

5. Execute the tool.

6. Validate the output.

7. Return the MCP-compatible result through the bridge.

The facilitator helps with verification and settlement, but it does not decide whether the research result is complete or useful. If the upstream search provider fails after payment, the resource needs a retry, credit, refund, or manual-review policy. That behavior belongs to the seller, not to the MCP client wrapper.

For a synchronous fixed-price tool, the service may return the result after the configured payment acceptance path succeeds. For a long-running research job, return a job ID and make result retrieval idempotent. Do not start a second paid job just because the MCP host lost the first response.

Production Hardening for a Paid MCP Tool

The two files above are a reference implementation, not a production custody system. Add these controls before exposing a real tool.

Stable idempotency

Generate a logical request ID before payment and carry it through the MCP arguments, HTTP request, payment identifier, worker job, and result record. The x402 Payment-Identifier extension can help deduplicate payment processing, but the tool execution queue needs its own durable protection too.

Spend policy

Check maximum amount, expected network, accepted scheme, tool name, recipient, per-agent budget, and daily or session limits before signing. Reject changed requirements rather than asking the agent to decide from a new prompt.

Authentication and abuse controls

Use MCP transport authentication or an application gateway where the service needs identity. Add rate limits, input limits, tenant isolation, request logging without private keys, and protection against tool arguments that cause excessive upstream cost.

Result integrity

Validate the output schema before returning it. Include a request ID, source count, generation timestamp, and result reference where appropriate. A payment receipt is not proof that the research result is accurate.

Timeouts and retries

Use bounded timeouts for facilitator calls, upstream research calls, and MCP result delivery. Retry reads cautiously. Do not blindly retry payment creation or an expensive non-idempotent tool execution after a timeout; reconcile the existing request first.

Refund and failure policy

Define what happens when payment is verified but the tool returns an error, an empty result, or a partial result. An automatic credit or refund may be appropriate for deterministic infrastructure failures. Subjective research quality may require review. A crypto payment is not automatically a card-style chargeback.

Discovery metadata

If the tool is made discoverable, keep discovery metadata aligned with the actual name, input schema, transport, description, and price. Discovery tells an agent that a tool exists; the live payment requirement remains authoritative for the amount and destination.

Where GOAT AgentKit Can Extend the Stack

GOAT Network is relevant when the MCP bridge or its merchant backend needs more than a single wallet signing call. AgentKit's documented payer-side plugin exposes payment creation, authorization submission, token transfer, status, and cancellation. Its merchant-side plugin exposes a broader portal surface for authentication, orders, balances, webhooks, API keys, and related operations.

That gives developers two practical extension points. On the buyer side, the MCP bridge can place the x402 client behind a wallet adapter and runtime policy. On the seller side, the research service can connect paid requests to merchant order status, settlement records, webhook processing, and operational reconciliation.

AgentKit Runtime also documents policy gates, idempotency stores, bounded retries and timeouts, output validation, metrics, and hooks. Those controls are useful around a paid MCP tool because payment and tool execution are both state-changing actions. The developer still owns the research service, its source quality, delivery contract, refund policy, and deployment configuration. GOAT is an infrastructure option for the surrounding agent and merchant stack, not a claim that every MCP tool automatically becomes production-safe.

Deployment Checklist

Before a real agent calls the tool, verify:

• the MCP schema and HTTP query schema accept the same inputs;

• the displayed tool price matches the server's payment requirement;

• the client rejects unexpected networks, assets, recipients, and amounts;

• the private key is outside source control and outside model-visible context;

• the test facilitator and network are appropriate for the environment;

• payment verification happens before tool execution;

• each logical call has a durable idempotency key;

• repeated MCP calls return the existing result instead of charging again;

• facilitator and upstream timeouts have bounded behavior;

• errors do not get serialized as successful paid results;

• settlement records can be reconciled with tool request records;

• refunds, credits, and failed delivery have explicit rules;

• webhook or status recovery exists if the merchant uses asynchronous payment state;

• logs contain IDs and statuses but never private keys or sensitive wallet material;

• the paid resource is tested separately from the MCP bridge.

FAQ

How does an MCP client pay for a tool call with x402?

The MCP bridge sends an HTTP request to the paid resource. If the resource returns HTTP 402 with payment requirements, the bridge checks the requirement, signs a payment payload with its configured wallet, retries with the payment signature, and converts the successful response into an MCP tool result.

Should payment happen inside the MCP protocol?

The reference architecture keeps payment at the HTTP resource boundary while MCP remains the tool interface. This lets the same paid resource serve MCP and non-MCP clients and keeps payment verification in the resource server rather than inside model instructions.

Can every MCP tool have the same price?

They can, but separate tool contracts usually need separate server-authoritative prices. The client should verify the expected tool, network, scheme, recipient, and amount before signing. A changed or unexpected requirement should be rejected.

What happens if the tool fails after payment?

The service should preserve the request and payment identifiers, distinguish payment state from execution state, and apply a documented retry, credit, refund, or review policy. It should not silently ask the agent to pay again.

Is the code sample production-ready as written?

No. It is a complete reference flow for a test configuration. Production deployment still requires secure custody, authentication, durable idempotency, observability, rate limits, output validation, reconciliation, and a tested refund or failure policy.

How can GOAT AgentKit support a paid MCP stack?

Its documented capabilities include payer and merchant payment actions, payment status and cancellation, orders, balances, webhooks, API keys, policy gates, idempotency, retries, timeouts, output validation, metrics, and hooks. Developers can use those surfaces around the MCP bridge or seller backend while keeping tool-specific execution and delivery logic in their own service.

A Paid MCP Tool Is a Product Boundary

The 402 response is only one step in monetizing an MCP server. A complete implementation defines the tool contract, names the price, checks wallet policy, verifies payment, runs the tool, validates the result, and returns an MCP-compatible response with enough state to recover from a timeout.

For research_digest, the result is not “the agent paid.” The result is a bounded, retrievable research output delivered exactly once for the intended tool call. That is the standard a production MCP server should meet before it treats x402 as revenue infrastructure.