agent402-mcp 0.12.12 → 0.13.0

package/README.md

@@ -1,15 +1,19 @@
 # agent402-mcp
 
-MCP server for [Agent402](https://agent402.tools), the applied layer of [Agentic Finance](https://agent402.tools/agentic-finance) - a catalog of **500+: 400+ pay-per-call web tools + 100+ curated multi-tool skill packs** for AI agents (every one tested, priced, and settled on-chain; every one earns its place), paid per call in USDC via the [x402 protocol](https://www.x402.org), or **with compute (proof-of-work)** when no wallet is configured. (The hosted API is dual-stack: it also accepts [MPP](https://agent402.tools/what-is-mpp) clients on the same 402, settling on Base/Celo or natively on Tempo; this package pays via x402.) Built by [Havok Holdings LLC](https://github.com/MikeyPetrillo/Agent402).
+MCP server for [Agent402](https://agent402.tools), the applied layer of [Agentic Finance](https://agent402.tools/agentic-finance) - a catalog of **500+: 400+ pay-per-call web tools + 100+ curated multi-tool skill packs** for AI agents (every one tested, priced, and settled on-chain; every one earns its place), paid per call in USDC via the [x402 protocol](https://www.x402.org), **with compute (proof-of-work)** when no wallet is configured, or **by card** through a prepaid credits key. (The hosted API is dual-stack: it also accepts [MPP](https://agent402.tools/what-is-mpp) clients on the same 402, settling on Base/Celo or natively on Tempo; this package pays via x402 or credits.) Built by [Havok Holdings LLC](https://github.com/MikeyPetrillo/Agent402).
 
-Your agent gets browser rendering, screenshots, PDF text extraction, URL→markdown, live web search **+ web answers with citations**, live **financial/crypto/macro data** (Yahoo stock quotes, CoinGecko, FRED, ECB FX, World Bank, yield curve), **SEC EDGAR filings** (10-K/10-Q text, XBRL, insider, 13F, IPO calendar), **deterministic stats & forecasting** (Pearson correlation, OLS, Holt-Winters), **compression** (gzip/brotli), DNS/TLS/WHOIS + email-deliverability checks, wallet-keyed shared memory, and 200+ deterministic pure-CPU utilities - plus 100+ **skill packs** like `security-audit`, `trend-analysis`, `structured-scrape`, `decode-blob`, and `forecasting-bake-off` callable as MCP prompts. Payment handled invisibly underneath the MCP calls. No signup, no API key.
+Your agent gets browser rendering, screenshots, PDF text extraction, URL→markdown, live web search **+ web answers with citations**, live **financial/crypto/macro data** (Yahoo stock quotes, CoinGecko, FRED, ECB FX, World Bank, yield curve), **SEC EDGAR filings** (10-K/10-Q text, XBRL, insider, 13F, IPO calendar), **deterministic stats & forecasting** (Pearson correlation, OLS, Holt-Winters), **compression** (gzip/brotli), DNS/TLS/WHOIS + email-deliverability checks, wallet-keyed shared memory, and 200+ deterministic pure-CPU utilities - plus 100+ **skill packs** like `security-audit`, `trend-analysis`, `structured-scrape`, `decode-blob`, and `forecasting-bake-off` callable as MCP prompts, and the **report products** (deep research, company dossier, 13F fund report, domain audit, token risk, FDA recall, insider flow, market brief) as ordinary catalog slugs. Payment handled invisibly underneath the MCP calls. No signup, no API key.
 
 ## Quick start
 
 **Zero install (hosted connector):** add `https://agent402.tools/mcp` as a remote
 MCP server - e.g. claude.ai → Settings → Connectors → Add custom connector. The
-pure-CPU tools run free there (rate-limited); for the full catalog and no rate
-limit, run this package locally with a wallet:
+pure-CPU tools run free there (rate-limited), and the paid tools are payable
+right on the connector over [MPP](https://agent402.tools/what-is-mpp): a paid
+call answers JSON-RPC error `-32042` with the challenges, and an MCP client
+wrapped with `mppx`'s `McpClient.wrap()` (USDC on Base/Celo, or native Tempo)
+pays and retries on its own, receipt in `_meta`. For no rate limit, or to pay
+over x402 or by card instead, run this package locally:
 
 With a funded wallet (USDC on Base, Polygon, Arbitrum, Monad, or Solana, or USDG on Robinhood Chain - the underlying service accepts 12 chains in total, but this package currently signs only EVM and Solana payments) - every tool available:
 
@@ -25,7 +29,21 @@ With a funded wallet (USDC on Base, Polygon, Arbitrum, Monad, or Solana, or USDG
 }
 ```
 
-Without a wallet - the 200+ pure-CPU tools work free via proof-of-work (the network/browser/memory tools will ask for a wallet):
+With prepaid card credits (no wallet) - buy a pack at https://agent402.tools/credits, claim the `a402_...` key once, and every tool is available:
+
+```json
+{
+  "mcpServers": {
+    "agent402": {
+      "command": "npx",
+      "args": ["-y", "agent402-mcp"],
+      "env": { "AGENT402_CREDITS_KEY": "a402_YOUR_KEY" }
+    }
+  }
+}
+```
+
+Without a wallet or credits key - the 200+ pure-CPU tools work free via proof-of-work (the network/browser/memory tools will ask for a wallet or a credits key):
 
 ```json
 {
@@ -37,14 +55,40 @@ Without a wallet - the 200+ pure-CPU tools work free via proof-of-work (the netw
 
 Claude Code: `claude mcp add agent402 -- npx -y agent402-mcp`
 
+## Configuration
+
+Every variable the server reads (all optional):
+
+| env | default | meaning |
+| --- | --- | --- |
+| `AGENT_KEY` | _(unset)_ | Hex private key of an EVM wallet funded with USDC on Base (or Polygon/Arbitrum/Monad), or USDG on Robinhood Chain. |
+| `SOLANA_AGENT_KEY` | _(unset)_ | Base58 secret key (or JSON byte array) of a Solana wallet funded with USDC on Solana. |
+| `AGENT402_CREDITS_KEY` | _(unset)_ | A prepaid card-credits key (`a402_...`) from https://agent402.tools/credits. Sent as `Authorization: Bearer` on every catalog call; the server debits the list price only on a successful (200) call and answers `X-Credits-Balance`. Used only when no wallet key is set (a wallet key wins); in credits mode every call - pure-CPU tools included - is debited from the key. |
+| `AGENT402_URL` | `https://agent402.tools` | Target service (point at your own deployment). |
+| `AGENT402_TOOLS` | curated set | Comma-separated slugs to expose as first-class tools. |
+| `AGENT402_MAX_PER_CALL` | unlimited | Refuse any single call priced above this many USD (e.g. `0.01`). Applies to the wallet and the credits path. |
+| `AGENT402_BUDGET` | unlimited | Hard cap on total USD spent per session (e.g. `1.00`). Applies to the wallet and the credits path. |
+| `AGENT402_NETWORKS` | _(unset)_ | Restrict + order the chains to pay on - e.g. `robinhood` (USDG on Robinhood Chain), `base,solana`, or a raw CAIP-2 like `eip155:4663`. Unset = the client picks (effectively Base on multi-chain sellers). |
+
+Spend controls are enforced **before a payment is signed** (or a credits call is
+sent) - a runaway model is refused, not billed. `payment.info` reports the
+caps, what's been spent, and what remains. With no wallet key and no credits key,
+the server runs in proof-of-work mode (pure-CPU tools stay free). Use dedicated
+low-value wallets for `AGENT_KEY` / `SOLANA_AGENT_KEY`, funded only with what
+you intend to spend. Most tools cost $0.001–$0.02. The routing tiers top out
+at $0.55 (`route-execute-max`); multi-tool skill packs run up to $1.50; and the
+report products run $5 to $39 per report (research $5 up to dossier-max $39),
+so set `AGENT402_MAX_PER_CALL` if you want a hard per-call ceiling.
+
 ## How it works
 
 - On startup the server reads the live catalog from `https://agent402.tools/api/pricing` + `/openapi.json`.
-- **Flagship tools** (`search`, `answer`, `search-news`, `render`, `stock-quote`, `transcribe`, `memory-read`, `memory-write`) are exposed as first-class MCP tools - search/answer is the front door. Override the set with `AGENT402_TOOLS`.
-- The rest of the 500+ endpoint catalog is reachable via `find_tool` / `search_tools` + `call_tool` - keeping your context window small.
-- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains - Base/Polygon/Arbitrum/Monad plus Robinhood Chain, `SOLANA_AGENT_KEY` for Solana), the server signs an x402 payment on a chain the seller accepts and retries; without a key it solves the tool's proof-of-work challenge (~0.2 s of CPU) on the eligible tools. (The service settles USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Stellar and Algorand, plus USDG on Robinhood Chain - 12 chains total - for callers using a raw x402 client rather than this package.)
-- `payment_info` tells the model which mode it's in and what a wallet would unlock.
-- `list_top_sellers` returns the live x402 leaderboard - which sellers are settling the most USDC (primarily on Base) in the last ~24h, derived from on-chain transfers. Free to call (no payment, no proof-of-work). Useful for agents discovering the wider x402 economy beyond this single service's catalog. (Aliases: `list_x402_sellers`, `top_x402_sellers`.)
+- **Flagship tools** are exposed as first-class MCP tools under dotted names - `web.search`, `web.answer`, `web.news`, `browser.render`, `market.quote`, `audio.transcribe`, `memory.read`, `memory.write` - search/answer is the front door. Override the set with `AGENT402_TOOLS` (slugs; a non-flagship slug is listed as its snake_case name).
+- The rest of the 500+ endpoint catalog is reachable via the meta tools `catalog.search` / `catalog.find` + `catalog.call` - keeping your context window small. The same dotted names are listed on the hosted connector; the older snake names (`search_tools`, `find_tool`, `call_tool`, `get_payment_info`, `describe_server`, `list_top_sellers`, and the flagship `search_web` …) remain accepted as CallTool aliases, so existing configs keep working.
+- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains - Base/Polygon/Arbitrum/Monad plus Robinhood Chain, `SOLANA_AGENT_KEY` for Solana), the server signs an x402 payment on a chain the seller accepts and retries; with only a credits key it sends `Authorization: Bearer a402_…` and the server debits the balance on success; with neither it solves the tool's proof-of-work challenge (~0.2 s of CPU) on the eligible tools. (The service settles USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Stellar and Algorand, plus USDG on Robinhood Chain - 12 chains total - for callers using a raw x402 client rather than this package.)
+- `payment.info` tells the model which mode it's in and what a wallet or a credits key would unlock.
+- `server.describe` returns orientation (flagship-first tools, install one-liners, free vs paid, discovery URLs). Call it first.
+- `sellers.list` returns the live leaderboards - `wire: "x402"` (default) ranks x402 sellers settling the most USDC (primarily on Base) in the last ~24h from on-chain transfers; `wire: "mpp"` ranks live-verified MPP sellers by inbound USDC.e transfers on Tempo. Free to call (no payment, no proof-of-work). Useful for agents discovering the wider x402 / MPP economy beyond this single service's catalog.
 - `route_and_execute` reaches tools **outside** this catalog in one call: give it a plain-language `task` and Agent402 resolves a proven external x402 seller (one with real on-chain settled volume), pays that seller on your behalf, and relays the result marked `untrustedContent`. Wallet-only. Flat routing fee, cheapest covering tier chosen from `maxUsd`:
 
   | Underlying seller price | Fee | Route |
@@ -54,6 +98,7 @@ Claude Code: `claude mcp add agent402 -- npx -y agent402-mcp`
   | ≤ $0.50 | $0.55 | `POST /api/route/execute-max` |
 
   A tool priced above the tier's ceiling returns a self-correcting 409 naming its direct route.
+- **Report products** are catalog slugs like any other, so `catalog.call` runs them with a wallet or a credits key: `research` ($5), `research-pro` ($15), `research-max` ($30), `market-brief` ($15), `dossier` ($19), `dossier-max` ($39), `fund-report` ($9), `fund-report-max` ($19), `domain-audit` ($5), `domain-audit-pro` ($9), `token-risk` ($5), `token-risk-pro` ($12), `recall-report` ($5), `insider-report` ($9). The same reports are sold by card at https://agent402.tools/reports, and the recurring monitors (domain, fund, recall, insider, IPO - $9/month) at https://agent402.tools/monitors.
 
 ## Workflows (skill packs)
 
@@ -65,31 +110,10 @@ automatically:
 - `prompts/list` returns each pack with typed arguments.
 - `prompts/get { name: "<slug>", arguments: { … } }` returns the rendered
   task template - a Claude-ready plan with the chosen tools wired in.
-- `search_tools` also surfaces matching workflows alongside individual tools,
+- `catalog.search` also surfaces matching workflows alongside individual tools,
   so a task-shaped query points the agent at the right plan, not just the
   raw tools.
 
-## Configuration
-
-| env | default | meaning |
-| --- | --- | --- |
-| `AGENT_KEY` | _(unset)_ | Hex private key of an EVM wallet funded with USDC on Base (or Polygon/Arbitrum/Monad), or USDG on Robinhood Chain. |
-| `SOLANA_AGENT_KEY` | _(unset)_ | Base58 secret key (or JSON byte array) of a Solana wallet funded with USDC on Solana. |
-| `AGENT402_URL` | `https://agent402.tools` | Target service (point at your own deployment). |
-| `AGENT402_TOOLS` | curated set | Comma-separated slugs to expose as first-class tools. |
-| `AGENT402_MAX_PER_CALL` | unlimited | Refuse any single call priced above this many USD (e.g. `0.01`). |
-| `AGENT402_BUDGET` | unlimited | Hard cap on total USDC spent per session (e.g. `1.00`). |
-| `AGENT402_NETWORKS` | _(unset)_ | Restrict + order the chains to pay on - e.g. `robinhood` (USDG on Robinhood Chain), `base,solana`, or a raw CAIP-2 like `eip155:4663`. Unset = the client picks (effectively Base on multi-chain sellers). |
-
-Spend controls are enforced **before a payment is signed** - a runaway model is
-refused, not billed. `payment_info` reports the caps, what's been spent, and
-what remains. With neither key set, the server runs in proof-of-work mode
-(pure-CPU tools stay free). Use dedicated low-value wallets for `AGENT_KEY` /
-`SOLANA_AGENT_KEY`, funded only with what you intend to spend. Most tools cost
-$0.001–$0.02; the priciest single tool is $0.55 (`route-execute-max`) and
-multi-tool skill packs run up to $1.50, so set `AGENT402_MAX_PER_CALL` if you
-want a hard per-call ceiling.
-
 ## Test
 
 From the repo root: `node mcp/test.js` (boots a local paywalled instance and drives the MCP server with a real client; the proof-of-work path settles real challenges).

package/index.js

@@ -17,6 +17,8 @@
 //   SOLANA_AGENT_KEY      base58 (or JSON byte-array) secret key of a funded Solana wallet (USDC on Solana) — optional
 //   AGENT402_TOOLS        comma-separated slugs to expose first-class (overrides default)
 //   AGENT402_MAX_PER_CALL refuse any single call priced above this many USD (e.g. 0.01)
+//   AGENT402_CREDITS_KEY  a prepaid card-credits key (a402_...) from https://agent402.tools/credits -
+//                         pays every tool by card with no wallet; debited per successful call
 //   AGENT402_BUDGET       hard cap on total USDC spent this session (e.g. 1.00)
 //   AGENT402_NETWORKS     restrict + order the chains to pay on (e.g. "robinhood" for USDG on
 //                         Robinhood Chain, "base,solana", or a raw CAIP-2 like eip155:4663) — optional
@@ -51,6 +53,11 @@ const AGENT_KEY = process.env.AGENT_KEY || "";
 // settle on whichever chain the seller offers (EVM accepts are tried first).
 const SOLANA_AGENT_KEY = process.env.SOLANA_AGENT_KEY || "";
 const HAS_WALLET = Boolean(AGENT_KEY || SOLANA_AGENT_KEY);
+// Prepaid card credits (no wallet): a key bought at https://agent402.tools/credits.
+// Sent as Authorization: Bearer on every catalog call; the server debits the
+// list price only on a successful (200) call and returns X-Credits-Balance.
+const CREDITS_KEY = (process.env.AGENT402_CREDITS_KEY || "").trim();
+const HAS_CREDITS = /^a402_[A-Za-z0-9_-]{32,64}$/.test(CREDITS_KEY);
 // Version comes from package.json — the serverInfo self-report drifted from
 // the published version once (0.11.5 vs 0.12.1) because this was a hardcoded
 // string bumped by hand. Reading the manifest makes drift impossible.
@@ -188,6 +195,7 @@ function walletRequiredText(tool) {
     `To enable it: set AGENT_KEY on this MCP server to the hex private key of an EVM wallet funded with USDC`,
     `on Base (or Polygon/Arbitrum), and/or SOLANA_AGENT_KEY to the base58 secret key of a Solana wallet funded`,
     `with USDC on Solana. Payment is per call via the x402 protocol — no signup or API key.`,
+    `No wallet? Buy prepaid card credits at ${BASE}/credits and set AGENT402_CREDITS_KEY to the a402_ key - every tool then pays by card, debited per successful call.`,
     `Pricing and details: ${BASE}/tools/${tool.slug}`,
   ].join(" ");
 }
@@ -206,7 +214,23 @@ async function callEndpoint(tool, args = {}) {
   }
 
   let res;
-  if (HAS_WALLET) {
+  if (!HAS_WALLET && HAS_CREDITS) {
+    // Card credits: same budget guards as the wallet path (the server enforces
+    // the balance; these keep a runaway session from draining a pack).
+    const price = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
+    if (price > MAX_PER_CALL) {
+      return { content: [{ type: "text", text: `Refused: "${tool.slug}" costs ${tool.price}/call, above the AGENT402_MAX_PER_CALL cap of $${MAX_PER_CALL}.` }], isError: true };
+    }
+    if (spentUsd + price > BUDGET) {
+      return { content: [{ type: "text", text: `Refused: session budget exhausted ($${spentUsd.toFixed(4)} of $${BUDGET} spent; "${tool.slug}" costs ${tool.price}).` }], isError: true };
+    }
+    res = await fetch(url, { ...init, headers: { ...init.headers, Authorization: `Bearer ${CREDITS_KEY}` } });
+    if (res.ok) spentUsd += price;
+    if (res.status === 402) {
+      let body = {}; try { body = await res.clone().json(); } catch { /* plain */ }
+      return { content: [{ type: "text", text: `Credits refused for "${tool.slug}": ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""}. Top up at ${body.topup || `${BASE}/credits`}.` }], isError: true };
+    }
+  } else if (HAS_WALLET) {
     const price = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
     if (price > MAX_PER_CALL) {
       return {
@@ -590,7 +614,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       const computePayable = [...catalog.values()].filter((t) => t.computePayable).length;
       return mcpJsonResult({
         service: BASE,
-        mode: HAS_WALLET ? "usdc" : "proof-of-work",
+        mode: HAS_WALLET ? "usdc" : HAS_CREDITS ? "credits" : "proof-of-work",
         wallet: address,
         solanaWallet: solanaAddress,
         network: pricingInfo?.payment?.network ?? "base",
@@ -599,7 +623,8 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         payableWithCompute: computePayable,
         walletOnly: catalog.size - computePayable,
         workflows: skillPacks.length,
-        spendControls: HAS_WALLET
+        credits: HAS_CREDITS ? { configured: true, how: "prepaid card credits (Authorization: Bearer a402_...) - every tool pays by card, debited only on a successful call", balance: `${BASE}/api/credits/balance`, topup: `${BASE}/credits` } : { configured: false, buy: `${BASE}/credits` },
+        spendControls: (HAS_WALLET || HAS_CREDITS)
           ? {
               maxPerCallUsd: MAX_PER_CALL === Infinity ? "unlimited" : MAX_PER_CALL,
               sessionBudgetUsd: BUDGET === Infinity ? "unlimited" : BUDGET,
@@ -608,8 +633,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             }
           : "n/a (proof-of-work mode spends CPU, not money)",
         note: HAS_WALLET
-          ? "Every tool is available; each call is paid in USDC via x402 from the configured wallet(s) — EVM chains via AGENT_KEY, Solana via SOLANA_AGENT_KEY — within the spend controls above."
-          : `No wallet configured: ${computePayable} pure-CPU tools are free via proof-of-work; the ${catalog.size - computePayable} network/browser/memory tools need a funded wallet (set AGENT_KEY for Base/Polygon/Arbitrum and/or SOLANA_AGENT_KEY for Solana).`,
+          ? "Every tool is available; each call is paid in USDC via x402 from the configured wallet(s) - EVM chains via AGENT_KEY, Solana via SOLANA_AGENT_KEY - within the spend controls above."
+          : HAS_CREDITS
+            ? "Every tool is available; each call is paid from the prepaid card credits key (AGENT402_CREDITS_KEY), debited only on a successful call, within the spend controls above."
+            : `No wallet or credits key configured: ${computePayable} pure-CPU tools are free via proof-of-work; the ${catalog.size - computePayable} network/browser/memory tools need a funded wallet (AGENT_KEY / SOLANA_AGENT_KEY) or a prepaid credits key (AGENT402_CREDITS_KEY, buy at ${BASE}/credits).`,
         install: {
           claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
           claudeCodeNpm: "claude mcp add agent402 -s user -- npx -y agent402-mcp@latest",
@@ -629,7 +656,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         positioning: `Agent402 is the applied layer of Agentic Finance: software agents that pay and get paid on their own, per request, over x402 or MPP (Machine Payments Protocol) - both answered on the same 402. ${BASE}/agentic-finance, ${BASE}/glossary.`,
         startHere: {
           firstJob: "Search the web and answer questions. Call web.search or web.answer directly, or catalog.find with your task.",
-          mode: HAS_WALLET ? "usdc" : "proof-of-work",
+          mode: HAS_WALLET ? "usdc" : HAS_CREDITS ? "credits" : "proof-of-work",
         },
         install: {
           claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,

package/output-schemas.js

@@ -514,7 +514,7 @@ export function mcpInitializeInstructions(baseUrl) {
     "Orientation: call server.describe. Payment rails / wallet setup: call payment.info.",
     "Missing a tool: call demand.request. Ecosystem sellers: call sellers.list.",
     `Install (hosted, zero wallet): ${install.claudeCodeHosted}`,
-    `Install (npm + wallet for paid flagships): ${install.claudeCodeNpm}`,
+    `Install (npm + wallet or prepaid card credits for paid flagships): ${install.claudeCodeNpm}`,
     `Cursor mcp.json: { "mcpServers": { "agent402": { "url": "${hosted}" } } }`,
     `Docs: ${baseUrl}/llms.txt · ${baseUrl}/api/find?q=… · status ${baseUrl}/status`,
   ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-mcp",
-  "version": "0.12.12",
+  "version": "0.13.0",
   "mcpName": "io.github.MikeyPetrillo/agent402",
   "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "homepage": "https://agent402.tools",