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 +14 -8
- package/index.d.ts +6 -3
- package/index.js +101 -17
- package/output-schemas.js +8 -7
- package/package.json +2 -2
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
|
|
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
|
+

|
|
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
|
+
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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`, `
|
|
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
|
|
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"
|
|
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
|
-
|
|
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.
|
|
@@ -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
|
-
|
|
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,
|
|
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.
|
|
1165
|
+
npm: "npx -y agent402-mcp@0.15.0",
|
|
1088
1166
|
maintainer: "Havok Holdings LLC",
|
|
1089
1167
|
},
|
|
1090
|
-
positioning: `Agent402 is
|
|
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
|
|
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.
|
|
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
|
-
//
|
|
1213
|
-
//
|
|
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
|
-
|
|
1216
|
-
|
|
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
|
|
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.
|
|
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
|
}
|
|
@@ -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
|
|
563
|
-
|
|
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.
|
|
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
|
|
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"
|