MCP server with x402

The Model Context Protocol (MCP) is the standardized way to expose tools to an LLM. Wrapping NERO 402 paid calls behind an MCP server lets an LLM agent use paid APIs through the same tool-calling interface it uses for everything else; the agent sees a tool, the tool internally pays for and forwards the request.

What you build

An MCP server that exposes one or more "paid call" tools. When the LLM invokes a tool:

1. The MCP server constructs the underlying x402 paid call using x402Fetch and aaNativeSigner.
2. The agent SCW (server-side, owned by the operator) pays the merchant.
3. The merchant's response is returned to the LLM as the tool's output.

The LLM never sees a private key, a UserOp, or a transaction hash. From the LLM's perspective, the tool is just query_nero_knowledge(question: string) -> string.

Setup

pnpm add @modelcontextprotocol/sdk @nerochain/x402-client @nerochain/x402-aa

A minimal MCP server with one paid tool:

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
import { ethers } from "ethers";
import { x402Fetch } from "@nerochain/x402-client";
import { aaNativeSigner } from "@nerochain/x402-aa";

const wallet = new ethers.Wallet(process.env.NERO_PRIVATE_KEY!);
const f = x402Fetch({
  signer: aaNativeSigner({
    signer: wallet,
    rpcUrl, bundlerUrl, paymasterUrl, paymasterApiKey,
    settlementContract,
  }),
});

const server = new Server({ name: "nero-x402-mcp", version: "1.0.0" });

server.tool({
  name: "query_nero_knowledge",
  description: "Ask a question about NERO Chain. Costs 0.002 DEMO-USDT per call.",
  inputSchema: { type: "object", properties: { question: { type: "string" } }, required: ["question"] },
  async handler({ question }) {
    const res = await f("https://x402.nerochain.io/api/nero-knowledge", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ question }),
    });
    const body = await res.json();
    return { content: [{ type: "text", text: body.answer }] };
  },
});

await server.connect(new StdioServerTransport());

Connecting to Claude Desktop

Claude Desktop reads MCP server configuration from ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nero-x402": {
      "command": "node",
      "args": ["/path/to/your/mcp-server/dist/index.js"],
      "env": {
        "NERO_PRIVATE_KEY": "0x...",
        "NERO_PAYMASTER_API_KEY": "..."
      }
    }
  }
}

After restart, Claude can call query_nero_knowledge as a tool. Each invocation is one paid call against the live NERO 402 stack.

Cost controls

A long-running agent should not have unbounded spending power. Practical safeguards:

• Cap funding. Only fund the SCW with the budget you're willing to lose to LLM mistakes.
• Per-tool authorization. Wrap the tool handler with a check that the LLM's request is sensible before paying.
• Logging. Record every settled call's transactionHash, the LLM's prompt, and the eventual response. Useful for debugging the LLM's spending patterns.

The session-key pattern (see Session keys) gives chain-enforced spending caps and is the right answer for a serious deployment.