HTTPayer

@httpayer/mcp

HTTPayer 的 MCP（模型上下文协议）服务。可让 AI Agent 使用信用余额调用启用了 x402 的 API——无需钱包、区块链或 Web3 知识。

• 控制台和 API 密钥：app.httpayer.com
• npm： @httpayer/mcp
• GitHub：httpayer/mcp

---

快速入门

使用 AI Agent（推荐）

将以下内容粘贴到任意兼容 MCP 的 Agent（Claude Code、Cursor、Windsurf、OpenCode……）中：

Set up https://httpayer.com/skill.md

Agent 会检测你的环境并自动完成所有操作。

不使用 Agent（手动操作）

1. 运行设置程序：

npx @httpayer/mcp setup

出现提示时，在 app.httpayer.com 获取 API 密钥。

选项：

选项	说明
--key sk-live-...	以非交互方式提供密钥
--client <name>	指定目标客户端：claude-code、claude-desktop、cursor、windsurf、opencode、zed、cline、warp、codex
--scope user|project	Claude Code 作用范围（默认：user）
--yes / -y	跳过所有提示
--update-key	替换现有密钥

2. 添加到客户端：

Claude Code：

claude mcp add httpayer --scope user -- npx -y @httpayer/mcp@latest

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "httpayer": {
      "command": "npx",
      "args": ["-y", "@httpayer/mcp@latest"]
    }
  }
}

Cursor（.cursor/mcp.json）、Windsurf（.windsurf/mcp.json）、Cline（.cline/mcp_settings.json）：

{
  "mcpServers": {
    "httpayer": {
      "command": "npx",
      "args": ["-y", "@httpayer/mcp@latest"]
    }
  }
}

OpenCode（opencode.json 或 ~/.config/opencode/config.json）：

{
  "mcp": {
    "httpayer": {
      "type": "local",
      "command": ["npx", "-y", "@httpayer/mcp@latest"],
      "enabled": true
    }
  }
}

Zed：

{
  "context_servers": {
    "httpayer": {
      "command": {
        "path": "npx",
        "args": ["-y", "@httpayer/mcp@latest"]
      }
    }
  }
}

3. 重启客户端并验证：

向 Agent 提问：“fetch https://api.httpayer.com/demo/v1/base-weather”

如果收到天气响应，说明 HTTPayer 正常运行。

---

工作原理

User prompt
    │
    ▼
AI agent (Claude Code, Cursor, Windsurf...)
    │  uses MCP tools + prompts + resources
    ▼
@httpayer/mcp (local MCP server via npx)
    │  REST calls with x-api-key header
    ▼
api.httpayer.com
    │  proxy handles x402 payment to target
    ▼
Target x402-gated API

运行流程

1. 客户端启动时，通过 npx -y @httpayer/mcp@latest 启动 MCP 服务（stdio 传输）。
2. 服务从 ~/.httpayer/mcp-config.json 读取 API 密钥。
3. Agent 会在其上下文中收到工具列表、系统指令、提示词和资源。
4. Agent 调用 fetch 时，MCP 服务会将请求转发到 POST https://api.httpayer.com/proxy。
5. HTTPayer 的代理会检测到 402，使用你的信用余额完成支付，然后重试并返回最终响应。
6. 结果（状态、正文、标头）会返回给 Agent。

---

MCP 功能

此服务提供三种 MCP 基元，让 Agent 自动获取上下文——无需用户主动询问。

工具

六种工具（请参阅下方完整参考）。

提示词

名称	说明
httpayer-context	将完整的 HTTPayer 支付上下文注入 Agent。支持提示词的客户端会在会话开始时自动加载。

兼容的客户端（Claude Desktop、Cursor 等）会在连接时调用 prompts/list，主动将这些内容注入 Agent 的上下文。

资源

URI	说明
httpayer://skill.md	完整的设置指南、触发模式、可用端点和工作流。客户端可按需获取此资源，作为 grounding 上下文。

---

MCP 工具参考

get_balance

查看信用余额和每日使用量。

输入： 无

响应示例：

