agent402-mcp 0.14.1 → 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 +9 -5
- package/index.js +86 -12
- package/output-schemas.js +3 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ Pick one setup. Both run locally through `npx`.
|
|
|
11
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.
|
|
12
12
|
|
|
13
13
|
```
|
|
14
|
-
claude mcp add agent402 -s user -- npx -y agent402-mcp@0.
|
|
14
|
+
claude mcp add agent402 -s user -- npx -y agent402-mcp@0.15.0
|
|
15
15
|
```
|
|
16
16
|
|
|
17
17
|
**2. Paid, with a wallet.** Paid tools are settled in USDC on each call.
|
|
@@ -21,7 +21,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.1
|
|
|
21
21
|
"mcpServers": {
|
|
22
22
|
"agent402": {
|
|
23
23
|
"command": "npx",
|
|
24
|
-
"args": ["-y", "agent402-mcp@0.
|
|
24
|
+
"args": ["-y", "agent402-mcp@0.15.0"],
|
|
25
25
|
"env": { "AGENT_KEY": "0xYOUR_PRIVATE_KEY" }
|
|
26
26
|
}
|
|
27
27
|
}
|
|
@@ -32,7 +32,7 @@ claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.1
|
|
|
32
32
|
|
|
33
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`.
|
|
34
34
|
|
|
35
|
-
Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@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`
|
|
36
36
|
(use a new wallet holding only a few dollars of USDC; never your main wallet).
|
|
37
37
|
|
|
38
38
|
Advanced setup (chains, MPP, error codes, the hosted connector) is in [Advanced](#advanced).
|
|
@@ -83,7 +83,10 @@ seller that kept the authorization could still redeem it, so it counts against
|
|
|
83
83
|
(`https://agent402.tools`, matched by exact origin), an error status is never
|
|
84
84
|
settled, so a hold for one ends at the authorization's `validBefore` plus 10
|
|
85
85
|
minutes (15 minutes after the answer when no `validBefore` is readable). A held
|
|
86
|
-
amount whose authorization expires unused is released, never charged.
|
|
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
|
|
87
90
|
option asking to stay valid for more than a day is refused before anything is
|
|
88
91
|
signed, so no signed authorization outlives a day.
|
|
89
92
|
|
|
@@ -96,7 +99,7 @@ its variable name, not its value.
|
|
|
96
99
|
|
|
97
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.
|
|
98
101
|
|
|
99
|
-
**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.
|
|
100
103
|
|
|
101
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.
|
|
102
105
|
|
|
@@ -125,6 +128,7 @@ its variable name, not its value.
|
|
|
125
128
|
| --- | --- | --- |
|
|
126
129
|
| ≤ $0.005 | $0.01 | `POST /api/route/execute` |
|
|
127
130
|
| ≤ $0.04 | $0.05 | `POST /api/route/execute-plus` |
|
|
131
|
+
| ≤ $0.10 | $0.12 | `POST /api/route/execute-mid` |
|
|
128
132
|
| ≤ $0.50 | $0.55 | `POST /api/route/execute-max` |
|
|
129
133
|
|
|
130
134
|
A tool priced above the tier's ceiling returns a self-correcting 409 naming its direct route.
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
@@ -977,7 +1046,7 @@ server.setRequestHandler("tools/list", redacted(withCatalog(async () => {
|
|
|
977
1046
|
properties: {
|
|
978
1047
|
task: { type: "string", description: "Plain-language task, e.g. 'crypto news headlines' or 'sentiment of a tweet'. Resolved to a proven external seller." },
|
|
979
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." },
|
|
980
|
-
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)." },
|
|
981
1050
|
},
|
|
982
1051
|
required: ["task"],
|
|
983
1052
|
},
|
|
@@ -1093,7 +1162,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
|
|
|
1093
1162
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
1094
1163
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
1095
1164
|
cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
|
|
1096
|
-
npm: "npx -y agent402-mcp@0.
|
|
1165
|
+
npm: "npx -y agent402-mcp@0.15.0",
|
|
1097
1166
|
maintainer: "Havok Holdings LLC",
|
|
1098
1167
|
},
|
|
1099
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.`,
|
|
@@ -1113,7 +1182,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
|
|
|
1113
1182
|
install: {
|
|
1114
1183
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
1115
1184
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
1116
|
-
npm: "npx -y agent402-mcp@0.
|
|
1185
|
+
npm: "npx -y agent402-mcp@0.15.0",
|
|
1117
1186
|
maintainer: "Havok Holdings LLC",
|
|
1118
1187
|
},
|
|
1119
1188
|
tools: catalog.size,
|
|
@@ -1218,12 +1287,17 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
|
|
|
1218
1287
|
if (!task) return { content: [{ type: "text", text: "router.execute requires a 'task' (plain-language description of what you need)." }], isError: true };
|
|
1219
1288
|
const maxUsd = Number(args.maxUsd) > 0 ? Number(args.maxUsd) : 0.005;
|
|
1220
1289
|
// Pick the CHEAPEST tier whose underlying cap covers maxUsd. The ladder
|
|
1221
|
-
//
|
|
1222
|
-
//
|
|
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).
|
|
1223
1292
|
// Keep this ordered cheapest-first so a new rung is a one-line insert.
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
: "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";
|
|
1227
1301
|
const tool = catalog.get(slug);
|
|
1228
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 };
|
|
1229
1303
|
// Body matches the route-execute input schema; include:"external" is what
|
package/output-schemas.js
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
534
|
+
npm: "npx -y agent402-mcp@0.15.0",
|
|
535
535
|
maintainer: "Havok Holdings LLC",
|
|
536
536
|
};
|
|
537
537
|
}
|
package/package.json
CHANGED