agent402-mcp 0.13.19 → 0.13.21

package/README.md

@@ -1,59 +1,39 @@
 # agent402-mcp
 
-MCP server for [Agent402](https://agent402.tools), the applied layer of [Agentic Finance](https://agent402.tools/agentic-finance) - a catalog of **500+ pay-per-call web tools and curated multi-tool skill packs** for AI agents, 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 a licensed feed, 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 **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.
+MCP server for [Agent402](https://agent402.tools), the applied layer of Agentic Finance: a catalog of **500+ web tools** that AI agents call one request at a time, paid per call in USDC over x402 or MPP (Machine Payments Protocol). Pure-CPU tools are free: each call solves a small proof-of-work puzzle on your own machine. Other tools are paid per call in USDC over the [x402 protocol](https://www.x402.org) from a wallet you control. Built by [Havok Holdings LLC](https://github.com/MikeyPetrillo/Agent402).
 
 ## 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), 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` carrying the challenges (`-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 with a credits key already issued, run this package locally:
+Pick one setup. Both run locally through `npx`.
 
-With a funded wallet (USDC on any EVM rail the server offers - Base, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc - or USDG on Robinhood Chain, or USDC on Solana via `SOLANA_AGENT_KEY`; the service also settles on Stellar and Algorand, which this package does not sign) - every tool available:
+**1. Free, no wallet.** Pure-CPU tools (no outbound calls, keys or models) run free. Each call solves a proof-of-work puzzle with your CPU, typically well under a second on a laptop. Tools that reach the network or a model ask for a wallet.
 
-```json
-{
-  "mcpServers": {
-    "agent402": {
-      "command": "npx",
-      "args": ["-y", "agent402-mcp"],
-      "env": { "AGENT_KEY": "0xYOUR_PRIVATE_KEY" }
-    }
-  }
-}
+```
+claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.21
 ```
 
-With a prepaid credits key already issued (new credits are not on sale) - every tool except the wallet-scoped ones (memory, usage) is available:
+**2. Paid, with a wallet.** Paid tools are settled in USDC on each call.
 
 ```json
 {
   "mcpServers": {
     "agent402": {
       "command": "npx",
-      "args": ["-y", "agent402-mcp"],
-      "env": { "AGENT402_CREDITS_KEY": "a402_YOUR_KEY" }
+      "args": ["-y", "agent402-mcp@0.13.21"],
+      "env": { "AGENT_KEY": "0xYOUR_PRIVATE_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):
+> Use a new wallet holding only a few dollars of USDC. Never use your main wallet.
 
-```json
-{
-  "mcpServers": {
-    "agent402": { "command": "npx", "args": ["-y", "agent402-mcp"] }
-  }
-}
-```
+Use `SOLANA_AGENT_KEY` instead for USDC on Solana. Each call is capped at $4 by default; there is no session budget unless you set `AGENT402_BUDGET`.
 
-Claude Code: `claude mcp add agent402 -- npx -y agent402-mcp`
+Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.13.21`
+(use a new wallet holding only a few dollars of USDC; never your main wallet).
+
+Advanced setup (chains, MPP, error codes, the hosted connector) is in [Advanced](#advanced).
 
 ## Configuration
 
@@ -63,26 +43,26 @@ Every variable the server reads (all optional):
 | --- | --- | --- |
 | `AGENT_KEY` | _(unset)_ | Hex private key of an EVM wallet funded with USDC on Base (or another EVM chain the server offers), 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 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_CREDITS_KEY` | _(unset)_ | A prepaid credits key (`a402_...`; [agent402.tools/credits](https://agent402.tools/credits) says whether packs are 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. Credits pay Agent402's own services only: `router.execute`, `seller-payability`, `decide.execute` and the flight tools buy from outside sellers and need a wallet key, and memory and usage need a wallet identity. |
 | `AGENT402_URL` | `https://agent402.tools` | Target service (point at your own deployment). Paid calls never follow redirects, so use the address that serves the routes directly; a redirect is refused with the origin to use. |
 | `AGENT402_TOOLS` | curated set | Comma-separated slugs to expose as first-class tools. |
 | `AGENT402_MAX_PER_CALL` | `4` | Refuse any single call priced above this many USD (e.g. `0.05`); `off` disables it. Applies to the wallet and the credits path. |
-| `AGENT402_BUDGET` | no session cap | Opt-in hard cap on total USD spent per session (e.g. `1.00`); unset or `off` means no session cap. Applies to the wallet and the credits path. |
+| `AGENT402_BUDGET` | _(unset, no cap)_ | Optional hard cap on total USD spent per session (e.g. `1.00`); unset or `off` means no session cap. Applies to the wallet and the credits path. |
+| `AGENT402_SHOW_ROUTER` | _(unset)_ | `1` lists `router.execute` and `sellers.list` even without a wallet. Both are listed automatically when a wallet key is set; a credits key does not pay `router.execute`, which buys from outside sellers and takes a wallet payment. |
 | `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). |
 | `AGENT402_ASYNC` | `auto` | Slow routes (reports, video, the premium image; `async.recommended` on their `/api/pricing` row) are paid with `Prefer: respond-async` and collected from their job link, so a long run never outlives the connection. `off` waits on the connection instead (since 0.13.18 sending `Prefer: wait=<maxSeconds>` where the row gives `async.preferWait`); `always` uses a job on every route that runs as one. |
 | `AGENT402_ASYNC_TIMEOUT_MS` | `900000` | How long to poll a job before answering with its link (`structuredContent.jobUrl`) to collect later. |
 
 The per-call cap is on by default and the session budget is opt-in; both are
 enforced on the payment that is signed (or before a credits call is sent) - a
-runaway model is refused, not billed. The
+call over the cap is refused before anything is signed. The
 wallet's x402 client carries a policy that drops every payment option over the
 per-call cap or what is left of the budget, so the 402 the wallet signs is held
 to the caps, and a wallet call sends no unpaid preflight first. Each option is priced from the
 known decimals of its asset (USDC on each rail, USDG on Robinhood Chain), never
 from a decimals value in the challenge, and an option in any other asset is not
 signed. A value that is not a USD amount or `off` reads as the default (the
-$4 per-call cap; no session cap). Set `AGENT402_BUDGET` to bound what one
-session may spend in total.
+$4 per-call cap and no session budget). Set `AGENT402_BUDGET` to cap the session total.
 `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
@@ -92,13 +72,23 @@ report products run $0.60 to $2.00 per report (domain-audit $0.60 up to the tick
 so the default per-call cap of $4 covers every tool; set `AGENT402_MAX_PER_CALL` lower for a
 tighter ceiling.
 
+## Advanced
+
+**Hosted connector (no install).** Add `https://agent402.tools/mcp` as a remote MCP server (for example claude.ai → Settings → Connectors → Add custom connector). Pure-CPU tools run free there, rate-limited. Paid tools are payable on the connector over [MPP](https://agent402.tools/what-is-mpp): a paid call answers JSON-RPC error `-32042` with the payment challenges, and `-32043` if a credential you presented was refused. An MCP client wrapped with `mppx`'s `McpClient.wrap()` pays and retries on its own, with the receipt in `_meta`. This package runs locally for no rate limit, or to pay over x402.
+
+**Chains.** With a funded wallet, `AGENT_KEY` pays USDC on any EVM chain the server offers (Base, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Arc) or USDG on Robinhood Chain. `SOLANA_AGENT_KEY` pays USDC on Solana. The service also settles on Stellar and Algorand, which this package does not sign. Restrict or order chains with `AGENT402_NETWORKS`.
+
+**Credits key.** A prepaid credits key (`AGENT402_CREDITS_KEY`) pays per successful call on Agent402's own services; the routes that buy from outside sellers (`router.execute`, `seller-payability`, `decide.execute`, the flight tools) need a wallet key. [agent402.tools/credits](https://agent402.tools/credits) says whether packs are on sale.
+
+**Error codes.** `-32042` payment required (the challenges are in the error data). `-32043` a presented credential was refused.
+
 ## How it works
 
 - 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+ tool 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, Robinhood Chain included; `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, Arc, Stellar and Algorand, plus USDG on Robinhood Chain - 13 chains total - for callers using a raw x402 client rather than this package.)
+- When a call hits HTTP 402: with a wallet key set (`AGENT_KEY` for the EVM chains, Robinhood Chain included; `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, Arc, Stellar and Algorand, plus USDG on Robinhood Chain - 13 chains total - for callers using a raw x402 client rather than this package. Where the server also offers a Circle Gateway batched accept on Arc or Base, this package pays the plain accept beside it.)
 - Since 0.13.15 the server's requests to the catalog and to sellers (catalog reads, the 402 and the paid retry) refuse a TLS chain through one of the intermediate CAs listed in `networks.js` (keys reported recoverable in Mozilla bug 2083449), keyed on each certificate's SubjectPublicKeyInfo hash, on a dedicated dispatcher. With a proxy or custom dispatcher installed, requests go out through it unchanged.
 - **Slow routes run as jobs** (since 0.13.17): a paid call to a route the catalog marks slow carries `Prefer: respond-async`, answers `202` with a job link, and the server polls `GET /api/jobs/{id}` (free), waiting `Retry-After` seconds between polls, until the answer is ready, reading the job's `state` and falling back to its `status`. Payment settles only on the delivered answer. A caller that sends a `progressToken` gets `notifications/progress` from the job's stage, steps and ETA. A job still running when `AGENT402_ASYNC_TIMEOUT_MS` ends comes back with its `jobUrl` instead.
 - `payment.info` tells the model which mode it's in and what a wallet or a credits key would unlock.

package/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Agent402 MCP server, exposes the agent402.tools catalog (1000+ pay-per-call
+// Agent402 MCP server, exposes the agent402.tools catalog (500+ pay-per-call
 // web tools) to any MCP client (Claude, ChatGPT, custom agents) and settles
 // payment underneath, so the model never sees the 402 dance:
 //
@@ -17,9 +17,11 @@
 //   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 (default 4; off disables)
-//   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 USD spent this session (opt-in: unset = no session cap)
+//   AGENT402_CREDITS_KEY  a prepaid credits key (a402_...); pays per successful call with no wallet,
+//                         on Agent402's own services only (outside-seller routes need a wallet)
+//   AGENT402_BUDGET       optional hard cap on total USD spent this session (no cap by default)
+//   AGENT402_SHOW_ROUTER  "1" lists router.execute and sellers.list without a wallet (both are listed
+//                         when a wallet or credits key is set)
 //   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
 import { createHash } from "node:crypto";
@@ -51,6 +53,8 @@ import {
   outputSchemaFromExample,
   mcpInitializeInstructions,
   toolInputBoundRefusal,
+  AGENT402_MCP_VERSION,
+  clipToolDescription,
 } from "./output-schemas.js";
 
 const BASE = (process.env.AGENT402_URL || "https://agent402.tools").replace(/\/$/, "");
@@ -68,6 +72,10 @@ const HAS_WALLET = Boolean(AGENT_KEY || SOLANA_AGENT_KEY);
 // 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();
+// Listed with a wallet: a credits key does not pay routes that buy from an
+// outside seller (prepaid credits are spent only on Agent402's own services).
+const SHOW_ROUTER = HAS_WALLET || process.env.AGENT402_SHOW_ROUTER === "1";
+const HIDDEN_WITHOUT_WALLET = new Set(["router.execute", META_MCP_NAMES.list_top_sellers]);
 const HAS_CREDITS = /^a402_[A-Za-z0-9_-]{32,64}$/.test(CREDITS_KEY);
 // Slow paid routes (async.recommended on their /api/pricing row) are sent with
 // Prefer: respond-async and collected from their job link (./async-job.js).
@@ -85,8 +93,8 @@ const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.ur
 // by default, at the dearest list price in the Agent402 catalog rounded up to
 // a whole dollar (mcp/test.js checks it still covers the catalog), and `off`
 // disables it; a malformed value reads as that default, never as off. The
-// session budget is opt-in: unset (or `off`) is no session cap, so a long
-// session is never refused by default.
+// session budget is opt-in: unset (or `off`) is no session cap, so a heavy user
+// is never stopped by a default. The per-call cap above still applies.
 const DEFAULT_MAX_PER_CALL_USD = 4;
 const DEFAULT_BUDGET_USD = Infinity;
 const capFromEnv = (name, def) => {
@@ -256,7 +264,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.`,
-    `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).`,
+    `Hold a prepaid credits key? Set AGENT402_CREDITS_KEY to the a402_ key and it pays per successful call on Agent402's own services (${BASE}/credits says whether packs are on sale).`,
     `Pricing and details: ${BASE}/tools/${tool.slug}`,
   ].join(" ");
 }
@@ -674,20 +682,20 @@ async function ensureCatalog() {
 const withCatalog = (handler) => async (req, extra) => { await ensureCatalog(); return handler(req, extra); };
 
 server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
+  // Read-only only for lookups that stay on this machine (describe, payment
+  // info). Anything that reaches the network or can spend is NET: not read-only,
+  // open-world. A host reads readOnlyHint to decide whether to ask first.
   const SAFE = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-  const OPEN = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
-  const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+  const NET = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
   const tools = curated.map((t) => {
     // verb_noun exposed names (match hosted /mcp). CallTool accepts kebab + plain snake too.
     const name = FLAGSHIP_MCP_NAMES[t.slug] || t.slug.replace(/-/g, "_");
-    const ann = t.slug === "memory-write" ? WRITE
-      : ["search", "answer", "search-news", "render", "stock-quote", "transcribe"].includes(t.slug) ? OPEN
-      : SAFE;
+    const ann = NET;
     return {
       name,
       title: t.slug,
       annotations: { title: t.slug, ...ann },
-      description: `[${t.price}/call${t.computePayable ? ", or free via proof-of-work" : ", wallet required"}] ${t.description}`,
+      description: clipToolDescription(`${t.computePayable ? `Paid (${t.price}/call), or free via proof-of-work:` : `Paid (${t.price}/call):`} ${t.description}`),
       inputSchema: t.inputSchema,
       outputSchema: FLAGSHIP_OUTPUT_SCHEMAS[t.slug] || outputSchemaFromExample(null),
     };
@@ -696,9 +704,9 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
     {
       name: META_MCP_NAMES.search_tools,
       title: "Search the Agent402 tool catalog",
-      annotations: { title: "Search the Agent402 tool catalog", ...SAFE },
+      annotations: { title: "Search the Agent402 tool catalog", ...NET },
       description:
-        `BROWSE the long catalog behind the flagship set: keyword search over Agent402's 500+ pay-per-call tools (exact count ${catalog.size}). Start with listed flagships for search/answer/news/render/stock/transcribe/memory; use this for long-tail slugs. Counterpart catalog.find resolves a task to ONE ready-to-run pick. Many pure-CPU tools are free via proof-of-work. OpenAI-compatible LLM gateway at ${BASE}/v1 (chat nano $0.003, auto $0.01, embeddings $0.002) via catalog.call when a wallet key is set. Returns matching tools + workflow templates; call them with catalog.call.`,
+        `Keyword search over the Agent402 catalog of 500+ tools (${catalog.size} loaded by this server). Returns matching tools and workflow templates; run one with catalog.call. Pure-CPU tools are free through proof-of-work; the others are paid per call in USDC when a wallet key is set.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -712,9 +720,9 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
     {
       name: META_MCP_NAMES.find_tool,
       title: "Resolve a task to the one best Agent402 tool",
-      annotations: { title: "Resolve a task to the one best Agent402 tool", ...SAFE },
+      annotations: { title: "Resolve a task to the one best Agent402 tool", ...NET },
       description:
-        "DECIDE, don't browse: resolve a plain-language task to the single best-matching Agent402 tool via the hosted /api/find resolver. Prefer this for anything outside the flagship list. Returns { task, matches } with the top pick first; then run catalog.call with the chosen slug + params.",
+        "Resolve a plain-language task to the single best-matching Agent402 tool through the hosted /api/find resolver. Returns { task, matches } with the top pick first. Run the pick with catalog.call and the slug and params it lists. Use catalog.search to compare several candidates.",
       inputSchema: {
         type: "object",
         properties: {
@@ -728,7 +736,7 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
     {
       name: META_MCP_NAMES.call_tool,
       title: "Run an Agent402 tool",
-      annotations: { title: "Run an Agent402 tool", ...SAFE },
+      annotations: { title: "Run an Agent402 tool", ...NET },
       description:
         "Call any Agent402 tool by slug (find slugs with catalog.find or catalog.search). Payment is handled automatically: USDC via x402 if this server has a wallet key, otherwise free proof-of-work on eligible pure-CPU tools (no wallet needed). Wallet-keyed highlights: live search/answer, stock-quote, render, transcribe, memory, and the /v1 LLM gateway tiers.",
       inputSchema: {
@@ -755,7 +763,7 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
       name: META_MCP_NAMES.describe_server,
       title: "About this Agent402 connector",
       annotations: { title: "About this Agent402 connector", ...SAFE },
-      description: "Describe this stdio MCP server: flagship-first tools, install one-liners, free vs paid, and discovery URLs. Call this first.",
+      description: "Describe this stdio MCP server: the tools it lists, install commands, free vs paid, and discovery URLs.",
       inputSchema: { type: "object", properties: {} },
       outputSchema: META_OUTPUT_SCHEMAS["server.describe"],
     },
@@ -766,9 +774,9 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
       // Pure verb_noun (Smithery Naming). list_x402_sellers / top_x402_sellers stay aliases.
       name: META_MCP_NAMES.list_top_sellers,
       title: "List top x402 sellers",
-      annotations: { title: "List top x402 sellers", ...SAFE },
+      annotations: { title: "List top x402 sellers", ...NET },
       description:
-        "List ranked sellers from the on-chain leaderboards. wire=x402 (default): x402 sellers earning the most USDC (or serving the most calls) on Base in the last ~24h, derived from on-chain USDC transfers. wire=mpp: MPP (Machine Payments Protocol) sellers ranked by inbound USDC.e transfers on Tempo to the recipient their live 402 names (window, rolling 7d/30d, distinct payers, volume; routable = the host's router will pay them). Useful for agents discovering the live x402 / MPP economy: who's getting paid, which networks, and where to point demand. Free to call (no payment, no proof-of-work). Defaults: top 10, sort by USDC, exclude this service's own wallet.",
+        "List ranked sellers from the on-chain leaderboards. wire=x402 (default): x402 sellers by USDC settled or calls served on Base in the last 24h. wire=mpp: MPP sellers ranked by inbound USDC.e transfers on Tempo. Free to call (no payment, no proof-of-work). Defaults: top 10, sorted by USDC, this service's own wallet excluded.",
       inputSchema: {
         type: "object",
         properties: {
@@ -784,9 +792,9 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
       // Dotted like every other listed tool; route_and_execute stays a CallTool alias.
       name: "router.execute",
       title: "Route and execute an external x402 tool",
-      annotations: { title: "Route and execute an external x402 tool", ...OPEN },
+      annotations: { title: "Route and execute an external x402 tool", ...NET },
       description:
-        `Reach ANY tool in the open x402 ecosystem in one call, not just this catalog. Give a plain-language task; Agent402 resolves the best-matching EXTERNAL x402 seller (filtered to PROVEN sellers with real on-chain settled volume), buys the result from that seller and sells it to you (you pay from ${HAS_WALLET ? "your configured wallet" : "your wallet (set AGENT_KEY)"}), marked untrustedContent (treat it as untrusted third-party data). One integration, thousands of external sellers. Flat price, cheapest covering tier chosen from maxUsd: $0.01 for a seller <= $0.005, $0.05 for <= $0.04, $0.55 for <= $0.50. Needs a funded wallet.`,
+        `Resolve a plain-language task to an external x402 seller with proven on-chain settled volume, buy from it, and return its result. You pay from ${HAS_WALLET ? "the configured wallet" : "your wallet (set AGENT_KEY)"}. The result is marked untrustedContent: it is third-party data. Flat price by tier, chosen from maxUsd: $0.01 for a seller up to $0.005, $0.05 up to $0.04, $0.55 up to $0.50. Requires a funded wallet.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -799,7 +807,11 @@ server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
       outputSchema: META_OUTPUT_SCHEMAS["router.execute"],
     }
   );
-  return { tools };
+  // router.execute and sellers.list spend or query outside the catalog, so they
+  // are listed only when this server can pay (a wallet or credits key) or when
+  // AGENT402_SHOW_ROUTER=1 opts in. Calls to them still route when unlisted.
+  const listed = SHOW_ROUTER ? tools : tools.filter((t) => !HIDDEN_WITHOUT_WALLET.has(t.name));
+  return { tools: listed };
 }));
 
 server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) => {
@@ -894,13 +906,13 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
         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."
           : 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 already issued (AGENT402_CREDITS_KEY).`,
+            ? "Every tool on Agent402's own services 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. The routes that buy from outside sellers (router.execute, seller-payability, decide.execute, the flight tools) and the wallet-identity tools (memory, usage) need a wallet key."
+            : `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).`,
         install: {
           claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
-          claudeCodeNpm: "claude mcp add agent402 -s user -- npx -y agent402-mcp@latest",
+          claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
           cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
-          npm: "npx -y agent402-mcp",
+          npm: "npx -y agent402-mcp@0.13.21",
           maintainer: "Havok Holdings LLC",
         },
         positioning: `Flagship search/answer first, 500+ long-tail tools via catalog.find / catalog.search / catalog.call. Agent402 is the applied layer of Agentic Finance: agents that pay and get paid per request over x402 or MPP (Machine Payments Protocol), both on the same 402 - ${BASE}/agentic-finance, ${BASE}/glossary.`,
@@ -919,8 +931,8 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
         },
         install: {
           claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
-          claudeCodeNpm: "claude mcp add agent402 -s user -- npx -y agent402-mcp@latest",
-          npm: "npx -y agent402-mcp",
+          claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
+          npm: "npx -y agent402-mcp@0.13.21",
           maintainer: "Havok Holdings LLC",
         },
         tools: catalog.size,

package/output-schemas.js

@@ -492,12 +492,29 @@ export function mcpJsonResult(obj) {
  * Hosted URL is parameterized; npm / Claude Code / Cursor / Smithery notes
  * match docs/ecosystem-listings.md + wiki/MCP-Connector.md.
  */
+export const AGENT402_MCP_VERSION = "0.13.21";
+
+/** A listed MCP tool description, at most `max` characters. Hosts truncate or
+ *  skip long descriptions, so the listing keeps the first whole sentences; the
+ *  full catalog text stays on catalog.find and the tool's page. */
+export const TOOL_DESCRIPTION_MAX = 400;
+export function clipToolDescription(text, max = TOOL_DESCRIPTION_MAX) {
+  const s = String(text ?? "").replace(/\s+/g, " ").trim();
+  if (s.length <= max) return s;
+  const head = s.slice(0, max);
+  const cut = head.lastIndexOf(". ");
+  if (cut > max * 0.5) return head.slice(0, cut + 1);
+  const sp = head.lastIndexOf(" ", max - 1);
+  return head.slice(0, sp > 0 ? sp : max - 1).replace(/[,;:\-\s]+$/, "") + ".";
+}
+
 export function mcpInstallHints(baseUrl) {
   const hosted = `${baseUrl}/mcp`;
   return {
     hostedUrl: hosted,
     claudeCodeHosted: `claude mcp add --transport http agent402 ${hosted}`,
-    claudeCodeNpm: "claude mcp add agent402 -s user -- npx -y agent402-mcp@latest",
+    walletWarning: "Use a new wallet holding only a few dollars of USDC. Never your main wallet.",
+    claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
     cursorMcpJson: {
       mcpServers: {
         agent402: { url: hosted },
@@ -507,12 +524,12 @@ export function mcpInstallHints(baseUrl) {
       mcpServers: {
         agent402: {
           command: "npx",
-          args: ["-y", "agent402-mcp"],
+          args: ["-y", "agent402-mcp@0.13.21"],
           env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
         },
       },
     },
-    npm: "npx -y agent402-mcp",
+    npm: "npx -y agent402-mcp@0.13.21",
     smithery: `Paste ${hosted} into the add-server form at https://smithery.ai/new. Submission is external; Agent402 does not auto-publish.`,
     maintainer: "Havok Holdings LLC",
   };
@@ -527,22 +544,17 @@ export function mcpInitializeInstructions(baseUrl, { decide = false, mpp = false
   const install = mcpInstallHints(baseUrl);
   const hosted = install.hostedUrl;
   return [
-    "Agent402 is a tools and models layer for AI agents (Havok Holdings LLC) - the applied layer of Agentic Finance: deterministic utilities, a metered model gateway and finished reports, paid per request over x402 or MPP, or free via proof-of-work on the pure-CPU tools.",
-    "One fact: 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.",
+    "Agent402 is the applied layer of Agentic Finance: a catalog of 500+ tools for AI agents: per-call tools and metered models, paid in USDC over x402 or MPP, or free through proof-of-work for the pure-CPU tools.",
+    "Flagship tools: web.search (live web search), web.answer (answers with citations), web.news, browser.render, market.quote, audio.transcribe, memory.read, memory.write.",
+    "Long tail: catalog.search lists tools by keyword, catalog.find returns the best match with its input schema and price, catalog.call runs a tool by slug.",
     // 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 (npm + wallet, pays for web.search, web.answer and the rest): ${install.claudeCodeNpm}`,
-    // The hosted line says what that connector takes: with MPP on it, a wallet
-    // can pay the other tools there too.
-    `${mpp ? "Hosted (proof-of-work tools free; the rest payable there over MPP from a wallet)" : "No wallet yet (hosted, proof-of-work tools only)"}: ${install.claudeCodeHosted}`,
+    ...(decide ? ["Multi-step jobs: decide.plan returns a call-ready plan (tools, order, fallbacks, inputs); decide.execute runs it. The plan fee is credited toward the run."] : []),
+    "Also: server.describe (connector details), payment.info (wallet and payment setup), demand.request (report a missing tool).",
+    `Install (npm package, pinned): ${install.claudeCodeNpm}`,
+    `${mpp ? "Hosted connector (proof-of-work tools free; other tools payable over MPP from a wallet)" : "Hosted connector (proof-of-work tools free; others need a wallet on the npm package)"}: ${install.claudeCodeHosted}`,
     `Cursor mcp.json: { "mcpServers": { "agent402": { "url": "${hosted}" } } }`,
-    `Why pay here (usage priced under a quoted ceiling, a failed x402 call is not charged and the receipt shows 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`,
+    `Docs: ${baseUrl}/llms.txt · status ${baseUrl}/status`,
   ].join("\n");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-mcp",
-  "version": "0.13.19",
+  "version": "0.13.21",
   "mcpName": "io.github.MikeyPetrillo/agent402",
   "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "homepage": "https://agent402.tools",
@@ -82,16 +82,19 @@
     "viem": "^2.21.0"
   },
   "overrides": {
-    "qs": "6.16.0",
+    "qs": "6.16.1",
     "ws": "^8.21.0",
     "hono": "4.13.13",
-    "fast-uri": "3.1.8",
-    "body-parser": "2.3.0",
+    "fast-uri": "3.1.9",
+    "body-parser": "2.4.0",
     "@hono/node-server": "2.0.12",
     "ip-address": "10.7.4",
     "@solana-program/token": "0.17.0",
     "@solana-program/compute-budget": "0.19.0",
     "@solana-program/token-2022": "0.19.0",
-    "@solana/program-client-core": "8.4.0"
+    "@solana/program-client-core": "8.4.0",
+    "@modelcontextprotocol/sdk": {
+      "zod": "4.6.7"
+    }
   }
 }