{
  "account_id": "account_123",
  "mainnet": {
    "credits_balance": 50000,
    "daily_limit": 100000,
    "daily_spend": 15500,
    "daily_remaining": 84500
  }
}

---

fetch

向任意启用了 x402 的端点发送 HTTP 请求。支付会自动处理。

输入：

字段	类型	必填	说明
url	字符串	是	目标 URL
method	字符串	否	GET、POST、PUT、DELETE、PATCH——默认值为 GET
body	对象	否	JSON 请求正文
params	对象	否	查询字符串参数
headers	对象	否	其他请求标头
timeout	数字	否	超时时间（秒），最长 120 秒

响应示例：

{
  "status": 200,
  "body": { "data": "..." },
  "headers": { "content-type": "application/json" }
}

状态码为 502 时，响应会包含用于异步轮询的 webhook_id。

---

simulate

试运行一次抓取。返回费用估算，不会消耗额度。

**输入：**与 fetch 相同（timeout 除外）。

响应示例：

{
  "requiresPayment": true,
  "proxyFeeBreakdown": {
    "targetAmount": 0.01,
    "proxyFee": 0.0003,
    "totalCreditsCharged": 10.3
  }
}

---

get_topup_link

返回用于添加额度的控制面板 URL。余额不足时展示给用户。

**输入：**无

---

check_limits

检查 HTTPayer 系统的全局每日限额和剩余容量。

**输入：**无

---

get_webhook_status

轮询异步操作的状态。当 fetch 返回带有 webhook_id 的 502 时使用。

输入：webhook_id（字符串，必填）

状态值：pending、success、success_refunded、payment_failed、upstream_error、internal_error、rate_limited

---

HTTPayer API 参考

身份验证：所有请求均需在请求头中携带 x-api-key: sk-live-...。

方法	路径	工具
GET	/v1/credits/balance	get_balance
POST	/proxy	fetch
POST	/proxy/sim	simulate
GET	/limits	check_limits
GET	/webhooks/{id}	get_webhook_status

代理端点

POST https://api.httpayer.com/proxy

{
  "api_url": "https://target.example.com/endpoint",
  "method": "GET",
  "json": { "key": "value" },
  "params": { "query": "param" },
  "headers": { "Custom-Header": "value" },
  "timeout": 30
}

仅需提供 api_url 和 method。

状态码：

代码	含义
200	成功
402	额度不足
429	请求过多
500	代理错误
502	目标拒绝付款——包含 webhook_id

---

配置

API 密钥存储于：~/.httpayer/mcp-config.json

{ "apiKey": "sk-live-..." }

更新方式：npx @httpayer/mcp setup --update-key

---

x402 协议概览

x402 是一种基于 HTTP 的微支付协议，使用 402 Payment Required 状态码。

不使用 HTTPayer：

1. 客户端访问端点 → 收到 402 和付款要求
2. 客户端在链上付款（需要钱包和 USDC）
3. 客户端携带付款证明重试

使用 HTTPayer：

1. 客户端调用 POST /proxy { api_url, method, ... }
2. HTTPayer 检测到 402，使用你的额度付款
3. HTTPayer 重试并返回最终响应

所有区块链交互都在 HTTPayer 侧进行。

---

额度系统

单位	数值
1 credit	0.001 USDC
1 USDC	1,000 credits
代理费	目标付款金额的 3%

在 app.httpayer.com 充值。低于 100 credits 时，Agent 会提示你充值。

---

错误处理

设置错误

情况	行为
密钥格式无效	打印错误并退出，状态码为 1
密钥被拒绝（401）	打印“API key rejected”并退出，状态码为 1
网络不可达	打印原因并退出，状态码为 1

MCP 工具错误

所有错误均返回 isError: true——服务会继续运行，Agent 会收到易读的消息。

情况	消息
无配置	"No HTTPayer API key configured. Run: npx @httpayer/mcp setup"
API 返回非 2xx	"HTTPayer {status}: {body}"
未知工具	"Unknown tool: {name}"

---

© 2026 HTTPayer Inc.