x402-mcp
MCP server for the x402 protocol. Lets AI agents (Claude, Cursor, etc.) discover and call payment-gated HTTP APIs automatically.
Repository: merkleworks/x402-mcp
MCP Server
This repository provides a Model Context Protocol (MCP) server that enables AI agents to call payment-gated HTTP APIs using the x402 protocol.
Tools exposed:
x402_http_request— Execute HTTP requests to APIs requiring payment via the x402 protocol. If the server returns 402, the tool parses the challenge, constructs the payment, retries with proof, and returns the final response.
Example agent flow:```
agent → tool call → x402_http_request → 402 challenge → payment → retry → response
**Automatic discovery:** The server is discoverable by MCP-aware frameworks without manual registry submission:
- **Repository descriptor:** mcp.json at the repo root (name, description, `install: npx x402-mcp`, tools).
- **npm:** Run with `npx x402-mcp`; package keywords include `mcp`, `model-context-protocol`, `ai-tools`, `x402`.
- **Well-known:** .well-known/mcp.json can be hosted at `https://demo.x402.merkleworks.io/.well-known/mcp.json` for domain-based discovery.
---
## Overview of x402
x402 is a protocol that gates HTTP APIs behind micropayments using **HTTP 402 Payment Required**:
1. **Request** — Client calls the API.
2. **402 challenge** — Server responds with `402 Payment Required` and an `X402-Challenge` header (nonce UTXO, price, payee, expiry).
3. **Payment** — Client builds a BSV transaction, delegates fees (optional), and broadcasts.
4. **Retry** — Client retries the request with an `X402-Proof` header.
5. **Response** — Server verifies the proof and returns the API response.
This flow lets APIs charge per request in satoshis without pre-registration or cards.
---
## What this MCP server does
This server exposes **Model Context Protocol (MCP)** tools so AI agents can:
- **`paid_http_request`** — Send an HTTP request; if the server returns 402, run the full x402 flow (parse challenge → pay → retry with proof) and return the final response. Primary tool for calling payment-gated APIs.
- **`discover_x402_api`** — List payable endpoints (from `/.well-known/x402` or by probing for 402).
- **`pay_x402_endpoint`** — Call a known x402 endpoint with full control (method, body, headers, delegator).
- **`parse_x402_challenge`** — Decode an `X402-Challenge` header.
- **`verify_x402_proof`** — Check an `X402-Proof` against a challenge and request.
Agents use **`paid_http_request`** for a single “call this URL; pay if 402” step.
---
## Installation
**Run with a single command (recommended):**```bash
npx x402-mcp
Or install globally:```bash
npm install -g x402-mcp
x402-mcp
From source:```bash
git clone https://github.com/merkleworks/x402-mcp.git
cd x402-mcp
npm install
npm run build
npm start
Usage example
Agent → tool call → x402_http_request → x402 flow (if 402) → API response
- The agent calls the tool with
url,method, and optionalheadersandbody. - The server sends the HTTP request.
- If the response is 402, the server parses the challenge, builds the payment, delegates/broadcasts, then retries with the proof.
- The tool returns the final response (status, body, and payment txid if paid).
Example tool call
Tool:
x402_http_request
Input schema:
| Field | Type | Required | Description |
|---|---|---|---|
url |
string | yes | Full URL of the API endpoint |
method |
string | no | HTTP method (default: GET) |
headers |
object | no | Optional HTTP headers (key-value strings) |
body |
string or object | no | Optional request body (string or JSON object) |
Example (GET):```json
{
"tool": "x402_http_request",
"input": {
"url": "https://demo.x402.merkleworks.io/v1/expensive",
"method": "GET"
}
}
**Example (POST with JSON body):**```json
{
"tool": "x402_http_request",
"input": {
"url": "https://api.example.com/v1/query",
"method": "POST",
"headers": { "Content-Type": "application/json" },
"body": { "query": "example" }
}
}
More examples: examples/, including example_agent_call.json.
Connecting from AI clients
Cursor
Add to .cursor/mcp.json:```json
{
"mcpServers": {
"x402": {
"command": "npx",
"args": ["@merkleworks/x402-mcp"]
}
}
}
Or with a local build:```json
{
"mcpServers": {
"x402": {
"command": "node",
"args": ["/path/to/x402-mcp/dist/server.js"]
}
}
}
Claude Desktop / Claude Code
Add to your MCP config (e.g. claude_desktop_config.json):```json
{
"mcpServers": {
"x402": {
"command": "npx",
"args": ["@merkleworks/x402-mcp"]
}
}
}
### Generic MCP client (Node.js)```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "npx",
args: ["@merkleworks/x402-mcp"],
});
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const result = await client.callTool("paid_http_request", {
url: "https://demo.x402.merkleworks.io/v1/expensive",
method: "GET",
});
console.log(result);
Tools reference
| Tool | Description |
|---|---|
paid_http_request |
Execute HTTP request; if 402, run x402 flow and return final response |
discover_x402_api |
Discover payable endpoints (/.well-known/x402 or probe) |
pay_x402_endpoint |
Call x402 endpoint with full control (delegator, broadcast URL, etc.) |
parse_x402_challenge |
Decode X402-Challenge header |
verify_x402_proof |
Verify X402-Proof against challenge and request |
Protocol summary
- Client requests a protected endpoint.
- Server responds 402 with
X402-Challenge. - Client builds a BSV tx, optionally uses a delegator for fees, then broadcasts.
- Client retries with
X402-Proof. - Server verifies and returns the response.
This MCP server implements that flow so agents can pay for API calls without manual steps.
Configuration
pay_x402_endpoint(and thuspaid_http_requestwhen it pays) use the same origin as the request URL for the delegator by default. Override withdelegator_url/broadcast_urlwhen usingpay_x402_endpointdirectly.- Discovery manifest format: protocol spec and
/.well-known/x402.
Examples
- example_agent_call.json — Example
paid_http_requestcall for agents. - discover-and-pay — Discover endpoints then pay and call the first. Run:
npx tsx examples/discover-and-pay.ts https://your-x402-api.example.com
MCP registry (mcp.json)
The repo includes mcp.json for MCP registries (e.g. mcp.so): name, description, repository, install command, and tool list.
License
Apache-2.0
