X402 Helper MCP
API discovery and x402 paid execution via MCP. Search by natural-language, call with USDC payment
使うべきか
品質と安全性
A
検出事項（2）
- HIGHTool poisoning patterns detected
- MEDIUMTool description contains URL to non-standard domainget_my_history 内
ツール定義とプロトコルへの準拠に関する自動分析に基づいています。
コンテキストコスト
~3,373トークン数（ツール定義）
~9.2 KB一般的なレスポンスサイズ
注意への影響は大きい（128k コンテキストの 2.64%）
これは、サーバーのツールがモデルのコンテキストに読み込まれるたびに消費されるおおよそのトークン数です。数が多いほど、ほかのタスクに使える注意が減ります。
インストール
ワンクリックインストール
これを `claude_desktop_config.json` ファイルに追加してください:
{
"mcpServers": {
"mcp": {
"url": "https://x402helper.xyz/mcp"
}
}
}リモートエンドポイント
https://x402helper.xyz/mcpstreamable-httpできること
ツール一覧
ツール（4）
🟢 読み取り専用🟡 書き込み🔴 削除⚪ 不明
🟢search_endpoints(query, queries, budget, maxRoutesPerQuery)
FREE search for paid API endpoints (x402) by task in natural language. Pass either a natural-language query (the planner will split it) or pre-split queries[]. Returns a structured plan (plan[]) with candidates; IMPORTANT: each candidate contains a routeId. To execute a found endpoint, pass routeId to call_endpoint — do not call the returned URL directly.
入力スキーマ
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural-language task. Pass the whole task in one call; the planner splits it into sub-queries automatically. Ignored if `queries` is provided."
},
"queries": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"maxItems": 8,
"description": "Optional pre-split sub-queries. If provided, takes precedence over `query` and bypasses the LLM planner (so faster). Use only when you already know the decomposition; otherwise omit and pass `query`."
},
"budget": {
"type": "object",
"description": "Optional filter to exclude expensive plans. If the cheapest possible plan (estimate.minPlanCost) exceeds maxTotalPrice, the plan is still returned but estimate.overBudget=true.",
"properties": {
"maxTotalPrice": {
"type": "number",
"minimum": 0,
"description": "Maximum total price for the recommended routes, in `currency`. Set it to skip plans that are too expensive for your task."
},
"currency": {
"type": "string",
"default": "USDC",
"description": "Currency for maxTotalPrice. Defaults to USDC."
}
}
},
"maxRoutesPerQuery": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"default": 3,
"description": "Max alternative routes returned per sub-query. Controls how many candidates you get to choose from; does not affect the discovery fee. Clamped to [1,5]."
}
}
}出力スキーマ
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"mode": {
"type": "string",
"enum": [
"discovery"
]
},
"queries": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
}
}
}
},
"budget": {
"type": "object",
"description": "Echo of the budget applied to this search (may have maxTotalPrice=null if not provided).",
"properties": {
"maxTotalPrice": {
"type": [
"number",
"null"
]
},
"currency": {
"type": "string"
}
}
},
"plan": {
"type": "array",
"description": "Ordered steps. Each step groups candidate routes for one sub-query. Empty array means no matching endpoints were found.",
"items": {
"type": "object",
"required": [
"step",
"queryId",
"query",
"routes"
],
"properties": {
"step": {
"type": "integer",
"minimum": 1
},
"queryId": {
"type": "string"
},
"query": {
"type": "string"
},
"routes": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"routeIndex",
"routeId",
"route",
"parameters",
"requestBody",
"args",
"status"
],
"properties": {
"routeIndex": {
"type": "integer",
"minimum": 1
},
"routeId": {
"type": "string"
},
"route": {
"type": "object",
"required": [
"method",
"url",
"price",
"description",
"score"
],
"properties": {
"method": {
"type": "string"
},
"url": {
"type": "string",
"description": "URL of the endpoint on x402helper.xyz. Do not fetch it directly — pass routeId to call_endpoint instead, which handles payment and required arguments."
},
"price": {
"type": "number",
"description": "Price per call of this route, in USDC. Charged by call_endpoint, not by search_endpoints."
},
"description": {
"type": [
"string",
"null"
]
},
"score": {
"type": "number",
"description": "RAG distance (lower = better match). Routes are sorted by score within each step."
}
}
},
"parameters": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"in",
"required",
"schema"
],
"properties": {
"name": {
"type": "string"
},
"in": {
"type": "string",
"enum": [
"query",
"path",
"header",
"cookie"
]
},
"required": {
"type": "boolean"
},
"description": {
"type": [
"string",
"null"
]
},
"schema": {
"type": "object",
"description": "JSON Schema for this parameter, as declared in the upstream OpenAPI spec."
},
"example": {},
"enum": {
"type": [
"array",
"null"
],
"items": {}
},
"default": {}
}
}
},
"requestBody": {
"oneOf": [
{
"type": "object"
},
{
"type": "null"
}
]
},
"args": {
"type": [
"object",
"null"
]
},
"status": {
"type": "string",
"enum": [
"recommended",
"unresolved"
],
"description": "recommended — route is indexed and its parameters/requestBody are known; safe to pass routeId to call_endpoint. unresolved — route came from search but is missing from the local index; its contract is unknown and call_endpoint will likely fail. Prefer another route in the same step."
}
}
}
}
}
}
},
"estimate": {
"type": "object",
"required": [
"currency",
"planTotal",
"minPlanCost",
"overBudget"
],
"properties": {
"currency": {
"type": "string"
},
"planTotal": {
"type": "number",
"description": "Sum of route.price over all recommended routes."
},
"minPlanCost": {
"type": "number",
"description": "Sum of the cheapest route price per step — the minimum needed to cover every step."
},
"overBudget": {
"type": "boolean",
"description": "True if minPlanCost exceeds budget.maxTotalPrice. The plan is still returned."
}
}
},
"meta": {
"type": "object",
"required": [
"plannerMs",
"plannerSource",
"ragMs",
"composerMs",
"queriesCount",
"routesConsidered",
"routesRecommended",
"maxRoutesPerQuery",
"budget",
"info"
],
"properties": {
"plannerMs": {
"type": "integer"
},
"plannerSource": {
"type": "string",
"enum": [
"llm",
"client"
]
},
"ragMs": {
"type": "integer"
},
"composerMs": {
"type": "integer"
},
"queriesCount": {
"type": "integer"
},
"routesConsidered": {
"type": "integer"
},
"routesRecommended": {
"type": "integer"
},
"maxRoutesPerQuery": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"budget": {
"type": "object",
"properties": {
"maxTotalPrice": {
"type": [
"number",
"null"
]
},
"maxPricePerRoute": {
"type": "number",
"description": "Hard filter applied during search: routes with price > this value were excluded before ranking."
}
}
},
"info": {
"type": "object",
"required": [
"openapi",
"x402",
"contacts"
],
"properties": {
"openapi": {
"type": "string"
},
"x402": {
"type": "string"
},
"contacts": {
"type": "string",
"format": "email"
}
}
}
}
}
},
"required": [
"status",
"mode",
"queries",
"budget",
"plan",
"estimate",
"meta"
]
}🟢call_endpoint(routeId, arguments)
Executes an endpoint found via search_endpoints. Accepts a routeId and arguments. If payment is required, returns isError=true with payment details in structuredContent. In this case, the agent must sign the payment and retry the call with _meta["x402/payment"]. On success, returns the actual result of the endpoint.
入力スキーマ
{
"type": "object",
"properties": {
"routeId": {
"type": "string"
},
"arguments": {
"type": "object"
}
},
"required": [
"routeId"
]
}🟡day_summary(weatherreg, newsreg)
Free read-only morning brief in one call: weather, S&P 500 / Dow / NASDAQ, BTC/ETH/SOL with 24h change, top-5 news. Use when the user asks for a daily brief, morning digest, market+weather snapshot, or "what's happening today. Do NOT use for single-fact lookups or for tickers/coins/countries outside the fixed set — use search_endpoints → call_endpoint instead; Rate limit: 20 calls / 5 min per agent (key = x-agent-id, else ip:user-agent); exceeding → 429 + Retry-After as errors[].retryAfter.
入力スキーマ
{
"type": "object",
"properties": {
"weatherreg": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "City for weather. If omitted, the server tries IP-based geolocation of the caller. If geolocation fails, the weather block is skipped and logged in errors[]."
},
"newsreg": {
"type": "string",
"pattern": "^[A-Za-z]{2}$",
"minLength": 2,
"maxLength": 2,
"description": "2-letter ISO country code for news. If omitted, defaults to worldwide headlines. Non-2-letter → -32602 before any upstream call."
}
},
"additionalProperties": false
}出力スキーマ
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"generatedAt": {
"type": "string",
"format": "date-time"
},
"blocks": {
"type": "object",
"description": "Successfully fetched blocks. Any subset of weather / indices / crypto / news. Blocks that failed are absent and listed in `errors`.",
"additionalProperties": false,
"properties": {
"weather": {
"type": "object",
"required": [
"location",
"temperature",
"windspeed",
"winddirection",
"weathercode",
"time"
],
"additionalProperties": false,
"properties": {
"location": {
"type": "string"
},
"temperature": {
"type": "number"
},
"windspeed": {
"type": "number"
},
"winddirection": {
"type": "number"
},
"weathercode": {
"type": "integer"
},
"time": {
"type": "string",
"description": "ISO-like local time from Open-Meteo, not RFC3339."
}
}
},
"indices": {
"type": "object",
"required": [
"indices"
],
"additionalProperties": false,
"properties": {
"indices": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"description": "One entry per successfully fetched index. Upstream set is fixed: ^GSPC, ^DJI, ^IXIC.",
"items": {
"type": "object",
"required": [
"symbol",
"name",
"price",
"change",
"changePercent",
"updatedAt"
],
"additionalProperties": false,
"properties": {
"symbol": {
"type": "string"
},
"name": {
"type": "string"
},
"price": {
"type": "number"
},
"change": {
"type": [
"number",
"null"
]
},
"changePercent": {
"type": [
"number",
"null"
]
},
"updatedAt": {
"type": [
"string",
"null"
]
}
}
}
},
"failed": {
"type": "array",
"maxItems": 3,
"description": "Only present when some symbols failed but at least one succeeded. ",
"items": {
"type": "object",
"required": [
"symbol",
"error"
],
"additionalProperties": false,
"properties": {
"symbol": {
"type": "string"
},
"error": {
"type": "string"
},
"retryAfter": {
"type": [
"string",
"null"
]
},
"description": "Seconds to wait before retrying this symbol."
}
}
}
}
},
"crypto": {
"type": "object",
"required": [
"coins"
],
"additionalProperties": false,
"properties": {
"coins": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"description": "Fixed set: bitcoin, ethereum, solana.",
"items": {
"type": "object",
"required": [
"id",
"priceUsd",
"change24h"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"priceUsd": {
"type": [
"number",
"null"
]
},
"change24h": {
"type": [
"number",
"null"
]
}
}
}
}
}
},
"news": {
"type": "object",
"required": [
"region",
"articles"
],
"additionalProperties": false,
"properties": {
"region": {
"type": "string",
"description": "Region code that was applied (\"world\" if none)."
},
"articles": {
"type": "array",
"maxItems": 5,
"description": "Up to 5 latest headlines.",
"items": {
"type": "object",
"required": [
"title",
"description",
"url",
"source",
"publishedAt",
"image"
],
"additionalProperties": false,
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"url": {
"type": "string"
},
"source": {
"type": [
"string",
"null"
]
},
"publishedAt": {
"type": "string",
"description": "ISO-like from provider, not RFC3339."
},
"image": {
"type": [
"string",
"null"
]
}
}
}
}
}
}
}
},
"errors": {
"type": "array",
"maxItems": 4,
"description": "Blocks that failed. Empty array when everything succeeded. ",
"items": {
"type": "object",
"required": [
"block",
"error"
],
"additionalProperties": false,
"properties": {
"block": {
"type": "string",
"enum": [
"weather",
"indices",
"crypto",
"news"
]
},
"error": {
"type": "string"
},
"retryAfter": {
"type": [
"string",
"null"
],
"description": "Seconds to wait before retrying this block."
}
}
}
},
"meta": {
"type": "object",
"required": [
"totalMs",
"info"
],
"additionalProperties": false,
"properties": {
"totalMs": {
"type": "integer"
},
"info": {
"type": "object",
"required": [
"x402",
"openapi",
"contacts"
],
"additionalProperties": false,
"properties": {
"x402": {
"type": "string"
},
"openapi": {
"type": "string"
},
"contacts": {
"type": "string",
"format": "email"
}
}
}
}
}
},
"required": [
"status",
"generatedAt",
"blocks",
"errors",
"meta"
],
"additionalProperties": false
}🟢get_my_history(buyerID)
FREE read-only access to your own successful paid calls history. Pass the buyerID you received as `meta.yourID` in any successful paid response — whether you called the endpoint directly over HTTP (e.g. https://x402helper.xyz/test-billing) or via the MCP tool `call_endpoint` (e.g. routeId `34f3gf:r1`). Returns aggregate counters plus per-route events (timestamp, endpoint, network, amount, facilitator, params). No payment required. Rate limit: 15 calls / 10 min per IP; exceeding → 429. User can also view it in a browser at https://x402helper.xyz/getmyhistory.html page.
入力スキーマ
{
"type": "object",
"properties": {
"buyerID": {
"type": "string",
"pattern": "^[0-9a-f]{8}$",
"minLength": 8,
"maxLength": 8,
"description": "8-char lowercase hex buyer ID (the value of meta.yourID from a successful paid response)."
}
},
"required": [
"buyerID"
],
"additionalProperties": false
}出力スキーマ
{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ok"
]
},
"buyerID": {
"type": "string",
"pattern": "^[0-9a-f]{8}$",
"description": "8-char lowercase hex buyer ID (echo of the input)."
},
"found": {
"type": "boolean",
"description": "False when no paid calls were recorded for this buyerID yet. Not an error."
},
"successfulCalls": {
"type": "integer",
"minimum": 0
},
"firstSeenAt": {
"type": [
"string",
"null"
]
},
"lastSeenAt": {
"type": [
"string",
"null"
]
},
"routes": {
"type": "object",
"description": "Map: routeKey → per-route history. routeKey is either a short alias (r1, r2, …) or path template (e.g. \"/9da78c/api/ofac-wallet-screen/:address\"). Empty object when found=false.",
"additionalProperties": {
"type": "object",
"required": [
"calls",
"firstCallAt",
"lastCallAt",
"events"
],
"additionalProperties": false,
"properties": {
"calls": {
"type": "integer",
"minimum": 0,
"description": "Number of successful calls on this route."
},
"firstCallAt": {
"type": [
"string",
"null"
]
},
"lastCallAt": {
"type": [
"string",
"null"
]
},
"events": {
"type": "array",
"description": "Chronological (oldest → newest) list of successful calls for this route. Capped at 500 most recent events per route.",
"items": {
"type": "object",
"required": [
"ts",
"endpoint",
"network",
"amount",
"facilitator",
"params"
],
"additionalProperties": false,
"properties": {
"ts": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of the call."
},
"endpoint": {
"type": [
"string",
"null"
],
"description": "Endpoint template as recorded at call time."
},
"network": {
"type": [
"string",
"null"
],
"description": "CAIP-2 network identifier the buyer paid on (e.g. \"eip155:8453\", \"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp\")."
},
"amount": {
"type": [
"string",
"null"
],
"description": "Amount charged for this call, in the route currency (USDC). String form preferred; legacy records may be numeric."
},
"facilitator": {
"type": [
"string",
"null"
],
"description": "Facilitator that verified the payment: \"dexter\", \"coinbase\", or \"payai\"."
},
"params": {
"type": [
"object",
"null"
],
"description": "Snapshot of call arguments: { path?: {...}, query?: {...}, body?: {...} }. Free-form per route. Null for legacy records."
}
}
}
}
}
}
},
"meta": {
"type": "object",
"required": [
"timestamp",
"contacts"
],
"additionalProperties": false,
"properties": {
"timestamp": {
"type": "string",
"description": "ISO 8601 server time of this response."
},
"yourID": {
"type": "string",
"pattern": "^[0-9a-f]{8}$",
"description": "Echo of buyerID — provided for consistency with meta.yourID in paid responses."
},
"contacts": {
"type": "string",
"description": "Support contact, e.g. \"[email protected]\"."
}
}
}
},
"required": [
"status",
"buyerID",
"found",
"successfulCalls",
"routes",
"meta"
],
"additionalProperties": false
}コミュニティ
エビデンス
最近の観測
検証済みバージョンは記録されていませんツール 4 件