HTTPayer

@httpayer/mcp

HTTPayer の MCP（Model Context Protocol）サーバーです。クレジット残高を使って、AI エージェントが x402 対応 API を呼び出せるようにします。ウォレット、ブロックチェーン、Web3 の知識は不要です。

• ダッシュボードと API キー：app.httpayer.com
• npm： @httpayer/mcp
• GitHub：httpayer/mcp

---

クイックスタート

AI エージェントを使う場合（推奨）

これを MCP 対応エージェント（Claude Code、Cursor、Windsurf、OpenCode など）に貼り付けます。

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

エージェントが環境を検出し、すべてを自動で処理します。

エージェントを使わない場合（手動）

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. クライアントを再起動して確認します：

エージェントに 「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. エージェントはツール一覧、システム指示、プロンプト、リソースをコンテキスト内で受け取ります。
4. エージェントが fetch を呼び出すと、MCP サーバーはリクエストを POST https://api.httpayer.com/proxy に転送します。
5. HTTPayer のプロキシは 402 を検出し、クレジットを使って支払い、再試行して、最終的な応答を返します。
6. 結果（ステータス、本文、ヘッダー）がエージェントに返されます。

---

MCP の機能

このサーバーは 3 つの MCP プリミティブを公開するため、ユーザーが尋ねなくてもエージェントがコンテキストを自動的に取得できます。

ツール

6 つのツールがあります（詳細は以下のリファレンスを参照）。

プロンプト

名前	説明
httpayer-context	HTTPayer の支払いに関するコンテキスト全体をエージェントに注入します。プロンプトに対応しているクライアントは、セッション開始時にこれを自動的に読み込みます。

Claude Desktop、Cursor などの対応クライアントは、接続時に prompts/list を呼び出し、これらを事前にエージェントのコンテキストに注入します。

リソース

URI	説明
httpayer://skill.md	セットアップガイド全体、トリガーパターン、利用可能なエンドポイント、ワークフローが記載されています。クライアントは必要に応じて、根拠となるコンテキストとしてこれを取得できます。

---

MCP ツールのリファレンス

get_balance

クレジット残高と日次使用量を確認します。

入力： なし

応答例：

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

---

fetch

任意の x402 対応エンドポイントに HTTP リクエストを送信します。支払いは自動的に処理されます。

入力：

フィールド	型	必須	説明
url	string	はい	対象 URL
method	string	いいえ	GET、POST、PUT、DELETE、PATCH。デフォルトは GET です
body	object	いいえ	JSON リクエスト本文
params	object	いいえ	クエリ文字列パラメーター
headers	object	いいえ	追加のリクエストヘッダー
timeout	number	いいえ	タイムアウト（秒）、最大 120

応答例：

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

502 の場合、応答には非同期ポーリング用の webhook_id が含まれます。

---

simulate

フェッチをドライランします。クレジットを消費せずに費用の見積もりを返します。

入力： timeoutを除き、fetchと同じです。

レスポンスの例：

{
  "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は、402 Payment Requiredステータスコードを使用するHTTPネイティブのマイクロペイメントプロトコルです。

HTTPayerを使用しない場合：

1. クライアントがエンドポイントにアクセスし、402と支払い要件を受け取ります
2. クライアントがオンチェーンで支払います（ウォレットとUSDCが必要です）
3. クライアントが支払い証明を添えて再試行します

HTTPayerを使用する場合：

1. クライアントがPOST /proxy { api_url, method, ... }を呼び出します
2. HTTPayerが402を検出し、クレジットを使って支払います
3. HTTPayerが再試行し、最終レスポンスを返します

ブロックチェーンとのやり取りはすべてHTTPayer側で行われます。

---

クレジットシステム

単位	値
1クレジット	0.001 USDC
1 USDC	1,000クレジット
プロキシ手数料	ターゲットへの支払い額の3%

app.httpayer.comでチャージできます。クレジットが100未満になると、エージェントからチャージを促されます。

---

エラー処理

セットアップエラー

状況	動作
キーの形式が無効	エラーを出力し、終了コード1で終了します
キーが拒否された（401）	「API key rejected」を出力し、終了コード1で終了します
ネットワークに接続できない	理由を出力し、終了コード1で終了します

MCP ツールのエラー

すべてのエラーはisError: trueを返します。サーバーは稼働を続け、エージェントには読み取り可能なメッセージが表示されます。

状況	メッセージ
設定がない	"No HTTPayer API key configured. Run: npx @httpayer/mcp setup"
API が2xx以外を返す	"HTTPayer {status}: {body}"
不明なツール	"Unknown tool: {name}"

---

© 2026 HTTPayer Inc.