agent402-mcp 0.13.22 → 0.13.25
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 +6 -6
- package/index.js +36 -8
- package/networks.js +10 -14
- package/output-schemas.js +3 -3
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@ Pick one setup. Both run locally through `npx`.
|
|
|
9
9
|
**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
10
|
|
|
11
11
|
```
|
|
12
|
-
claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.
|
|
12
|
+
claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.25
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
**2. Paid, with a wallet.** Paid tools are settled in USDC on each call.
|
|
@@ -19,7 +19,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.22
|
|
|
19
19
|
"mcpServers": {
|
|
20
20
|
"agent402": {
|
|
21
21
|
"command": "npx",
|
|
22
|
-
"args": ["-y", "agent402-mcp@0.13.
|
|
22
|
+
"args": ["-y", "agent402-mcp@0.13.25"],
|
|
23
23
|
"env": { "AGENT_KEY": "0xYOUR_PRIVATE_KEY" }
|
|
24
24
|
}
|
|
25
25
|
}
|
|
@@ -30,7 +30,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.13.22
|
|
|
30
30
|
|
|
31
31
|
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`.
|
|
32
32
|
|
|
33
|
-
Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.13.
|
|
33
|
+
Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.13.25`
|
|
34
34
|
(use a new wallet holding only a few dollars of USDC; never your main wallet).
|
|
35
35
|
|
|
36
36
|
Advanced setup (chains, MPP, error codes, the hosted connector) is in [Advanced](#advanced).
|
|
@@ -66,7 +66,7 @@ $4 per-call cap and no session budget). Set `AGENT402_BUDGET` to cap the session
|
|
|
66
66
|
`payment.info` reports the caps, what's been spent, and what remains. With no wallet key and no credits key,
|
|
67
67
|
the server runs in proof-of-work mode (pure-CPU tools stay free). Use dedicated
|
|
68
68
|
low-value wallets for `AGENT_KEY` / `SOLANA_AGENT_KEY`, funded only with what
|
|
69
|
-
you intend to spend. Most tools cost $0.001
|
|
69
|
+
you intend to spend. Most tools cost $0.001 to $0.02. The routing tiers top out
|
|
70
70
|
at $3.30 (`route-execute-pro`); multi-tool skill packs run $0.003 to $0.101; and the
|
|
71
71
|
report products run $0.60 to $2.00 per report (domain-audit $0.60 up to the ticker pack at $2.00),
|
|
72
72
|
so the default per-call cap of $4 covers every tool; set `AGENT402_MAX_PER_CALL` lower for a
|
|
@@ -74,13 +74,13 @@ tighter ceiling.
|
|
|
74
74
|
|
|
75
75
|
## Advanced
|
|
76
76
|
|
|
77
|
-
**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):
|
|
77
|
+
**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.
|
|
78
78
|
|
|
79
79
|
**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`.
|
|
80
80
|
|
|
81
81
|
**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.
|
|
82
82
|
|
|
83
|
-
**Error codes.** `-32042` payment required (the challenges are in the error data). `-32043` a presented credential was refused.
|
|
83
|
+
**Error codes.** A first ask is a tool result, not an error (challenges in `_meta["org.paymentauth/payment-required"]`). `-32042` payment required on the tasks path (the challenges are in the error data). `-32043` a presented credential was refused.
|
|
84
84
|
|
|
85
85
|
## How it works
|
|
86
86
|
|
package/index.js
CHANGED
|
@@ -61,14 +61,24 @@ const BASE = (process.env.AGENT402_URL || "https://agent402.tools").replace(/\/$
|
|
|
61
61
|
// Catalog and seller requests (the 402 and the paid retry included) go through
|
|
62
62
|
// a dedicated dispatcher that refuses a TLS chain through a distrusted
|
|
63
63
|
// intermediate CA (networks.js).
|
|
64
|
-
|
|
64
|
+
// Every request names this package in its User-Agent (product token only), so
|
|
65
|
+
// the seller can tell which client a call came from. A caller's own
|
|
66
|
+
// User-Agent header, when one is set, is kept.
|
|
67
|
+
const plainFetch = distrustFetch();
|
|
68
|
+
const ownFetch = (input, init = {}) => {
|
|
69
|
+
// The payment wrapper passes a Request and no init: its headers are the base.
|
|
70
|
+
const h = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
|
|
71
|
+
if (!h.has("user-agent")) h.set("user-agent", `agent402-mcp/${VERSION}`);
|
|
72
|
+
return plainFetch(input, { ...init, headers: h });
|
|
73
|
+
};
|
|
65
74
|
const AGENT_KEY = process.env.AGENT_KEY || "";
|
|
66
75
|
// Solana secret key: base58 string (Phantom/solana-keygen export) or a JSON
|
|
67
76
|
// byte array. Either key alone enables paid calls; with both, the buyer can
|
|
68
77
|
// settle on whichever chain the seller offers (EVM accepts are tried first).
|
|
69
78
|
const SOLANA_AGENT_KEY = process.env.SOLANA_AGENT_KEY || "";
|
|
70
79
|
const HAS_WALLET = Boolean(AGENT_KEY || SOLANA_AGENT_KEY);
|
|
71
|
-
//
|
|
80
|
+
// A prepaid credits key (no wallet), already issued or bought where the
|
|
81
|
+
// service sells them (creditsSale() below reads which).
|
|
72
82
|
// Sent as Authorization: Bearer on every catalog call; the server debits the
|
|
73
83
|
// list price only on a successful (200) call and returns X-Credits-Balance.
|
|
74
84
|
const CREDITS_KEY = (process.env.AGENT402_CREDITS_KEY || "").trim();
|
|
@@ -395,7 +405,7 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
|
|
|
395
405
|
|
|
396
406
|
let res;
|
|
397
407
|
if (!HAS_WALLET && HAS_CREDITS) {
|
|
398
|
-
//
|
|
408
|
+
// Credits key: same budget guards as the wallet path, against the same
|
|
399
409
|
// number - the credits gate holds and debits what the 402 quotes for THIS
|
|
400
410
|
// body, not the route's list price.
|
|
401
411
|
const listUsd = parseFloat(String(tool.price).replace(/[^0-9.]/g, "")) || 0;
|
|
@@ -415,7 +425,11 @@ async function callEndpoint(tool, args = {}, { onProgress = null } = {}) {
|
|
|
415
425
|
if (res.ok) spentUsd += price;
|
|
416
426
|
if (res.status === 402) {
|
|
417
427
|
let body = {}; try { body = await res.clone().json(); } catch { /* plain */ }
|
|
418
|
-
|
|
428
|
+
// The refusal carries a topup link only while the service sells credits;
|
|
429
|
+
// otherwise its note says so and names where to pay per call instead.
|
|
430
|
+
const sale = creditsSale();
|
|
431
|
+
const next = body.topup ? `Top up at ${body.topup}.` : body.topupNote ? `${body.topupNote}${body.pay ? ` (${body.pay})` : ""}` : sale.buy ? `Top up at ${sale.buy}.` : `${sale.note[0].toUpperCase()}${sale.note.slice(1)}.`;
|
|
432
|
+
return { content: [{ type: "text", text: `Credits refused for "${tool.slug}": ${body.error || "payment required"}${body.balanceUsd != null ? ` (balance $${body.balanceUsd})` : ""}. ${next}` }], isError: true };
|
|
419
433
|
}
|
|
420
434
|
} else if (HAS_WALLET) {
|
|
421
435
|
// The signing guard (installed on every key-built client, getPayFetch)
|
|
@@ -662,6 +676,17 @@ server.setRequestHandler(GetPromptRequestSchema, async (req) => {
|
|
|
662
676
|
let curated = [];
|
|
663
677
|
let pricingInfo = null;
|
|
664
678
|
|
|
679
|
+
// Whether the service sells new credits is a switch on the server, read from
|
|
680
|
+
// its /api/pricing (credits.onSale); this package cannot see the switch on its
|
|
681
|
+
// own, so a buy link is shown only while the catalog read says they are sold,
|
|
682
|
+
// and a key already issued keeps working either way.
|
|
683
|
+
function creditsSale() {
|
|
684
|
+
const c = pricingInfo?.credits;
|
|
685
|
+
if (c?.onSale === true) return { onSale: true, buy: c.buy || `${BASE}/credits` };
|
|
686
|
+
if (c?.onSale === false) return { onSale: false, note: "new credits are not on sale; a key already issued keeps working" };
|
|
687
|
+
return { onSale: null, note: `whether new credits are sold is read from ${BASE}/api/pricing (credits.onSale); a key already issued keeps working` };
|
|
688
|
+
}
|
|
689
|
+
|
|
665
690
|
// A catalog that could not load at boot (a shed or unreachable service) is
|
|
666
691
|
// read again on the next tools/list or tools/call, at most once per
|
|
667
692
|
// CATALOG_RETRY_MS, so a session that started during a busy minute recovers
|
|
@@ -883,6 +908,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
883
908
|
try { solanaAddress = (await solanaSigner()).address; } catch { solanaAddress = "invalid SOLANA_AGENT_KEY"; }
|
|
884
909
|
}
|
|
885
910
|
const computePayable = [...catalog.values()].filter((t) => t.computePayable).length;
|
|
911
|
+
const sale = creditsSale();
|
|
886
912
|
return mcpJsonResult({
|
|
887
913
|
service: BASE,
|
|
888
914
|
mode: HAS_WALLET ? "usdc" : HAS_CREDITS ? "credits" : "proof-of-work",
|
|
@@ -894,7 +920,9 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
894
920
|
payableWithCompute: computePayable,
|
|
895
921
|
walletOnly: catalog.size - computePayable,
|
|
896
922
|
workflows: skillPacks.length,
|
|
897
|
-
credits: HAS_CREDITS
|
|
923
|
+
credits: HAS_CREDITS
|
|
924
|
+
? { configured: true, how: "a prepaid credits key (Authorization: Bearer a402_...) - every wallet-only tool except the wallet-identity-bound ones (memory, usage, receipts, attest, feedback) and the routes that buy from an outside seller pays from the balance, debited only on a successful call", balance: `${BASE}/api/credits/balance`, onSale: sale.onSale, ...(sale.buy ? { topup: sale.buy } : { note: sale.note }) }
|
|
925
|
+
: { configured: false, how: "a credits key, where sold or already issued, pays per successful call on Agent402's own services (AGENT402_CREDITS_KEY)", onSale: sale.onSale, ...(sale.buy ? { buy: sale.buy } : { note: sale.note }) },
|
|
898
926
|
spendControls: (HAS_WALLET || HAS_CREDITS)
|
|
899
927
|
? {
|
|
900
928
|
maxPerCallUsd: MAX_PER_CALL === Infinity ? "unlimited" : MAX_PER_CALL,
|
|
@@ -906,13 +934,13 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
906
934
|
note: HAS_WALLET
|
|
907
935
|
? "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."
|
|
908
936
|
: HAS_CREDITS
|
|
909
|
-
? "Every tool on Agent402's own services is available; each call is paid from the
|
|
937
|
+
? "Every tool on Agent402's own services is available; each call is paid from the 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."
|
|
910
938
|
: `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).`,
|
|
911
939
|
install: {
|
|
912
940
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
913
941
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
914
942
|
cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
|
|
915
|
-
npm: "npx -y agent402-mcp@0.13.
|
|
943
|
+
npm: "npx -y agent402-mcp@0.13.25",
|
|
916
944
|
maintainer: "Havok Holdings LLC",
|
|
917
945
|
},
|
|
918
946
|
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.`,
|
|
@@ -932,7 +960,7 @@ server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req, extra) =
|
|
|
932
960
|
install: {
|
|
933
961
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
934
962
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
935
|
-
npm: "npx -y agent402-mcp@0.13.
|
|
963
|
+
npm: "npx -y agent402-mcp@0.13.25",
|
|
936
964
|
maintainer: "Havok Holdings LLC",
|
|
937
965
|
},
|
|
938
966
|
tools: catalog.size,
|
package/networks.js
CHANGED
|
@@ -10,27 +10,23 @@
|
|
|
10
10
|
// USDG on Robinhood Chain unreachable no matter what the wallet holds.
|
|
11
11
|
import tls from "node:tls";
|
|
12
12
|
import { createHash, X509Certificate } from "node:crypto";
|
|
13
|
+
import { NETWORK_NAMES, networkIdsOf } from "./known-assets.js";
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
arbitrum: "eip155:42161",
|
|
18
|
-
"base-sepolia": "eip155:84532",
|
|
19
|
-
robinhood: "eip155:4663",
|
|
20
|
-
arc: "eip155:5042",
|
|
21
|
-
solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
|
|
22
|
-
"solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
|
|
23
|
-
};
|
|
15
|
+
/** Chain name -> its CAIP-2 id (the first id the known-asset table lists for
|
|
16
|
+
* that name), derived so a chain added there is named here too. */
|
|
17
|
+
export const NETWORK_CAIP2 = Object.freeze(Object.fromEntries(Object.entries(NETWORK_NAMES).map(([name, ids]) => [name, ids[0]])));
|
|
24
18
|
|
|
25
19
|
/** Parse "robinhood,base" / "eip155:4663" into an ordered CAIP-2 list.
|
|
26
|
-
*
|
|
27
|
-
*
|
|
20
|
+
* A chain name maps to every id the known-asset table lists for it (both
|
|
21
|
+
* Algorand spellings); unknown names pass through verbatim so raw CAIP-2
|
|
22
|
+
* ids (future chains) work without a package update. Returns [] when unset. */
|
|
28
23
|
export function parseNetworkPrefs(raw) {
|
|
29
|
-
|
|
24
|
+
const ids = String(raw || "")
|
|
30
25
|
.split(",")
|
|
31
26
|
.map((s) => s.trim().toLowerCase())
|
|
32
27
|
.filter(Boolean)
|
|
33
|
-
.
|
|
28
|
+
.flatMap((n) => networkIdsOf(n));
|
|
29
|
+
return [...new Set(ids)];
|
|
34
30
|
}
|
|
35
31
|
|
|
36
32
|
/** Filter a 402's accepts to the preferred networks, ordered by preference
|
package/output-schemas.js
CHANGED
|
@@ -492,7 +492,7 @@ export function mcpJsonResult(obj) {
|
|
|
492
492
|
* Hosted URL is parameterized; npm / Claude Code / Cursor / Smithery notes
|
|
493
493
|
* match docs/ecosystem-listings.md + wiki/MCP-Connector.md.
|
|
494
494
|
*/
|
|
495
|
-
export const AGENT402_MCP_VERSION = "0.13.
|
|
495
|
+
export const AGENT402_MCP_VERSION = "0.13.25";
|
|
496
496
|
|
|
497
497
|
/** A listed MCP tool description, at most `max` characters. Hosts truncate or
|
|
498
498
|
* skip long descriptions, so the listing keeps the first whole sentences; the
|
|
@@ -524,12 +524,12 @@ export function mcpInstallHints(baseUrl) {
|
|
|
524
524
|
mcpServers: {
|
|
525
525
|
agent402: {
|
|
526
526
|
command: "npx",
|
|
527
|
-
args: ["-y", "agent402-mcp@0.13.
|
|
527
|
+
args: ["-y", "agent402-mcp@0.13.25"],
|
|
528
528
|
env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
|
|
529
529
|
},
|
|
530
530
|
},
|
|
531
531
|
},
|
|
532
|
-
npm: "npx -y agent402-mcp@0.13.
|
|
532
|
+
npm: "npx -y agent402-mcp@0.13.25",
|
|
533
533
|
smithery: `Paste ${hosted} into the add-server form at https://smithery.ai/new. Submission is external; Agent402 does not auto-publish.`,
|
|
534
534
|
maintainer: "Havok Holdings LLC",
|
|
535
535
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent402-mcp",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.25",
|
|
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",
|
|
@@ -73,13 +73,13 @@
|
|
|
73
73
|
],
|
|
74
74
|
"license": "MIT",
|
|
75
75
|
"dependencies": {
|
|
76
|
-
"@modelcontextprotocol/sdk": "
|
|
77
|
-
"@solana/kit": "
|
|
76
|
+
"@modelcontextprotocol/sdk": "1.32.1",
|
|
77
|
+
"@solana/kit": "8.4.0",
|
|
78
78
|
"@x402/core": "2.28.0",
|
|
79
79
|
"@x402/evm": "2.28.0",
|
|
80
80
|
"@x402/fetch": "2.28.0",
|
|
81
81
|
"@x402/svm": "2.28.0",
|
|
82
|
-
"viem": "
|
|
82
|
+
"viem": "2.52.2"
|
|
83
83
|
},
|
|
84
84
|
"overrides": {
|
|
85
85
|
"qs": "6.16.1",
|