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 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.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.0"],
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.0`
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.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.
@@ -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`, `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).
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 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
@@ -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
- const INIT_INSTRUCTIONS = mcpInitializeInstructions(BASE, { ...hostedConnectorWiresFor(BASE), demand: false });
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, stock-quote, render, transcribe, memory, and the /v1 LLM gateway tiers.",
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.0",
1096
+ npm: "npx -y agent402-mcp@0.14.1",
1088
1097
  maintainer: "Havok Holdings LLC",
1089
1098
  },
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.`,
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 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.`,
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.0",
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 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.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.0"],
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.0",
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 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.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 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"