使用说明
x402 mcp
TypeScript MCP（模型上下文协议）服务器，集成了用于x402支付协议的Express.js。
概述
这是一个 混合MCP服务器 它结合了：
- MCP服务器：提供通过模型上下文协议与x402支付协议交互的工具
- 快速HTTP服务器：使用x402支付中间件创建受支付保护的HTTP端点
这使得AI助手和MCP客户端既可以管理x402支付，又可以动态创建受加密货币支付保护的HTTP端点。使用TypeScript、官方MCP SDK和x402 express中间件构建。
特性
🔧 MCP支付管理工具
- x402_创建_付款_请求：创建具有指定价格和详细信息的新付款请求
- x402_支票_付款_状态：检查现有付款请求的状态
- x402_get_config：获取当前x402配置（支付地址、网络、服务商URL）
- x402_list_网络：列出x402支付的可用网络
🌐 用于快速端点管理的MCP工具
- x402_创建_保护_端点：动态创建受x402支付中间件保护的HTTP端点
- x402_list_受保护_端点：列出Express服务器上的所有受保护端点
- x402_get-express_server_status：获取Express服务器状态（运行状态、端口、端点计数）
- x402_更新_点_价格：更新现有受保护端点的价格
⚙️ 配置
- 付款地址:
0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7 - 网络：基础Sepolia（测试网）-主网更改为“基础”
- 支付令牌：USDC（稳定币）
- 主持人URL:
https://x402.org/facilitator（测试网） - 快速港口:
4021
安装
npm install
发展
在热重载的开发模式下运行服务器：
npm run dev
构建
将TypeScript编译为JavaScript：
npm run build
生产
运行已编译的服务器：
npm start
建筑
这是一个 混合服务器 它同时运行两台服务器：
┌─────────────────────────────────────────────────────────────┐
│ x402-mcp Process │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐│
│ │ MCP Server (stdio) │ │ Express HTTP Server ││
│ │ │ │ (Port 4021) ││
│ │ • Tool Management │ │ ││
│ │ • Payment Requests │ │ • Payment Middleware ││
│ │ • Endpoint Management │ │ • Protected Routes ││
│ │ • Configuration │ │ • Health Check ││
│ └──────────────────────────┘ └──────────────────────────┘│
│ │
│ Both use X402_CONFIG shared state │
└─────────────────────────────────────────────────────────────┘
│
▼
x402 Facilitator
(Payment Verification)
关键组件
- MCP服务器：通过stdio进行通信，为AI助手提供工具
- 快递服务器：带x402支付中间件的HTTP服务器
- Express服务器管理器：管理Express生命周期和受保护的端点
- X402处理器：处理手动创建和跟踪付款请求
- x402快递中间件：拦截HTTP请求，强制付款
项目结构
x402-mcp/
├── src/
│ └── index.ts # Main implementation (MCP + Express hybrid)
├── dist/ # Compiled JavaScript output
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .gitignore # Git ignore rules
└── README.md # This file
与MCP客户端一起使用
配置
将此服务器添加到您的MCP客户端配置中（例如，Claude Desktop）：
{
"mcpServers": {
"x402-mcp": {
"command": "node",
"args": ["/path/to/x402-mcp/dist/index.js"]
}
}
}
发展：
{
"mcpServers": {
"x402-mcp": {
"command": "npm",
"args": ["run", "dev"],
"cwd": "/path/to/x402-mcp"
}
}
}
工具调用示例
创建受保护的HTTP端点
{
"name": "x402_create_protected_endpoint",
"arguments": {
"path": "/weather",
"method": "GET",
"price": "$0.001",
"description": "Get current weather data for any location",
"responseData": {
"weather": "sunny",
"temperature": 72,
"humidity": 45
},
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name"
}
}
},
"outputSchema": {
"type": "object",
"properties": {
"weather": { "type": "string" },
"temperature": { "type": "number" },
"humidity": { "type": "number" }
}
}
}
}
答复：
{
"success": true,
"message": "Protected endpoint created successfully",
"data": {
"endpoint": "GET /weather",
"url": "http://localhost:4021/weather",
"price": "$0.001",
"description": "Get current weather data for any location",
"network": "base-sepolia",
"payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7"
}
}
现在，当有人访问时 http://localhost:4021/weather 如果不付款，他们将收到402 payment Required响应和付款说明！
创建付款请求
{
"name": "x402_create_payment_request",
"arguments": {
"price": "$0.50",
"description": "Access to premium API endpoint",
"resource": "/api/premium/data",
"maxTimeoutSeconds": 120
}
}
答复：
{
"success": true,
"message": "Payment request created successfully",
"data": {
"paymentId": "x402_1234567890_abc123",
"paymentUrl": "https://x402.org/facilitator/pay?id=...",
"price": "$0.50",
"network": "base-sepolia",
"payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7",
"description": "Access to premium API endpoint",
"expiresAt": "2024-01-01T12:02:00.000Z"
}
}
列出所有受保护的端点
{
"name": "x402_list_protected_endpoints",
"arguments": {}
}
答复：
{
"success": true,
"message": "Found 1 protected endpoint(s)",
"data": [
{
"method": "GET",
"path": "/weather",
"price": "$0.001",
"description": "Get current weather data for any location",
"url": "http://localhost:4021/weather"
}
]
}
获取Express服务器状态
{
"name": "x402_get_express_server_status",
"arguments": {}
}
答复：
{
"success": true,
"message": "Express server is running",
"data": {
"isRunning": true,
"port": 4021,
"network": "base-sepolia",
"payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7",
"facilitatorUrl": "https://x402.org/facilitator",
"endpointCount": 1,
"endpoints": [...]
}
}
检查付款状态
{
"name": "x402_check_payment_status",
"arguments": {
"paymentId": "x402_1234567890_abc123"
}
}
答复：
{
"success": true,
"data": {
"paymentId": "x402_1234567890_abc123",
"status": "pending",
"paid": false,
"price": "$0.50",
"network": "base-sepolia",
"createdAt": "2024-01-01T12:00:00.000Z",
"expiresAt": "2024-01-01T12:02:00.000Z"
}
}
获取配置
{
"name": "x402_get_config",
"arguments": {}
}
答复：
{
"success": true,
"message": "Current x402 configuration",
"data": {
"payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7",
"network": "base-sepolia",
"facilitatorUrl": "https://x402.org/facilitator"
}
}
列出网络
{
"name": "x402_list_networks",
"arguments": {}
}
答复：
{
"success": true,
"message": "Available networks for x402 payments",
"data": [
{
"name": "base",
"displayName": "Base Mainnet",
"chainId": 8453,
"currency": "ETH",
"stablecoin": "USDC",
"isMainnet": true
},
{
"name": "base-sepolia",
"displayName": "Base Sepolia Testnet",
"chainId": 84532,
"currency": "ETH",
"stablecoin": "USDC",
"isMainnet": false
},
{
"name": "avalanche",
"displayName": "Avalanche C-Chain",
"chainId": 43114,
"currency": "AVAX",
"stablecoin": "USDC",
"isMainnet": true
},
{
"name": "solana",
"displayName": "Solana Mainnet",
"chainId": null,
"currency": "SOL",
"stablecoin": "USDC",
"isMainnet": true
}
]
}
错误处理
服务器包括全面的错误处理：
- 未找到付款：检查不存在的付款状态时返回错误
- 付款状态无效：防止在错误状态下进行付款操作
- 过期付款：自动将待付款标记为已过期
- 无效参数：使用带有详细错误消息的Zod模式进行验证
技术栈
- TypeScript：类型安全开发
- Node.js：运行时环境
- MCP-SDK：官方模型上下文协议SDK
- x402快递：x402支付协议集成
- 萨德：运行时类型验证
x402协议的工作原理
x402协议是基于HTTP的加密货币支付的标准。这种混合MCP服务器提供了两种互补的方法：
方法1：快速中间件（推荐）
这是使用Express中间件的标准x402流：
- 创建受保护的端点：使用
x402_create_protected_endpoint动态创建HTTP端点 - 客户提出请求：当客户端在不付款的情况下访问端点时，他们会收到 需要HTTP 402付款
- 付款说明：402响应在响应体中包括付款详细信息（金额、地址、网络）
- 客户付款：客户在区块链上提交支付交易
- 使用证明重试：客户端使用重试请求
X-PAYMENT包含加密付款证明的标头 - 中间件验证：x402中间件通过协调器验证付款
- 访问已授权：如果有效，端点将返回受保护的内容
方法2：手动付款请求
对于自定义付款流：
- 呼叫
x402_create_payment_request价格和细节 - 服务器返回支付URL和唯一的支付ID
- 用户通过付款URL完成付款
- 呼叫
x402_check_payment_status验证付款完成情况 - 确认付款后授予资源访问权限
网络支持
- 基础 （主网）和 基础Sepolia （测试网）
- 雪崩C链 （主网）和 富士雪崩 （测试网）
- 索拉纳 （主网）和 索拉纳发展网 （测试网）
- 所有已处理的付款 USDC稳定币
用例
- AI API货币化：对昂贵的AI模型推理调用收费
- 内容付费墙：加密货币支付背后的门高级内容
- 小额交易：为单个API调用启用小额付款（低至0.001美元）
- 资源访问控制：管理对计算资源的访问
- API市场动态：AI代理可以自动发现API并为其付费
- 按次付费服务：天气数据、股票价格、翻译API等。
在主网上运行
要在主网上接受真实付款，您需要进行一些更改：
1.设置CDP API密钥
- 注册地址： cdp.coinbase.com
- 创建新项目并生成API凭据
- 设置环境变量：
export CDP_API_KEY_ID=your-api-key-id export CDP_API_KEY_SECRET=your-api-key-secret
2.更新中的配置 src/index.ts
// Uncomment the facilitator import
import { facilitator } from "@coinbase/x402";
const X402_CONFIG = {
payTo: "0xYourMainnetAddress", // Your real mainnet wallet address
network: "base" as const, // Change from "base-sepolia" to "base"
facilitatorUrl: "https://x402.org/facilitator", // Not used for mainnet
expressPort: 4021,
};
3.更新Express中间件以使用CDP引导程序
在 applyPaymentMiddleware() 方法：
private applyPaymentMiddleware() {
if (Object.keys(this.routeConfigs).length > 0) {
this.app.use(paymentMiddleware(
X402_CONFIG.payTo,
this.routeConfigs,
facilitator // Use CDP facilitator instead of testnet URL
));
}
}
定制
测试网配置（当前）
const X402_CONFIG = {
payTo: "0xYourAddress", // Your receiving wallet address
network: "base-sepolia" as const, // or "avalanche-fuji", "solana-devnet"
facilitatorUrl: "https://x402.org/facilitator",
expressPort: 4021,
};
主网配置
const X402_CONFIG = {
payTo: "0xYourAddress", // Your receiving wallet address
network: "base" as const, // or "avalanche", "solana"
facilitatorUrl: "https://x402.org/facilitator",
expressPort: 4021,
};
备注：当您指定价格时，例如 "$0.50"，x402协议自动处理所选网络上的美元支付。
资源
许可证
麻省理工学院