agent402-mcp 0.13.4 → 0.13.6

package/README.md

@@ -1,8 +1,8 @@
 # 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 + 80+ 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).
+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 + 80+ curated multi-tool skill packs** for AI agents (every one priced per call and settled on-chain), paid per call in USDC via the [x402 protocol](https://www.x402.org), **with compute (proof-of-work)** when no wallet is configured, or through a prepaid credits key already issued. (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** (US equity quotes and daily bars from Databento, 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.
+Your agent gets browser rendering, screenshots, PDF text extraction, URL→markdown, live web search **+ web answers with citations**, live **financial/crypto/macro data** (US equity quotes and daily bars from Databento, 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 the pure-CPU utilities - plus 80+ **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
 
@@ -10,7 +10,7 @@ Your agent gets browser rendering, screenshots, PDF text extraction, URL→markd
 MCP server - e.g. claude.ai → Settings → Connectors → Add custom connector. The
 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 (`-32043` if a presented credential was refused), and an MCP client
+call answers with a tool result carrying the challenges in `_meta["org.paymentauth/payment-required"]` (`-32043` if a presented credential was refused), 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:
@@ -29,7 +29,7 @@ With a funded wallet (USDC on any EVM rail the server offers - Base, Polygon, Ar
 }
 ```
 
-With prepaid card credits (no wallet) - buy a pack at https://agent402.tools/credits, claim the `a402_...` key once, and every tool is available:
+With a prepaid credits key already issued (new credits are not on sale) - every tool except the wallet-scoped ones (memory, usage) is available:
 
 ```json
 {
@@ -43,7 +43,7 @@ With prepaid card credits (no wallet) - buy a pack at https://agent402.tools/cre
 }
 ```
 
-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):
+Without a wallet or credits key - the pure-CPU tools work free via proof-of-work (the network/browser/memory tools will ask for a wallet or a credits key):
 
 ```json
 {
@@ -63,7 +63,7 @@ Every variable the server reads (all optional):
 | --- | --- | --- |
 | `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_CREDITS_KEY` | _(unset)_ | A prepaid credits key (`a402_...`) already issued (new credits are not on sale). 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. |
@@ -76,7 +76,7 @@ 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 $3.30 (`route-execute-pro`); multi-tool skill packs run $0.003 to $0.119; and the
+at $3.30 (`route-execute-pro`); multi-tool skill packs run $0.003 to $0.101; and the
 report products run $0.60 to $2.00 per report (domain-audit $0.60 up to the ticker pack at $2.00),
 so set `AGENT402_MAX_PER_CALL` if you want a hard per-call ceiling.
 
@@ -84,6 +84,7 @@ so set `AGENT402_MAX_PER_CALL` if you want a hard per-call ceiling.
 
 - On startup the server reads the live catalog from `https://agent402.tools/api/pricing` + `/openapi.json`.
 - **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).
+- **Decide** (`decide.plan`, `decide.execute`, `decide.feedback`): describe a job and get a call-ready plan over the catalog and outside x402 sellers (tools in order, fallbacks, validated params, chained steps), then run it yourself or through Agent402. Listed when the server offers Decide; see https://agent402.tools/decide.
 - 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.

package/index.js

@@ -17,8 +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_CREDITS_KEY  a prepaid credits key (a402_...) already issued (new credits are not on
+//                         sale); pays per successful call with no wallet
 //   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
@@ -75,6 +75,8 @@ const DEFAULT_CURATED = [
   // Search/answer is the front door; long tail stays behind catalog.search/catalog.call.
   "search", "answer", "search-news", "render",
   "stock-quote", "transcribe", "memory-read", "memory-write",
+  // Present only on hosts running the decide service; skipped elsewhere.
+  "decide", "decide-execute",
 ];
 
 // stdout is the MCP protocol channel — all logging goes to stderr.
@@ -196,7 +198,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.`,
+    `Already hold a prepaid credits key? Set AGENT402_CREDITS_KEY to the a402_ key and it pays per successful call (new credits are not on sale).`,
     `Pricing and details: ${BASE}/tools/${tool.slug}`,
   ].join(" ");
 }
@@ -271,6 +273,20 @@ async function quotedUsd(url, init, listUsd) {
   } catch { return listUsd; /* fail-open to the advertised price */ }
 }
 
+// A refused call's tool text. A 402 body from an x402 v2 seller may also carry
+// the whole PaymentRequired offer (this server copies its PAYMENT-REQUIRED
+// header into the body), which is kilobytes of accepts and extension schemas
+// an agent cannot act on in text. Keep the refusal's own fields (error,
+// reason, hint, retry) and say where the offer is; any other body is returned
+// as it came.
+function failureText(status, text) {
+  let doc;
+  try { doc = JSON.parse(text); } catch { return text; }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc) || typeof doc.x402Version !== "number") return text;
+  const { x402Version: _v, resource: _r, accepts, extensions: _e, ...rest } = doc;
+  return JSON.stringify({ ...rest, status, paymentOptions: Array.isArray(accepts) ? accepts.length : 0, note: "The full offer is in the PAYMENT-REQUIRED header of this 402." });
+}
+
 async function callEndpoint(tool, args = {}) {
   const url = new URL(`${BASE}${tool.path}`);
   const init = { method: tool.method, headers: { Accept: "application/json" } };
@@ -349,7 +365,7 @@ async function callEndpoint(tool, args = {}) {
   }
   const text = await res.text();
   if (res.status >= 400) {
-    return { content: [{ type: "text", text }], isError: true };
+    return { content: [{ type: "text", text: failureText(res.status, text) }], isError: true };
   }
   let parsed;
   try { parsed = JSON.parse(text); } catch { parsed = { raw: text }; }
@@ -713,7 +729,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
           ? "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).`,
+            : `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 already issued (AGENT402_CREDITS_KEY).`,
         install: {
           claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
           claudeCodeNpm: "claude mcp add agent402 -s user -- npx -y agent402-mcp@latest",

package/output-schemas.js

@@ -39,6 +39,8 @@ export const FLAGSHIP_MCP_NAMES = {
   transcribe: "audio.transcribe",
   "memory-read": "memory.read",
   "memory-write": "memory.write",
+  decide: "decide.plan",
+  "decide-execute": "decide.execute",
 };
 
 /** Meta tools listed alongside flagships — dotted canonical names. */
@@ -91,11 +93,11 @@ export function resolveListedName(name) {
 
 /** Open-world / egress tools — honest annotations for directory clients. */
 export const FLAGSHIP_OPEN_WORLD = new Set([
-  "search", "answer", "search-news", "render", "stock-quote", "transcribe",
+  "search", "answer", "search-news", "render", "stock-quote", "transcribe", "decide",
 ]);
 
 /** Tools that mutate durable state (not read-only). */
-export const FLAGSHIP_WRITERS = new Set(["memory-write"]);
+export const FLAGSHIP_WRITERS = new Set(["memory-write", "decide-execute"]);
 
 /** initialize.serverInfo description (MCP Implementation.description). */
 export const MCP_SERVER_DESCRIPTION =
@@ -503,7 +505,7 @@ export function mcpInstallHints(baseUrl) {
  * server.describe. Keep tool names listed-only (dotted Smithery form) (self-consistency) and lead
  * with search/answer as the front door.
  */
-export function mcpInitializeInstructions(baseUrl) {
+export function mcpInitializeInstructions(baseUrl, { decide = false } = {}) {
   const install = mcpInstallHints(baseUrl);
   const hosted = install.hostedUrl;
   return [
@@ -511,12 +513,15 @@ export function mcpInitializeInstructions(baseUrl) {
     "Front door: call web.search or web.answer for live web search and cited answers.",
     "Also listed: web.news, browser.render, market.quote, audio.transcribe, memory.read, memory.write.",
     "Long catalog (500+ tools): call catalog.find with your task, or catalog.search then catalog.call.",
+    // Only where the decide tools are listed: an instruction must never name a
+    // tool the connector does not advertise.
+    ...(decide ? ["A job that needs several tools: call decide.plan with the task for a call-ready plan (tools, order, fallbacks, inputs), then decide.execute to run it; the plan fee comes back as credit toward the run."] : []),
     "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 or prepaid card credits for paid flagships): ${install.claudeCodeNpm}`,
+    `Install (npm + wallet for paid flagships): ${install.claudeCodeNpm}`,
     `Cursor mcp.json: { "mcpServers": { "agent402": { "url": "${hosted}" } } }`,
-    `Why pay here (usage priced under a quoted ceiling, a failed call is not charged and the receipt proves it, keyed retries never pay twice, one key for tools + models + reports, card credits with no wallet, proof at /status and /revenue): ${baseUrl}/why`,
+    `Why pay here (usage priced under a quoted ceiling, a failed call is not charged and the receipt proves it, keyed retries never pay twice, one key for tools + models + reports, no wallet needed for the proof-of-work tools or a report by card, proof at /status and /revenue): ${baseUrl}/why`,
     `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.13.4",
+  "version": "0.13.6",
   "mcpName": "io.github.MikeyPetrillo/agent402",
   "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "homepage": "https://agent402.tools",
@@ -69,21 +69,21 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@solana/kit": "^5.1.0",
-    "@x402/core": "2.26.0",
-    "@x402/evm": "2.26.0",
-    "@x402/fetch": "2.26.0",
-    "@x402/svm": "2.26.0",
+    "@x402/core": "2.27.0",
+    "@x402/evm": "2.27.0",
+    "@x402/fetch": "2.27.0",
+    "@x402/svm": "2.27.0",
     "viem": "^2.21.0"
   },
   "overrides": {
     "qs": "6.16.0",
     "ws": "^8.21.0",
     "hono": "4.13.7",
-    "fast-uri": "3.1.7",
+    "fast-uri": "3.1.8",
     "body-parser": "2.3.0",
     "@hono/node-server": "2.0.12",
-    "ip-address": "10.4.0"
+    "ip-address": "10.7.1"
   }
 }