agent402-mcp 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # agent402-mcp
2
2
 
3
- MCP server for [Agent402](https://agent402.tools), the applied layer of Agentic Finance. Agent402 is a catalog of 500+ tools that AI agents find, pay for per request over x402 or MPP, and call with no account or API key. Paid calls settle 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).
3
+ MCP server for [Agent402](https://agent402.tools), the applied layer of Agentic Finance. Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. 500+ ready tools on the same rails. Paid calls settle 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).
4
+
5
+ ![A paid call on Agent402: the request, the 402 with its price, the signature, the settlement, the answer and the signed receipt](https://raw.githubusercontent.com/MikeyPetrillo/Agent402/main/docs/media/agent402-call.gif)
4
6
 
5
7
  ## Quick start
6
8
 
@@ -9,7 +11,7 @@ Pick one setup. Both run locally through `npx`.
9
11
  **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.
10
12
 
11
13
  ```
12
- claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.0
14
+ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.15.0
13
15
  ```
14
16
 
15
17
  **2. Paid, with a wallet.** Paid tools are settled in USDC on each call.
@@ -19,7 +21,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.0
19
21
  "mcpServers": {
20
22
  "agent402": {
21
23
  "command": "npx",
22
- "args": ["-y", "agent402-mcp@0.14.0"],
24
+ "args": ["-y", "agent402-mcp@0.15.0"],
23
25
  "env": { "AGENT_KEY": "0xYOUR_PRIVATE_KEY" }
24
26
  }
25
27
  }
@@ -30,7 +32,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.0
30
32
 
31
33
  Use `SOLANA_AGENT_KEY` instead for USDC on Solana. Each call is capped at $5 by default to protect your wallet (`AGENT402_MAX_PER_CALL`, `0` or `off` turns it off); there is no session budget unless you set `AGENT402_BUDGET`.
32
34
 
33
- Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.14.0`
35
+ Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.15.0`
34
36
  (use a new wallet holding only a few dollars of USDC; never your main wallet).
35
37
 
36
38
  Advanced setup (chains, MPP, error codes, the hosted connector) is in [Advanced](#advanced).
@@ -68,7 +70,7 @@ server names the variable on stderr. Set `AGENT402_BUDGET` to cap the session to
68
70
  the server runs in proof-of-work mode (pure-CPU tools stay free). Use dedicated
69
71
  low-value wallets for `AGENT_KEY` / `SOLANA_AGENT_KEY`, funded only with what
70
72
  you intend to spend. Most tools cost $0.001 to $0.02. The routing tiers top out
71
- at $3.30 (`route-execute-pro`); multi-tool skill packs run $0.003 to $0.101; and the
73
+ at $3.30 (`route-execute-pro`); multi-tool skill packs run $0.001 to $0.093; and the
72
74
  report products run $0.60 to $2.00 per report (domain-audit $0.60 up to the ticker pack at $2.00),
73
75
  so the default per-call cap of $5 covers every tool; set `AGENT402_MAX_PER_CALL` lower for a
74
76
  tighter ceiling, or `off` for none.
@@ -81,7 +83,10 @@ seller that kept the authorization could still redeem it, so it counts against
81
83
  (`https://agent402.tools`, matched by exact origin), an error status is never
82
84
  settled, so a hold for one ends at the authorization's `validBefore` plus 10
83
85
  minutes (15 minutes after the answer when no `validBefore` is readable). A held
84
- amount whose authorization expires unused is released, never charged. A payment
86
+ amount whose authorization expires unused is released, never charged. Some calls are paid before they run; a failed one can be retried free with the same payment, or is refunded. A
87
+ failure whose body says `charged: true` and `retry: "same-payment"` is that case:
88
+ this server sends the same payment once more, as it was signed, and counts the
89
+ amount once against `AGENT402_BUDGET` as spent, never held. A payment
85
90
  option asking to stay valid for more than a day is refused before anything is
86
91
  signed, so no signed authorization outlives a day.
87
92
 
@@ -94,7 +99,7 @@ its variable name, not its value.
94
99
 
95
100
  **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): the connector answers with an `isError` tool result whose text names every way to pay and whose `_meta["org.paymentauth/payment-required"]` carries the challenges. A presented credential that is refused answers JSON-RPC `-32043`, and a call on the tasks path answers `-32042`, both with `data.challenges`. 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.
96
101
 
97
- **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, Ink) 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`.
102
+ **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, Ink) 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`. A paid call names the `AGENT_KEY` wallet in the `X-Agent402-Wallet` request header with a fresh `X-Agent402-Wallet-Proof` (that key's signature for the host and route), so a server that prices a returning wallet lower can quote it on that call; free calls never carry them.
98
103
 
99
104
  **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.
100
105
 
@@ -103,7 +108,7 @@ its variable name, not its value.
103
108
  ## How it works
104
109
 
105
110
  - On startup the server reads the live catalog from `https://agent402.tools/api/pricing` + `/openapi.json`.
106
- - **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).
111
+ - **Flagship tools** are exposed as first-class MCP tools under dotted names - `web.search`, `web.answer`, `web.news`, `browser.render`, `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).
107
112
  - **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.
108
113
  - 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.
109
114
  - 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, Ink, Stellar and Algorand, plus USDG on Robinhood Chain - 14 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.)
@@ -123,6 +128,7 @@ its variable name, not its value.
123
128
  | --- | --- | --- |
124
129
  | ≤ $0.005 | $0.01 | `POST /api/route/execute` |
125
130
  | ≤ $0.04 | $0.05 | `POST /api/route/execute-plus` |
131
+ | ≤ $0.10 | $0.12 | `POST /api/route/execute-mid` |
126
132
  | ≤ $0.50 | $0.55 | `POST /api/route/execute-max` |
127
133
 
128
134
  A tool priced above the tier's ceiling returns a self-correcting 409 naming its direct route.
package/index.d.ts CHANGED
@@ -29,12 +29,15 @@ export interface Agent402McpEnv {
29
29
  AGENT402_ASYNC_TIMEOUT_MS?: string;
30
30
  }
31
31
 
32
- /** Names this server lists in tools/list. */
32
+ /** Names this server can list in tools/list; a flagship is listed only when
33
+ * the server's catalog serves its tool (market.quote, decide.plan and
34
+ * decide.execute are absent on a server without them). */
33
35
  export type Agent402McpToolName =
34
36
  | "catalog.search" | "catalog.find" | "catalog.call"
35
37
  | "payment.info" | "server.describe" | "sellers.list" | "router.execute"
36
- | "web.search" | "web.answer" | "web.news" | "browser.render" | "market.quote"
37
- | "audio.transcribe" | "memory.read" | "memory.write" | "decide.plan" | "decide.execute";
38
+ | "web.search" | "web.answer" | "web.news" | "browser.render"
39
+ | "audio.transcribe" | "memory.read" | "memory.write" | "decide.plan" | "decide.execute"
40
+ | "market.quote";
38
41
 
39
42
  /** catalog.search arguments. `limit` is clamped to 1..25 (default 10). */
40
43
  export interface CatalogSearchArgs { query: string; limit?: number }
package/index.js CHANGED
@@ -311,7 +311,9 @@ function getPayFetch() {
311
311
  });
312
312
  // Registered after the guard's check of the signed amount, so it runs only
313
313
  // for a payload about to be sent: from here the payment is outstanding.
314
- client.onAfterPaymentCreation(async ({ paymentPayload } = {}) => { const e = signCtx.getStore(); if (e && e.signed) { e.sent = true; e.until = signedValidUntilMs(paymentPayload); } });
314
+ // The payload is kept, so a payment the seller took before a run that
315
+ // failed can be sent once more as it was (never signed again).
316
+ client.onAfterPaymentCreation(async ({ paymentPayload } = {}) => { const e = signCtx.getStore(); if (e && e.signed) { e.sent = true; e.until = signedValidUntilMs(paymentPayload); e.payload = paymentPayload || null; } });
315
317
  if (AGENT_KEY) {
316
318
  const { registerExactEvmScheme } = await import("@x402/evm/exact/client");
317
319
  const { privateKeyToAccount } = await import("viem/accounts");
@@ -332,6 +334,37 @@ function getPayFetch() {
332
334
  return payFetchPromise;
333
335
  }
334
336
 
337
+ // The EVM wallet AGENT_KEY pays from, named on every paid call in the
338
+ // X-Agent402-Wallet header with a fresh proof that this key holds it
339
+ // (X-Agent402-Wallet-Proof: unix seconds and the key's EIP-191 signature over
340
+ // the server's host name, the route, the wallet and those seconds), so a
341
+ // server that prices a returning wallet lower can quote it on that call. The
342
+ // signed retry resends both. Null without an EVM key or when the key is
343
+ // malformed (the paid path reports that itself); never sent on a free call.
344
+ let walletHintPromise = null;
345
+ function walletHint() {
346
+ walletHintPromise ??= (async () => {
347
+ if (!AGENT_KEY) return null;
348
+ try { const { privateKeyToAccount } = await import("viem/accounts"); return evmAccount(privateKeyToAccount); } catch { return null; }
349
+ })();
350
+ return walletHintPromise;
351
+ }
352
+ /** The text the wallet signs for one host and route at `time` (unix seconds). */
353
+ function walletProofMessage({ host, route, wallet, time }) {
354
+ return `Agent402 returning-wallet price\nhost: ${String(host).toLowerCase()}\nroute: ${route}\nwallet: ${String(wallet).toLowerCase()}\ntime: ${time}`;
355
+ }
356
+ /** The headers a paid call to `tool` adds for its wallet hint and proof ({} when there is none). */
357
+ async function walletHintHeaders(tool) {
358
+ const account = await walletHint();
359
+ if (!account) return {};
360
+ try {
361
+ const time = String(Math.floor(Date.now() / 1000));
362
+ const route = `${String(tool.method || "POST").toUpperCase()} ${tool.path}`;
363
+ const signature = await account.signMessage({ message: walletProofMessage({ host: new URL(BASE).hostname, route, wallet: account.address, time }) });
364
+ return { "X-Agent402-Wallet": account.address, "X-Agent402-Wallet-Proof": `${time}.${signature}` };
365
+ } catch { return {}; }
366
+ }
367
+
335
368
  /** The viem account for AGENT_KEY, or walletKeyError. */
336
369
  function evmAccount(privateKeyToAccount) {
337
370
  try { return privateKeyToAccount(AGENT_KEY.trim()); } catch { throw walletKeyError("AGENT_KEY", "a 0x-prefixed 32-byte hex private key"); }
@@ -431,6 +464,23 @@ async function quotedUsd(url, init, listUsd) {
431
464
  // an agent cannot act on in text. Keep the refusal's own fields (error,
432
465
  // reason, hint, retry) and say where the offer is; any other body is returned
433
466
  // as it came.
467
+ /** True when a failed paid answer says its payment was settled before the
468
+ * call ran (charged: true, retry: "same-payment"). Read from a copy. */
469
+ async function settledFirstFailure(res) {
470
+ try {
471
+ const body = typeof res?.clone === "function" ? await res.clone().json() : null;
472
+ return !!body && typeof body === "object" && body.charged === true && body.retry === "same-payment";
473
+ } catch { return false; }
474
+ }
475
+ /** The payment header that carries `payload` as it was signed, or null. */
476
+ async function paymentHeaderFor(payload) {
477
+ if (!payload || typeof payload !== "object") return null;
478
+ try {
479
+ const { encodePaymentSignatureHeader } = await import("@x402/core/http");
480
+ return { "PAYMENT-SIGNATURE": encodePaymentSignatureHeader(payload) };
481
+ } catch { return null; }
482
+ }
483
+
434
484
  function failureText(status, text) {
435
485
  let doc;
436
486
  try { doc = JSON.parse(text); } catch { return text; }
@@ -548,10 +598,12 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
548
598
  const payFetch = await getPayFetch();
549
599
  // Held until the call settles or fails; the guard replaces `usd` with the
550
600
  // amount it lets the wallet sign.
551
- const entry = { usd: price, signed: false, sent: false, refusal: null };
601
+ const entry = { usd: price, signed: false, sent: false, refusal: null, payload: null };
552
602
  pendingSpend.add(entry);
603
+ let hintHeaders = {};
553
604
  try {
554
- const first = await signCtx.run(entry, () => payFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders } }));
605
+ hintHeaders = await walletHintHeaders(tool);
606
+ const first = await signCtx.run(entry, () => payFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders, ...hintHeaders } }));
555
607
  if (isRedirect(first)) {
556
608
  pendingSpend.delete(entry);
557
609
  // A signature already sent leaves that payment's outcome unknown, so
@@ -571,10 +623,27 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
571
623
  throw e;
572
624
  }
573
625
  pendingSpend.delete(entry);
626
+ // A payment the seller settled BEFORE the call ran, whose run then
627
+ // failed (the body says charged: true and retry: "same-payment"): the
628
+ // same payment is sent once more, as it was signed, and the seller runs
629
+ // it at no further charge. Its amount counts once, as spent.
630
+ let takenFirst = false, resent = false;
631
+ if (entry.sent && res.status >= 400 && await settledFirstFailure(res)) {
632
+ takenFirst = true;
633
+ const header = await paymentHeaderFor(entry.payload);
634
+ if (header) {
635
+ resent = true;
636
+ try { res = await collect(await ownFetch(url, { ...paidInit, headers: { ...init.headers, ...asyncHeaders, ...hintHeaders, ...header } })); }
637
+ catch (e) { spentUsd += entry.usd; if (e instanceof AsyncJobPendingError) return pendingJobResult(tool, e); throw e; }
638
+ }
639
+ }
574
640
  // A sent payment is spent when the server confirms settlement (payment
575
641
  // receipt header) or answers 2xx; any other answer leaves the signed
576
642
  // authorization with the seller, so it is held, never released.
577
- if (entry.sent) {
643
+ if (entry.sent && takenFirst) {
644
+ spentUsd += entry.usd;
645
+ if (!res.ok) heldNote = ` The payment of $${entry.usd} was taken before the call ran, so it counts as spent against AGENT402_BUDGET and is owed back, refunded after on-chain proof${resent ? "; the same payment, sent once more, failed too" : "; sending the same payment again runs the call at no further charge"}.`;
646
+ } else if (entry.sent) {
578
647
  if (res.headers.get("payment-response") || res.headers.get("x-payment-response") || res.ok) spentUsd += entry.usd;
579
648
  else if (res.status >= 400 && url.origin === DEFAULT_ORIGIN) {
580
649
  // The default host did not settle it: held until it expires unused.
@@ -765,8 +834,12 @@ function rankWorkflows(query, k = 2) {
765
834
  // MCP wiring
766
835
  // Initialize instructions mirror src/mcp-flagship.js mcpInitializeInstructions
767
836
  // (stdio package cannot import src/ when published). Keep tool names listed-only.
768
- // This server lists no demand.request, so its instructions do not name it.
769
- const INIT_INSTRUCTIONS = mcpInitializeInstructions(BASE, { ...hostedConnectorWiresFor(BASE), demand: false });
837
+ // This server lists no demand.request, so its instructions do not name it;
838
+ // market.quote is named only while it is listed (the catalog lists
839
+ // stock-quote and it is first-class here), so the text is rebuilt after each
840
+ // catalog read (syncInstructions) and before the first initialize.
841
+ const instructionsFor = (stock) => mcpInitializeInstructions(BASE, { ...hostedConnectorWiresFor(BASE), demand: false, stock });
842
+ const INIT_INSTRUCTIONS = instructionsFor(false);
770
843
 
771
844
  const server = new Server(
772
845
  {
@@ -778,6 +851,10 @@ const server = new Server(
778
851
  },
779
852
  { capabilities: { tools: {}, prompts: {} }, instructions: INIT_INSTRUCTIONS },
780
853
  );
854
+ /** Point the initialize instructions at what tools/list lists now. */
855
+ function syncInstructions() {
856
+ server._instructions = instructionsFor(curated.some((t) => t.slug === "stock-quote"));
857
+ }
781
858
 
782
859
  // Skill packs are exposed as MCP prompts, discoverable in slash menus on any
783
860
  // MCP-aware client. The list is fetched once at boot in loadCatalog(); the
@@ -834,6 +911,7 @@ async function ensureCatalog() {
834
911
  try {
835
912
  pricingInfo = await loadCatalog();
836
913
  curated = requested.map((slug) => catalog.get(slug)).filter(Boolean);
914
+ syncInstructions();
837
915
  log(`catalog: ${catalog.size} tools from ${BASE} on a later read; ${curated.length} first-class`);
838
916
  } catch (err) {
839
917
  log(`Could not load the catalog from ${BASE}: ${err.message}: next read in ${CATALOG_RETRY_MS / 1000}s`);
@@ -906,7 +984,7 @@ server.setRequestHandler("tools/list", redacted(withCatalog(async () => {
906
984
  title: "Run an Agent402 tool",
907
985
  annotations: { title: "Run an Agent402 tool", ...CALL_PAID },
908
986
  description:
909
- "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.",
987
+ "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, render, transcribe, memory, and the /v1 LLM gateway tiers.",
910
988
  inputSchema: {
911
989
  type: "object",
912
990
  properties: {
@@ -968,7 +1046,7 @@ server.setRequestHandler("tools/list", redacted(withCatalog(async () => {
968
1046
  properties: {
969
1047
  task: { type: "string", description: "Plain-language task, e.g. 'crypto news headlines' or 'sentiment of a tweet'. Resolved to a proven external seller." },
970
1048
  params: { type: ["object", "string"], description: "Input parameters for the resolved external tool (optional; the seller decides its own schema): an object, or a JSON string of one." },
971
- maxUsd: { type: "number", description: "Max underlying seller price in USD. Default 0.005 (the $0.01 fee tier); above 0.005 and up to 0.04 uses the $0.05 tier; above 0.04 the $0.55 tier (seller up to $0.50)." },
1049
+ maxUsd: { type: "number", description: "Max underlying seller price in USD. Default 0.005 (the $0.01 fee tier); above 0.005 and up to 0.04 uses the $0.05 tier; above 0.04 and up to 0.10 the $0.12 tier; above 0.10 the $0.55 tier (seller up to $0.50)." },
972
1050
  },
973
1051
  required: ["task"],
974
1052
  },
@@ -1084,10 +1162,10 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1084
1162
  claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
1085
1163
  claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
1086
1164
  cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
1087
- npm: "npx -y agent402-mcp@0.14.0",
1165
+ npm: "npx -y agent402-mcp@0.15.0",
1088
1166
  maintainer: "Havok Holdings LLC",
1089
1167
  },
1090
- positioning: `Agent402 is a catalog of 500+ tools that AI agents find, pay for per request over x402 or MPP, and call with no account or API key. 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.`,
1168
+ positioning: `Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. 500+ ready tools on the same rails. Flagship search/answer first, the long tail 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.`,
1091
1169
  ecosystem: "Call sellers.list to see which x402 sellers (any wallet, not just this host) are settling the most USDC (primarily on Base) in the last 24h, or sellers.list with wire=mpp for MPP sellers ranked by on-chain USDC.e transfers on Tempo - discovers the live economy beyond this catalog.",
1092
1170
  });
1093
1171
  }
@@ -1096,7 +1174,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1096
1174
  service: BASE,
1097
1175
  connector: "stdio npm package (agent402-mcp)",
1098
1176
  maintainer: "Havok Holdings LLC",
1099
- positioning: `Agent402 is a catalog of 500+ tools that AI agents find, pay for per request over x402 or MPP, and call with no account or API key. It 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.`,
1177
+ positioning: `Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. 500+ ready tools on the same rails. It 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.`,
1100
1178
  startHere: {
1101
1179
  firstJob: "Search the web and answer questions. Call web.search or web.answer directly, or catalog.find with your task.",
1102
1180
  mode: HAS_WALLET ? "usdc" : HAS_CREDITS ? "credits" : "proof-of-work",
@@ -1104,7 +1182,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1104
1182
  install: {
1105
1183
  claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
1106
1184
  claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
1107
- npm: "npx -y agent402-mcp@0.14.0",
1185
+ npm: "npx -y agent402-mcp@0.15.0",
1108
1186
  maintainer: "Havok Holdings LLC",
1109
1187
  },
1110
1188
  tools: catalog.size,
@@ -1209,12 +1287,17 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
1209
1287
  if (!task) return { content: [{ type: "text", text: "router.execute requires a 'task' (plain-language description of what you need)." }], isError: true };
1210
1288
  const maxUsd = Number(args.maxUsd) > 0 ? Number(args.maxUsd) : 0.005;
1211
1289
  // Pick the CHEAPEST tier whose underlying cap covers maxUsd. The ladder
1212
- // has three rungs; skipping the middle one billed 11x for a mid-priced
1213
- // seller (a $0.02 seller went through the $0.55 tier instead of $0.05).
1290
+ // skipped a middle rung once and billed 11x for a mid-priced seller (a
1291
+ // $0.02 seller went through the $0.55 tier instead of $0.05).
1214
1292
  // Keep this ordered cheapest-first so a new rung is a one-line insert.
1215
- const slug = maxUsd > 0.04 ? "route-execute-max"
1216
- : maxUsd > 0.005 ? "route-execute-plus"
1217
- : "route-execute";
1293
+ // A server that does not list a rung yet is served by the next one up.
1294
+ const ROUTER_TIERS = [
1295
+ { slug: "route-execute", underlyingMaxUsd: 0.005 },
1296
+ { slug: "route-execute-plus", underlyingMaxUsd: 0.04 },
1297
+ { slug: "route-execute-mid", underlyingMaxUsd: 0.1 },
1298
+ { slug: "route-execute-max", underlyingMaxUsd: 0.5 },
1299
+ ];
1300
+ const slug = ROUTER_TIERS.find((t) => maxUsd <= t.underlyingMaxUsd && catalog.has(t.slug))?.slug || "route-execute-max";
1218
1301
  const tool = catalog.get(slug);
1219
1302
  if (!tool) return { content: [{ type: "text", text: `External routing (${slug}) is not in the catalog from ${BASE} yet. It may be rolling out; retry shortly.` }], isError: true };
1220
1303
  // Body matches the route-execute input schema; include:"external" is what
@@ -1270,6 +1353,7 @@ try {
1270
1353
  const requested = (process.env.AGENT402_TOOLS || DEFAULT_CURATED.join(","))
1271
1354
  .split(",").map((s) => s.trim()).filter(Boolean);
1272
1355
  curated = requested.map((slug) => catalog.get(slug)).filter(Boolean);
1356
+ syncInstructions();
1273
1357
  log(`catalog: ${catalog.size} tools from ${BASE}; ${curated.length} first-class, rest via catalog.search/catalog.call`);
1274
1358
  // A key is reported configured only once it parses: a key that does not
1275
1359
  // parse is named (never printed) so the operator sees it before the first
package/output-schemas.js CHANGED
@@ -119,7 +119,7 @@ export const FLAGSHIP_WRITERS = new Set(["memory-write", "decide-execute"]);
119
119
 
120
120
  /** initialize.serverInfo description (MCP Implementation.description). */
121
121
  export const MCP_SERVER_DESCRIPTION =
122
- "Agent402 is a catalog of 500+ tools that AI agents find, pay for per request over x402 or MPP, and call with no account or API key. Flagships: live web search and cited answers, news, browser render, market data, speech-to-text and wallet-keyed memory; the rest via catalog.find. Settle in USDC via x402 or MPP (Machine Payments Protocol) on the same 402, or free via proof-of-work. The applied layer of Agentic Finance. Maintained by Havok Holdings LLC.";
122
+ "Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. 500+ ready tools on the same rails. Flagships: live web search and cited answers, news, browser render, market data, speech-to-text and wallet-keyed memory; the rest via catalog.find. Settle in USDC via x402 or MPP (Machine Payments Protocol) on the same 402, or free via proof-of-work. The applied layer of Agentic Finance. Maintained by Havok Holdings LLC.";
123
123
 
124
124
  /** initialize.serverInfo.websiteUrl */
125
125
  export const MCP_SERVER_WEBSITE = "https://agent402.tools";
@@ -494,7 +494,7 @@ export function mcpJsonResult(obj) {
494
494
  * Hosted URL is parameterized; npm / Claude Code / Cursor notes
495
495
  * match docs/ecosystem-listings.md + wiki/MCP-Connector.md.
496
496
  */
497
- export const AGENT402_MCP_VERSION = "0.14.0";
497
+ export const AGENT402_MCP_VERSION = "0.15.0";
498
498
 
499
499
  /** A listed MCP tool description, at most `max` characters. Hosts truncate or
500
500
  * skip long descriptions, so the listing keeps the first whole sentences; the
@@ -526,12 +526,12 @@ export function mcpInstallHints(baseUrl) {
526
526
  mcpServers: {
527
527
  agent402: {
528
528
  command: "npx",
529
- args: ["-y", "agent402-mcp@0.14.0"],
529
+ args: ["-y", "agent402-mcp@0.15.0"],
530
530
  env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
531
531
  },
532
532
  },
533
533
  },
534
- npm: "npx -y agent402-mcp@0.14.0",
534
+ npm: "npx -y agent402-mcp@0.15.0",
535
535
  maintainer: "Havok Holdings LLC",
536
536
  };
537
537
  }
@@ -555,12 +555,13 @@ export function hostedConnectorWiresFor(baseUrl) {
555
555
  return String(baseUrl || "").replace(/\/+$/, "") === HOSTED_SERVICE_URL ? HOSTED_CONNECTOR_WIRES : {};
556
556
  }
557
557
 
558
- export function mcpInitializeInstructions(baseUrl, { decide = false, mpp = false, x402 = false, demand = true } = {}) {
558
+ export function mcpInitializeInstructions(baseUrl, { decide = false, mpp = false, x402 = false, demand = true, stock = false } = {}) {
559
559
  const install = mcpInstallHints(baseUrl);
560
560
  const hosted = install.hostedUrl;
561
561
  return [
562
- "Agent402 is a catalog of 500+ tools that AI agents find, pay for per request over x402 or MPP, and call with no account or API key. Per-call tools and metered models, paid in USDC, or free through proof-of-work for the pure-CPU tools; the applied layer of Agentic Finance.",
563
- "Flagship tools: web.search (live web search), web.answer (answers with citations), web.news, browser.render, market.quote, audio.transcribe, memory.read, memory.write.",
562
+ "Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. 500+ ready tools on the same rails. Per-call tools and metered models, paid in USDC, or free through proof-of-work for the pure-CPU tools; the applied layer of Agentic Finance.",
563
+ // market.quote only where the server lists a stock quote (it is listed then).
564
+ `Flagship tools: web.search (live web search), web.answer (answers with citations), web.news, browser.render, ${stock ? "market.quote, " : ""}audio.transcribe, memory.read, memory.write.`,
564
565
  "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.",
565
566
  // Only where the decide tools are listed: an instruction must never name a
566
567
  // tool the connector does not advertise.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent402-mcp",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "mcpName": "io.github.MikeyPetrillo/agent402",
5
5
  "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
6
6
  "homepage": "https://agent402.tools",
@@ -9,7 +9,7 @@
9
9
  "url": "git+https://github.com/MikeyPetrillo/Agent402.git",
10
10
  "directory": "mcp"
11
11
  },
12
- "description": "Agent402 MCP server. Agent402 is a catalog of 500+ tools that AI agents find, pay for per request over x402 or MPP, and call with no account or API key. The applied layer of Agentic Finance: skill packs too, USDC or USDG on 14 chains, or free via proof-of-work. Catalog: browser, web search + cited answers, PDFs, OCR, images, LLM inference, image generation, code execution, STT, embeddings, live financial/crypto/macro data, SEC EDGAR filings, deterministic stats & forecasting, compression, payments. Open source, self-hostable.",
12
+ "description": "Agent402 MCP server. Agent402 is the payment and trust layer for agent commerce: agents find, pay for and verify every paid call to Agent402, across x402 and MPP, with a signed receipt for each one. The applied layer of Agentic Finance. 500+ ready tools on the same rails: skill packs too, USDC or USDG on 14 chains, or free via proof-of-work. Catalog: browser, web search + cited answers, PDFs, OCR, images, LLM inference, image generation, code execution, STT, embeddings, live financial/crypto/macro data, SEC EDGAR filings, deterministic stats & forecasting, compression, payments. Open source, self-hostable.",
13
13
  "type": "module",
14
14
  "bin": {
15
15
  "agent402-mcp": "index.js"