agent402-mcp 0.14.0 → 0.14.1
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 +8 -6
- package/index.d.ts +6 -3
- package/index.js +17 -7
- 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.
|
|
14
|
+
claude mcp add agent402 -s user -- npx -y agent402-mcp@0.14.1
|
|
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.
|
|
24
|
+
"args": ["-y", "agent402-mcp@0.14.1"],
|
|
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.
|
|
35
|
+
Claude Code with a wallet: `claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_PRIVATE_KEY -- npx -y agent402-mcp@0.14.1`
|
|
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.
|
|
@@ -103,7 +105,7 @@ its variable name, not its value.
|
|
|
103
105
|
## How it works
|
|
104
106
|
|
|
105
107
|
- 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`, `
|
|
108
|
+
- **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
109
|
- **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
110
|
- 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
111
|
- 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.)
|
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
|
@@ -765,8 +765,12 @@ function rankWorkflows(query, k = 2) {
|
|
|
765
765
|
// MCP wiring
|
|
766
766
|
// Initialize instructions mirror src/mcp-flagship.js mcpInitializeInstructions
|
|
767
767
|
// (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
|
-
|
|
768
|
+
// This server lists no demand.request, so its instructions do not name it;
|
|
769
|
+
// market.quote is named only while it is listed (the catalog lists
|
|
770
|
+
// stock-quote and it is first-class here), so the text is rebuilt after each
|
|
771
|
+
// catalog read (syncInstructions) and before the first initialize.
|
|
772
|
+
const instructionsFor = (stock) => mcpInitializeInstructions(BASE, { ...hostedConnectorWiresFor(BASE), demand: false, stock });
|
|
773
|
+
const INIT_INSTRUCTIONS = instructionsFor(false);
|
|
770
774
|
|
|
771
775
|
const server = new Server(
|
|
772
776
|
{
|
|
@@ -778,6 +782,10 @@ const server = new Server(
|
|
|
778
782
|
},
|
|
779
783
|
{ capabilities: { tools: {}, prompts: {} }, instructions: INIT_INSTRUCTIONS },
|
|
780
784
|
);
|
|
785
|
+
/** Point the initialize instructions at what tools/list lists now. */
|
|
786
|
+
function syncInstructions() {
|
|
787
|
+
server._instructions = instructionsFor(curated.some((t) => t.slug === "stock-quote"));
|
|
788
|
+
}
|
|
781
789
|
|
|
782
790
|
// Skill packs are exposed as MCP prompts, discoverable in slash menus on any
|
|
783
791
|
// MCP-aware client. The list is fetched once at boot in loadCatalog(); the
|
|
@@ -834,6 +842,7 @@ async function ensureCatalog() {
|
|
|
834
842
|
try {
|
|
835
843
|
pricingInfo = await loadCatalog();
|
|
836
844
|
curated = requested.map((slug) => catalog.get(slug)).filter(Boolean);
|
|
845
|
+
syncInstructions();
|
|
837
846
|
log(`catalog: ${catalog.size} tools from ${BASE} on a later read; ${curated.length} first-class`);
|
|
838
847
|
} catch (err) {
|
|
839
848
|
log(`Could not load the catalog from ${BASE}: ${err.message}: next read in ${CATALOG_RETRY_MS / 1000}s`);
|
|
@@ -906,7 +915,7 @@ server.setRequestHandler("tools/list", redacted(withCatalog(async () => {
|
|
|
906
915
|
title: "Run an Agent402 tool",
|
|
907
916
|
annotations: { title: "Run an Agent402 tool", ...CALL_PAID },
|
|
908
917
|
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,
|
|
918
|
+
"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
919
|
inputSchema: {
|
|
911
920
|
type: "object",
|
|
912
921
|
properties: {
|
|
@@ -1084,10 +1093,10 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
|
|
|
1084
1093
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
1085
1094
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
1086
1095
|
cursorHosted: { mcpServers: { agent402: { url: `${BASE}/mcp` } } },
|
|
1087
|
-
npm: "npx -y agent402-mcp@0.14.
|
|
1096
|
+
npm: "npx -y agent402-mcp@0.14.1",
|
|
1088
1097
|
maintainer: "Havok Holdings LLC",
|
|
1089
1098
|
},
|
|
1090
|
-
positioning: `Agent402 is
|
|
1099
|
+
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
1100
|
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
1101
|
});
|
|
1093
1102
|
}
|
|
@@ -1096,7 +1105,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
|
|
|
1096
1105
|
service: BASE,
|
|
1097
1106
|
connector: "stdio npm package (agent402-mcp)",
|
|
1098
1107
|
maintainer: "Havok Holdings LLC",
|
|
1099
|
-
positioning: `Agent402 is
|
|
1108
|
+
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
1109
|
startHere: {
|
|
1101
1110
|
firstJob: "Search the web and answer questions. Call web.search or web.answer directly, or catalog.find with your task.",
|
|
1102
1111
|
mode: HAS_WALLET ? "usdc" : HAS_CREDITS ? "credits" : "proof-of-work",
|
|
@@ -1104,7 +1113,7 @@ server.setRequestHandler("tools/call", redacted(withCatalog(async (req, extra) =
|
|
|
1104
1113
|
install: {
|
|
1105
1114
|
claudeCodeHosted: `claude mcp add --transport http agent402 ${BASE}/mcp`,
|
|
1106
1115
|
claudeCodeNpm: `claude mcp add agent402 -s user -- npx -y agent402-mcp@${AGENT402_MCP_VERSION}`,
|
|
1107
|
-
npm: "npx -y agent402-mcp@0.14.
|
|
1116
|
+
npm: "npx -y agent402-mcp@0.14.1",
|
|
1108
1117
|
maintainer: "Havok Holdings LLC",
|
|
1109
1118
|
},
|
|
1110
1119
|
tools: catalog.size,
|
|
@@ -1270,6 +1279,7 @@ try {
|
|
|
1270
1279
|
const requested = (process.env.AGENT402_TOOLS || DEFAULT_CURATED.join(","))
|
|
1271
1280
|
.split(",").map((s) => s.trim()).filter(Boolean);
|
|
1272
1281
|
curated = requested.map((slug) => catalog.get(slug)).filter(Boolean);
|
|
1282
|
+
syncInstructions();
|
|
1273
1283
|
log(`catalog: ${catalog.size} tools from ${BASE}; ${curated.length} first-class, rest via catalog.search/catalog.call`);
|
|
1274
1284
|
// A key is reported configured only once it parses: a key that does not
|
|
1275
1285
|
// 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.14.
|
|
497
|
+
export const AGENT402_MCP_VERSION = "0.14.1";
|
|
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.
|
|
529
|
+
args: ["-y", "agent402-mcp@0.14.1"],
|
|
530
530
|
env: { AGENT_KEY: "0xYOUR_PRIVATE_KEY" },
|
|
531
531
|
},
|
|
532
532
|
},
|
|
533
533
|
},
|
|
534
|
-
npm: "npx -y agent402-mcp@0.14.
|
|
534
|
+
npm: "npx -y agent402-mcp@0.14.1",
|
|
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.14.
|
|
3
|
+
"version": "0.14.1",
|
|
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"
|