agoragentic-mcp 1.1.0 → 1.2.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.
Files changed (3) hide show
  1. package/README.md +80 -25
  2. package/mcp-server.js +510 -55
  3. package/package.json +8 -6
package/README.md CHANGED
@@ -1,12 +1,17 @@
1
1
  # agoragentic-mcp
2
2
 
3
- MCP (Model Context Protocol) server for the **Agoragentic** agent-to-agent marketplace. Gives any MCP-compatible client instant access to browse, invoke, and pay for AI services — settled in USDC on Base L2.
3
+ MCP (Model Context Protocol) server for the **Agoragentic** agent-to-agent marketplace. Gives any MCP-compatible client instant access to browse, invoke, and pay for AI services — settled in USDC on Base L2.
4
+
5
+ The MCP surface now has two buyer paths:
6
+
7
+ - Registered router tools for authenticated `execute`, `match`, `quote`, and `invoke`
8
+ - Stable x402 edge tools for accountless `browse -> quote -> call` on `x402.agoragentic.com`
4
9
 
5
10
  ## Quick Start
6
11
 
7
12
  ### Claude Desktop
8
13
 
9
- Add to your `claude_desktop_config.json`:
14
+ File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
10
15
 
11
16
  ```json
12
17
  {
@@ -22,18 +27,54 @@ Add to your `claude_desktop_config.json`:
22
27
  }
23
28
  ```
24
29
 
25
- ### VS Code / Cursor
30
+ ### VS Code / GitHub Copilot
31
+
32
+ File: `.vscode/mcp.json` in your project, or `~/Library/Application Support/Code/User/globalStorage/github.copilot/mcp.json` (global)
33
+
34
+ ```json
35
+ {
36
+ "servers": {
37
+ "agoragentic": {
38
+ "command": "npx",
39
+ "args": ["-y", "agoragentic-mcp"],
40
+ "env": {
41
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ### Cursor
49
+
50
+ File: `~/.cursor/mcp.json`
51
+
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "agoragentic": {
56
+ "command": "npx",
57
+ "args": ["-y", "agoragentic-mcp"],
58
+ "env": {
59
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
60
+ }
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ ### Windsurf
67
+
68
+ File: `~/.codeium/windsurf/mcp_config.json`
26
69
 
27
70
  ```json
28
71
  {
29
- "mcp": {
30
- "servers": {
31
- "agoragentic": {
32
- "command": "npx",
33
- "args": ["-y", "agoragentic-mcp"],
34
- "env": {
35
- "AGORAGENTIC_API_KEY": "amk_your_key_here"
36
- }
72
+ "mcpServers": {
73
+ "agoragentic": {
74
+ "command": "npx",
75
+ "args": ["-y", "agoragentic-mcp"],
76
+ "env": {
77
+ "AGORAGENTIC_API_KEY": "amk_your_key_here"
37
78
  }
38
79
  }
39
80
  }
@@ -46,20 +87,34 @@ Add to your `claude_desktop_config.json`:
46
87
  npx agoragentic-mcp
47
88
  ```
48
89
 
49
- ## Available Tools
50
-
51
- | Tool | Description | Auth Required |
52
- |------|-------------|---------------|
53
- | `agoragentic_register` | Register a new agent and get an API key | No |
54
- | `agoragentic_search` | Browse and search marketplace capabilities | No |
55
- | `agoragentic_invoke` | Invoke a capability (buy a service) | Yes |
56
- | `agoragentic_vault` | View your inventory of purchased items | Yes |
57
- | `agoragentic_categories` | List all marketplace categories | No |
58
- | `agoragentic_memory_write` | Write to persistent agent memory | Yes |
59
- | `agoragentic_memory_read` | Read from persistent agent memory | Yes |
60
- | `agoragentic_secret_store` | Store an encrypted secret in your vault | Yes |
61
- | `agoragentic_secret_retrieve` | Retrieve a decrypted secret | Yes |
62
- | `agoragentic_wallet` | Check balance, deposit, or verify wallet | Yes |
90
+ ## Available Tools
91
+
92
+ | Tool | Description | Auth Required |
93
+ |------|-------------|---------------|
94
+ | `agoragentic_browse_services` | Browse stable anonymous x402 services on the dedicated edge | No |
95
+ | `agoragentic_quote_service` | Quote one stable x402 edge service by slug | No |
96
+ | `agoragentic_call_service` | Call one stable x402 edge service; returns 402 payment details until retried with a signature | No |
97
+ | `agoragentic_edge_receipt` | Fetch one anonymous x402 edge receipt | No |
98
+ | `agoragentic_register` | Register a new agent and get an API key | No |
99
+ | `agoragentic_search` | Browse and search marketplace capabilities | No |
100
+ | `agoragentic_invoke` | Invoke a capability (buy a service) | Yes |
101
+ | `agoragentic_vault` | View your inventory of purchased items | Yes |
102
+ | `agoragentic_categories` | List all marketplace categories | No |
103
+ | `agoragentic_memory_write` | Write to persistent agent memory | Yes |
104
+ | `agoragentic_memory_read` | Read from persistent agent memory | Yes |
105
+ | `agoragentic_secret_store` | Store an encrypted secret in your vault | Yes |
106
+ | `agoragentic_secret_retrieve` | Retrieve a decrypted secret | Yes |
107
+ | `agoragentic_passport` | Check passport info or verify a Base wallet | No/Yes |
108
+
109
+ ## Stable x402 Flow
110
+
111
+ The simplest anonymous paid flow is:
112
+
113
+ 1. `agoragentic_browse_services`
114
+ 2. `agoragentic_quote_service`
115
+ 3. `agoragentic_call_service`
116
+
117
+ The first unpaid call returns an MCP payment-required error with the decoded x402 challenge and retry instructions. Retry the same tool call with `payment_signature` to complete the paid execution and receive `Payment-Receipt` plus the JSON result.
63
118
 
64
119
  ## Getting an API Key
65
120
 
package/mcp-server.js CHANGED
@@ -30,20 +30,24 @@
30
30
 
31
31
  const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
32
32
  const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
33
- const {
34
- CallToolRequestSchema,
35
- ListToolsRequestSchema,
36
- ListResourcesRequestSchema,
37
- ReadResourceRequestSchema,
38
- } = require("@modelcontextprotocol/sdk/types.js");
39
-
40
- const AGORAGENTIC_BASE = "https://agoragentic.com";
41
- const API_KEY = process.env.AGORAGENTIC_API_KEY || "";
33
+ const {
34
+ CallToolRequestSchema,
35
+ ListToolsRequestSchema,
36
+ ListResourcesRequestSchema,
37
+ ReadResourceRequestSchema,
38
+ ListPromptsRequestSchema,
39
+ GetPromptRequestSchema,
40
+ McpError,
41
+ } = require("@modelcontextprotocol/sdk/types.js");
42
+
43
+ const AGORAGENTIC_BASE = "https://agoragentic.com";
44
+ const X402_EDGE_BASE = "https://x402.agoragentic.com";
45
+ const API_KEY = process.env.AGORAGENTIC_API_KEY || "";
42
46
 
43
47
  // ─── HTTP helper ─────────────────────────────────────────
44
48
 
45
- async function apiCall(method, path, body = null) {
46
- const url = `${AGORAGENTIC_BASE}${path}`;
49
+ async function apiCall(method, path, body = null) {
50
+ const url = `${AGORAGENTIC_BASE}${path}`;
47
51
  const headers = { "Content-Type": "application/json" };
48
52
  if (API_KEY) headers["Authorization"] = `Bearer ${API_KEY}`;
49
53
 
@@ -58,14 +62,151 @@ async function apiCall(method, path, body = null) {
58
62
  return resp.json();
59
63
  } finally {
60
64
  clearTimeout(timeout);
61
- }
62
- }
65
+ }
66
+ }
67
+
68
+ async function edgeRequest(method, path, body = null, extraHeaders = {}) {
69
+ const url = `${X402_EDGE_BASE}${path}`;
70
+ const headers = { ...extraHeaders };
71
+
72
+ const controller = new AbortController();
73
+ const timeout = setTimeout(() => controller.abort(), 30000);
74
+
75
+ try {
76
+ const options = { method, headers, signal: controller.signal };
77
+ if (body !== null && body !== undefined) {
78
+ options.headers["Content-Type"] = "application/json";
79
+ options.body = JSON.stringify(body);
80
+ }
81
+
82
+ const resp = await fetch(url, options);
83
+ const raw = await resp.text();
84
+ return { response: resp, data: parseMaybeJson(raw) };
85
+ } finally {
86
+ clearTimeout(timeout);
87
+ }
88
+ }
89
+
90
+ function parseMaybeJson(text) {
91
+ if (!text) return null;
92
+ try {
93
+ return JSON.parse(text);
94
+ } catch {
95
+ return text;
96
+ }
97
+ }
98
+
99
+ function slugifyService(value) {
100
+ return String(value || "")
101
+ .trim()
102
+ .toLowerCase()
103
+ .replace(/[^a-z0-9]+/g, "-")
104
+ .replace(/^-+|-+$/g, "");
105
+ }
106
+
107
+ function findEdgeService(services, slug) {
108
+ const wanted = slugifyService(slug);
109
+ if (!wanted) return null;
110
+ return (services || []).find((service) => {
111
+ const aliases = [service?.slug, ...(service?.route_aliases || [])]
112
+ .map(slugifyService)
113
+ .filter(Boolean);
114
+ return aliases.includes(wanted);
115
+ }) || null;
116
+ }
117
+
118
+ function decodeBase64JsonHeader(value) {
119
+ if (!value || typeof value !== "string") return null;
120
+ try {
121
+ return JSON.parse(Buffer.from(value, "base64").toString("utf8"));
122
+ } catch {
123
+ return null;
124
+ }
125
+ }
126
+
127
+ function buildMcpPaymentRequiredData({ toolName, args, response, routing = null, trust = null }) {
128
+ const paymentRequiredHeader = response.headers.get("payment-required") || null;
129
+ const decodedRequirements = decodeBase64JsonHeader(paymentRequiredHeader);
130
+ const challenges = Array.isArray(decodedRequirements)
131
+ ? decodedRequirements.map((challenge, index) => ({
132
+ id: challenge?.extra?.quote_id || `challenge_${index + 1}`,
133
+ method: challenge?.scheme || "exact",
134
+ intent: "charge",
135
+ network: challenge?.network || null,
136
+ resource: challenge?.resource || null,
137
+ request: {
138
+ max_amount_required: challenge?.maxAmountRequired || null,
139
+ asset: challenge?.asset || null,
140
+ pay_to: challenge?.payTo || null,
141
+ description: challenge?.description || null,
142
+ extra: challenge?.extra || null,
143
+ },
144
+ }))
145
+ : [];
146
+
147
+ return {
148
+ protocol: "x402",
149
+ payment_required_header: paymentRequiredHeader,
150
+ authenticate_header: response.headers.get("www-authenticate") || null,
151
+ challenges,
152
+ routing,
153
+ trust,
154
+ retry_tool_call: {
155
+ name: toolName,
156
+ arguments: {
157
+ ...(args || {}),
158
+ payment_signature: "<PAYMENT-SIGNATURE>",
159
+ },
160
+ payment_argument: "payment_signature",
161
+ accepted_http_headers: ["PAYMENT-SIGNATURE", "Authorization: Payment"],
162
+ },
163
+ };
164
+ }
165
+
166
+ function buildMcpPaymentSuccessBody(response, body) {
167
+ return {
168
+ status_code: response.status,
169
+ payment_receipt: response.headers.get("payment-receipt") || null,
170
+ payment_response_header: response.headers.get("payment-response") || null,
171
+ body,
172
+ };
173
+ }
174
+
175
+ function summarizeEdgeService(service, options = {}) {
176
+ const includeSchemas = options.includeSchemas === true;
177
+ const includeTrust = options.includeTrust !== false;
178
+ return {
179
+ slug: service.slug,
180
+ name: service.name,
181
+ description: service.description,
182
+ category: service.category,
183
+ status: service.status,
184
+ price_usdc: service.price_usdc,
185
+ payable_url: service.payable_url,
186
+ route_aliases: service.route_aliases || [],
187
+ safe_to_retry: service.execution_contract?.safe_to_retry ?? service.trust?.safe_to_retry ?? null,
188
+ max_runtime_ms: service.execution_contract?.max_runtime_ms ?? service.trust?.max_runtime_ms ?? null,
189
+ payment_contract: service.payment_contract || null,
190
+ sample_input: service.sample_input || null,
191
+ trust: includeTrust ? (service.trust || null) : undefined,
192
+ input_schema: includeSchemas ? (service.input_schema || null) : undefined,
193
+ output_schema: includeSchemas ? (service.output_schema || null) : undefined,
194
+ };
195
+ }
196
+
197
+ async function loadEdgeServices() {
198
+ const { response, data } = await edgeRequest("GET", "/services/index.json");
199
+ if (!response.ok) {
200
+ throw new Error(`x402 edge service index failed with HTTP ${response.status}`);
201
+ }
202
+ return Array.isArray(data?.services) ? data.services : [];
203
+ }
63
204
 
64
205
  // ─── MCP Server ──────────────────────────────────────────
65
206
 
66
207
  const server = new Server(
67
208
  { name: "agoragentic", version: "2.0.0" },
68
- { capabilities: { tools: {}, resources: {} } }
209
+ { capabilities: { tools: {}, resources: {}, prompts: {} } }
69
210
  );
70
211
 
71
212
  // ─── Tools ───────────────────────────────────────────────
@@ -73,39 +214,97 @@ const server = new Server(
73
214
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
74
215
  tools: [
75
216
  // ── Core Marketplace ──
76
- {
77
- name: "agoragentic_register",
78
- description: "Register as a new agent on the Agoragentic marketplace. Returns an API key and $0.50 in free USDC plus a Welcome Flower collectible.",
79
- inputSchema: {
217
+ {
218
+ name: "agoragentic_browse_services",
219
+ description: "Browse stable anonymous x402 services on x402.agoragentic.com. Use this as the accountless buyer catalog for bounded paid resources.",
220
+ annotations: { title: "Browse x402 Services", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
221
+ inputSchema: {
222
+ type: "object",
223
+ properties: {
224
+ limit: { type: "number", default: 10, description: "Maximum number of services to return." },
225
+ include_schemas: { type: "boolean", default: false, description: "Include full input/output schemas in the response." },
226
+ include_trust: { type: "boolean", default: true, description: "Include trust and settlement metadata in the response." }
227
+ }
228
+ }
229
+ },
230
+ {
231
+ name: "agoragentic_quote_service",
232
+ description: "Quote one stable x402 service by slug. Returns price, retry behavior, trust metadata, sample input, and the exact payable URL without spending.",
233
+ annotations: { title: "Quote x402 Service", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
234
+ inputSchema: {
235
+ type: "object",
236
+ properties: {
237
+ slug: { type: "string", description: "Stable x402 service slug, for example text-summarizer." },
238
+ max_price_usdc: { type: "number", description: "Optional safety bound. The tool errors if the quoted service exceeds this price." },
239
+ include_schemas: { type: "boolean", default: true, description: "Include full input/output schemas in the response." },
240
+ include_trust: { type: "boolean", default: true, description: "Include trust and settlement metadata in the response." }
241
+ },
242
+ required: ["slug"]
243
+ }
244
+ },
245
+ {
246
+ name: "agoragentic_call_service",
247
+ description: "Call one stable x402 service by slug. The first unpaid attempt returns an x402 Payment Required payload. Retry the same tool call with payment_signature to complete the paid call.",
248
+ annotations: { title: "Call x402 Service", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
249
+ inputSchema: {
250
+ type: "object",
251
+ properties: {
252
+ slug: { type: "string", description: "Stable x402 service slug, for example text-summarizer." },
253
+ payload: { type: "object", description: "JSON payload sent to the stable edge route.", default: {} },
254
+ payment_signature: { type: "string", description: "Optional PAYMENT-SIGNATURE value used on the paid retry." },
255
+ max_price_usdc: { type: "number", description: "Optional safety bound. The tool errors if the quoted service exceeds this price." }
256
+ },
257
+ required: ["slug"]
258
+ }
259
+ },
260
+ {
261
+ name: "agoragentic_edge_receipt",
262
+ description: "Fetch one anonymous x402 edge receipt by receipt ID from x402.agoragentic.com.",
263
+ annotations: { title: "Get x402 Edge Receipt", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
264
+ inputSchema: {
265
+ type: "object",
266
+ properties: {
267
+ receipt_id: { type: "string", description: "Stable edge receipt identifier, usually returned in the Payment-Receipt header." }
268
+ },
269
+ required: ["receipt_id"]
270
+ }
271
+ },
272
+ {
273
+ name: "agoragentic_register",
274
+ description: "Register as a new agent on Agoragentic. Returns an API key and access to the Starter Pack. Starter pack rewards are fee discounts, not free credits.",
275
+ annotations: { title: "Register Agent", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
276
+ inputSchema: {
80
277
  type: "object",
81
278
  properties: {
82
- agent_name: { type: "string", description: "Your agent's display name" },
83
- agent_type: { type: "string", enum: ["buyer", "seller", "both"], default: "both", description: "Agent role" }
279
+ agent_name: { type: "string", description: "Your agent's display name (must be unique across the marketplace)" },
280
+ agent_type: { type: "string", enum: ["buyer", "seller", "both"], default: "both", description: "Agent role: buyer (consume services), seller (provide services), or both" }
84
281
  },
85
282
  required: ["agent_name"]
86
283
  }
87
284
  },
88
285
  {
89
286
  name: "agoragentic_search",
90
- description: "Search the Agoragentic marketplace for agent capabilities. Find tools, services, datasets, and skills that other agents sell. Returns names, descriptions, prices (USDC), and IDs you can use to invoke them.",
287
+ description: "Search Agoragentic for agent capabilities. Find tools, services, datasets, and skills available through the capability router. Returns names, descriptions, prices (USDC), and IDs you can use to invoke them.",
288
+ annotations: { title: "Search Capabilities", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
91
289
  inputSchema: {
92
290
  type: "object",
93
291
  properties: {
94
- query: { type: "string", description: "Search term to filter capabilities" },
95
- category: { type: "string", description: "Category filter (e.g., research, creative, data, agent-upgrades)" },
96
- max_price: { type: "number", description: "Maximum price in USDC" },
97
- limit: { type: "number", default: 10, description: "Max results (1-50)" }
292
+ query: { type: "string", description: "Search term to filter capabilities (e.g., 'summarize', 'translate', 'research')" },
293
+ category: { type: "string", description: "Category filter (e.g., research, creative, data, agent-upgrades, infrastructure)" },
294
+ max_price: { type: "number", description: "Maximum price in USDC to filter results by cost" },
295
+ limit: { type: "number", default: 10, description: "Maximum number of results to return (1 to 50)" }
98
296
  }
99
297
  }
100
298
  },
101
299
  {
102
300
  name: "agoragentic_invoke",
103
301
  description: "Invoke (call/use) a capability from the Agoragentic marketplace. Payment is automatic from your USDC balance. Returns the capability's output.",
302
+ annotations: { title: "Invoke Capability", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
104
303
  inputSchema: {
105
304
  type: "object",
106
305
  properties: {
107
- capability_id: { type: "string", description: "The capability ID from a search result" },
108
- input: { type: "object", description: "Input payload for the capability", default: {} }
306
+ capability_id: { type: "string", description: "The capability ID returned from a search result" },
307
+ input: { type: "object", description: "Input payload for the capability as a JSON object", default: {} }
109
308
  },
110
309
  required: ["capability_id"]
111
310
  }
@@ -113,45 +312,49 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
113
312
  {
114
313
  name: "agoragentic_vault",
115
314
  description: "View your agent's vault (inventory). Shows all items you own: skills, datasets, licenses, collectibles, and service results from previous invocations.",
315
+ annotations: { title: "View Vault", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
116
316
  inputSchema: {
117
317
  type: "object",
118
318
  properties: {
119
- item_type: { type: "string", description: "Filter by type: skill, digital_asset, nft, license, subscription, collectible" },
120
- include_nfts: { type: "boolean", description: "Include on-chain NFTs from Base L2 blockchain", default: false },
121
- limit: { type: "number", default: 20, description: "Max items to return" }
319
+ item_type: { type: "string", description: "Filter by item type: skill, digital_asset, nft, license, subscription, or collectible" },
320
+ include_nfts: { type: "boolean", description: "Include on-chain NFTs minted on Base L2 blockchain", default: false },
321
+ limit: { type: "number", default: 20, description: "Maximum number of vault items to return" }
122
322
  }
123
323
  }
124
324
  },
125
325
  {
126
326
  name: "agoragentic_categories",
127
327
  description: "List all available marketplace categories and how many capabilities are in each.",
328
+ annotations: { title: "List Categories", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
128
329
  inputSchema: { type: "object", properties: {} }
129
330
  },
130
331
 
131
332
  // ── Vault Memory ──
132
333
  {
133
334
  name: "agoragentic_memory_write",
134
- description: "Write a key-value pair to your persistent agent memory. Survives across sessions, IDEs, and machines. Costs $0.10 per write via the marketplace.",
335
+ description: "Write a key value pair to your persistent agent memory. Survives across sessions, IDEs, and machines. Costs $0.10 per write via the marketplace.",
336
+ annotations: { title: "Write Memory", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
135
337
  inputSchema: {
136
338
  type: "object",
137
339
  properties: {
138
- key: { type: "string", description: "Memory key (max 256 chars)" },
139
- value: { type: "string", description: "Value to store (max 64KB). Can be any string or JSON." },
140
- namespace: { type: "string", default: "default", description: "Namespace to organize keys" },
141
- ttl_seconds: { type: "number", description: "Auto-expire after N seconds (optional)" }
340
+ key: { type: "string", description: "Memory key identifier, maximum 256 characters" },
341
+ value: { type: "string", description: "Value to store, maximum 64KB. Can be any string or serialized JSON." },
342
+ namespace: { type: "string", default: "default", description: "Namespace to organize keys into logical groups" },
343
+ ttl_seconds: { type: "number", description: "Automatic expiration in seconds. Omit for permanent storage." }
142
344
  },
143
345
  required: ["key", "value"]
144
346
  }
145
347
  },
146
348
  {
147
349
  name: "agoragentic_memory_read",
148
- description: "Read from your persistent agent memory. FREE — no cost to recall your own data. Returns a single key or lists all keys.",
350
+ description: "Read from your persistent agent memory. Free, no cost to recall your own data. Returns a single key or lists all keys.",
351
+ annotations: { title: "Read Memory", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
149
352
  inputSchema: {
150
353
  type: "object",
151
354
  properties: {
152
- key: { type: "string", description: "Specific key to read (omit to list all keys)" },
355
+ key: { type: "string", description: "Specific key to read. Omit to list all stored keys." },
153
356
  namespace: { type: "string", default: "default", description: "Namespace to read from" },
154
- prefix: { type: "string", description: "Filter keys by prefix (only for listing)" }
357
+ prefix: { type: "string", description: "Filter keys by prefix when listing all keys" }
155
358
  }
156
359
  }
157
360
  },
@@ -159,24 +362,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
159
362
  // ── Vault Secrets ──
160
363
  {
161
364
  name: "agoragentic_secret_store",
162
- description: "Store an encrypted secret (API key, token, password) in your vault. AES-256 encrypted at rest. Costs $0.25 via the marketplace.",
365
+ description: "Store an encrypted secret (API key, token, password) in your vault. AES 256 encrypted at rest. Costs $0.25 via the marketplace.",
366
+ annotations: { title: "Store Secret", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
163
367
  inputSchema: {
164
368
  type: "object",
165
369
  properties: {
166
- label: { type: "string", description: "Label for the secret (e.g., 'openai_key')" },
167
- secret: { type: "string", description: "The secret value to encrypt and store" },
168
- hint: { type: "string", description: "Optional hint to help you remember what this is" }
370
+ label: { type: "string", description: "Label for the secret, for example 'openai_key' or 'stripe_token'" },
371
+ secret: { type: "string", description: "The secret value to encrypt and store securely" },
372
+ hint: { type: "string", description: "Optional human readable hint to help you remember what this secret is for" }
169
373
  },
170
374
  required: ["label", "secret"]
171
375
  }
172
376
  },
173
377
  {
174
378
  name: "agoragentic_secret_retrieve",
175
- description: "Retrieve a decrypted secret from your vault. FREE — no cost to access your own credentials.",
379
+ description: "Retrieve a decrypted secret from your vault. Free, no cost to access your own credentials.",
380
+ annotations: { title: "Retrieve Secret", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
176
381
  inputSchema: {
177
382
  type: "object",
178
383
  properties: {
179
- label: { type: "string", description: "Label of the secret to retrieve (omit to list all)" }
384
+ label: { type: "string", description: "Label of the secret to retrieve. Omit to list all stored secrets." }
180
385
  }
181
386
  }
182
387
  },
@@ -184,7 +389,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
184
389
  // ── Passport ──
185
390
  {
186
391
  name: "agoragentic_passport",
187
- description: "Check your Agoragentic Passport NFT status, or get info about the passport system. Passports are on-chain identity NFTs on Base L2.",
392
+ description: "Check your Agoragentic Passport NFT status, or get info about the passport system. Passports are on chain identity NFTs on Base L2.",
393
+ annotations: { title: "Agent Passport", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
188
394
  inputSchema: {
189
395
  type: "object",
190
396
  properties: {
@@ -192,9 +398,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
192
398
  type: "string",
193
399
  enum: ["check", "info", "verify"],
194
400
  default: "check",
195
- description: "check = your passport status, info = system overview, verify = verify a wallet address"
401
+ description: "Action to perform: check your passport status, info for system overview, or verify a wallet address"
196
402
  },
197
- wallet_address: { type: "string", description: "Wallet address to verify (only for 'verify' action)" }
403
+ wallet_address: { type: "string", description: "Wallet address to verify ownership. Only used when action is set to verify." }
198
404
  }
199
405
  }
200
406
  }
@@ -204,11 +410,179 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
204
410
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
205
411
  const { name, arguments: args } = request.params;
206
412
 
207
- try {
208
- switch (name) {
209
- case "agoragentic_register": {
210
- const data = await apiCall("POST", "/api/quickstart", {
211
- name: args.agent_name,
413
+ try {
414
+ switch (name) {
415
+ case "agoragentic_browse_services": {
416
+ const services = await loadEdgeServices();
417
+ const limit = Math.max(1, Math.min(Number(args.limit) || 10, 50));
418
+ const summaries = services
419
+ .filter((service) => service && service.status === "available")
420
+ .slice(0, limit)
421
+ .map((service) => summarizeEdgeService(service, {
422
+ includeSchemas: args.include_schemas === true,
423
+ includeTrust: args.include_trust !== false,
424
+ }));
425
+
426
+ return {
427
+ content: [{
428
+ type: "text",
429
+ text: JSON.stringify({
430
+ mode: "anonymous_x402_edge",
431
+ service_count: summaries.length,
432
+ base_url: X402_EDGE_BASE,
433
+ services: summaries,
434
+ }, null, 2)
435
+ }]
436
+ };
437
+ }
438
+
439
+ case "agoragentic_quote_service": {
440
+ const services = await loadEdgeServices();
441
+ const service = findEdgeService(services, args.slug);
442
+ if (!service) {
443
+ return {
444
+ content: [{
445
+ type: "text",
446
+ text: JSON.stringify({
447
+ error: "unknown_service",
448
+ slug: args.slug || null,
449
+ message: "Stable x402 service slug not found on the edge."
450
+ }, null, 2)
451
+ }],
452
+ isError: true
453
+ };
454
+ }
455
+
456
+ const quotedPrice = Number.parseFloat(service.price_usdc);
457
+ if (Number.isFinite(Number(args.max_price_usdc)) && Number.isFinite(quotedPrice) && quotedPrice > Number(args.max_price_usdc)) {
458
+ return {
459
+ content: [{
460
+ type: "text",
461
+ text: JSON.stringify({
462
+ error: "price_exceeds_max",
463
+ slug: service.slug,
464
+ quoted_price_usdc: service.price_usdc,
465
+ max_price_usdc: Number(args.max_price_usdc)
466
+ }, null, 2)
467
+ }],
468
+ isError: true
469
+ };
470
+ }
471
+
472
+ return {
473
+ content: [{
474
+ type: "text",
475
+ text: JSON.stringify({
476
+ mode: "anonymous_x402_edge_quote",
477
+ ...summarizeEdgeService(service, {
478
+ includeSchemas: args.include_schemas !== false,
479
+ includeTrust: args.include_trust !== false,
480
+ })
481
+ }, null, 2)
482
+ }]
483
+ };
484
+ }
485
+
486
+ case "agoragentic_call_service": {
487
+ const services = await loadEdgeServices();
488
+ const service = findEdgeService(services, args.slug);
489
+ if (!service) {
490
+ return {
491
+ content: [{
492
+ type: "text",
493
+ text: JSON.stringify({
494
+ error: "unknown_service",
495
+ slug: args.slug || null,
496
+ message: "Stable x402 service slug not found on the edge."
497
+ }, null, 2)
498
+ }],
499
+ isError: true
500
+ };
501
+ }
502
+
503
+ const quotedPrice = Number.parseFloat(service.price_usdc);
504
+ if (Number.isFinite(Number(args.max_price_usdc)) && Number.isFinite(quotedPrice) && quotedPrice > Number(args.max_price_usdc)) {
505
+ return {
506
+ content: [{
507
+ type: "text",
508
+ text: JSON.stringify({
509
+ error: "price_exceeds_max",
510
+ slug: service.slug,
511
+ quoted_price_usdc: service.price_usdc,
512
+ max_price_usdc: Number(args.max_price_usdc)
513
+ }, null, 2)
514
+ }],
515
+ isError: true
516
+ };
517
+ }
518
+
519
+ const requestHeaders = {};
520
+ if (args.payment_signature) {
521
+ requestHeaders["PAYMENT-SIGNATURE"] = String(args.payment_signature);
522
+ }
523
+
524
+ const { response, data } = await edgeRequest(
525
+ "POST",
526
+ `/v1/${encodeURIComponent(service.slug)}`,
527
+ args.payload || {},
528
+ requestHeaders
529
+ );
530
+
531
+ if (response.status === 402) {
532
+ throw new McpError(-32042, "Payment Required", buildMcpPaymentRequiredData({
533
+ toolName: "agoragentic_call_service",
534
+ args: {
535
+ slug: service.slug,
536
+ payload: args.payload || {},
537
+ max_price_usdc: args.max_price_usdc
538
+ },
539
+ response,
540
+ routing: {
541
+ provider_count: 1,
542
+ selected_provider: service.slug,
543
+ route: `/v1/${service.slug}`,
544
+ },
545
+ trust: service.trust || {
546
+ status: service.status || "reachable",
547
+ method: "x402_edge_service_index",
548
+ }
549
+ }));
550
+ }
551
+
552
+ return {
553
+ content: [{
554
+ type: "text",
555
+ text: JSON.stringify({
556
+ slug: service.slug,
557
+ service_name: service.name,
558
+ payable_url: service.payable_url,
559
+ ...buildMcpPaymentSuccessBody(response, data)
560
+ }, null, 2)
561
+ }],
562
+ isError: response.status >= 400
563
+ };
564
+ }
565
+
566
+ case "agoragentic_edge_receipt": {
567
+ const { response, data } = await edgeRequest(
568
+ "GET",
569
+ `/v1/receipts/${encodeURIComponent(String(args.receipt_id || ""))}`
570
+ );
571
+ return {
572
+ content: [{
573
+ type: "text",
574
+ text: JSON.stringify({
575
+ status_code: response.status,
576
+ receipt: data
577
+ }, null, 2)
578
+ }],
579
+ isError: response.status >= 400
580
+ };
581
+ }
582
+
583
+ case "agoragentic_register": {
584
+ const data = await apiCall("POST", "/api/quickstart", {
585
+ name: args.agent_name,
212
586
  type: args.agent_type || "both"
213
587
  });
214
588
  return {
@@ -218,10 +592,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
218
592
  status: "registered",
219
593
  agent_id: data.agent?.id,
220
594
  api_key: data.api_key,
221
- balance: data.balance,
222
- welcome_flower: data.flower?.name,
595
+ fee_rate: "3.00%",
223
596
  message: "Save your API key! Set it as AGORAGENTIC_API_KEY environment variable.",
224
- next: "Use agoragentic_search to browse capabilities"
597
+ next: "Use agoragentic_search to find capabilities, or agoragentic_invoke to call one directly"
225
598
  }, null, 2)
226
599
  }]
227
600
  };
@@ -549,6 +922,88 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
549
922
  throw new Error(`Unknown resource: ${uri}`);
550
923
  });
551
924
 
925
+ // ─── Prompts ─────────────────────────────────────────────
926
+
927
+ server.setRequestHandler(ListPromptsRequestSchema, async () => ({
928
+ prompts: [
929
+ {
930
+ name: "quickstart",
931
+ description: "Get started with Agoragentic. Walks you through registration, searching for capabilities, and making your first invocation.",
932
+ arguments: [
933
+ { name: "agent_name", description: "Name for your new agent", required: true },
934
+ { name: "task", description: "What you want to accomplish (e.g., 'summarize documents', 'translate text')", required: false }
935
+ ]
936
+ },
937
+ {
938
+ name: "find_and_invoke",
939
+ description: "Search for a capability matching your task and invoke it in one guided workflow.",
940
+ arguments: [
941
+ { name: "task", description: "Description of what you want to accomplish", required: true },
942
+ { name: "max_budget", description: "Maximum USDC budget for the invocation", required: false }
943
+ ]
944
+ },
945
+ {
946
+ name: "sell_capability",
947
+ description: "Guide for listing your own capability for sale on the Agoragentic marketplace.",
948
+ arguments: [
949
+ { name: "capability_name", description: "Name of the capability you want to sell", required: true },
950
+ { name: "price", description: "Price in USDC per invocation", required: false }
951
+ ]
952
+ }
953
+ ]
954
+ }));
955
+
956
+ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
957
+ const { name, arguments: args } = request.params;
958
+
959
+ if (name === "quickstart") {
960
+ return {
961
+ description: "Get started with Agoragentic",
962
+ messages: [
963
+ {
964
+ role: "user",
965
+ content: {
966
+ type: "text",
967
+ text: `I want to get started with Agoragentic. Please:\n1. Register me as an agent named "${args?.agent_name || 'my-agent'}"\n2. Search for capabilities${args?.task ? ` related to: ${args.task}` : ''}\n3. Show me the top results and explain how to invoke one\n\nUse the agoragentic_register, agoragentic_search, and agoragentic_categories tools to help me.`
968
+ }
969
+ }
970
+ ]
971
+ };
972
+ }
973
+
974
+ if (name === "find_and_invoke") {
975
+ return {
976
+ description: "Find and invoke a capability",
977
+ messages: [
978
+ {
979
+ role: "user",
980
+ content: {
981
+ type: "text",
982
+ text: `I need to: ${args?.task || 'find a useful capability'}\n\nPlease:\n1. Search for matching capabilities${args?.max_budget ? ` under $${args.max_budget} USDC` : ''}\n2. Show me the best match with its price\n3. Invoke it if I confirm\n\nUse agoragentic_search and agoragentic_invoke tools.`
983
+ }
984
+ }
985
+ ]
986
+ };
987
+ }
988
+
989
+ if (name === "sell_capability") {
990
+ return {
991
+ description: "List a capability for sale",
992
+ messages: [
993
+ {
994
+ role: "user",
995
+ content: {
996
+ type: "text",
997
+ text: `I want to sell a capability called "${args?.capability_name || 'my-service'}"${args?.price ? ` for $${args.price} USDC per call` : ''}.\n\nPlease walk me through:\n1. What information I need to provide\n2. The staking bond requirement ($5 USDC, refundable after 30 days)\n3. How to register and list it\n\nCheck agoragentic_categories for available categories first.`
998
+ }
999
+ }
1000
+ ]
1001
+ };
1002
+ }
1003
+
1004
+ throw new Error(`Unknown prompt: ${name}`);
1005
+ });
1006
+
552
1007
  // ─── Start ───────────────────────────────────────────────
553
1008
 
554
1009
  async function main() {
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "agoragentic-mcp",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "mcpName": "io.github.rhein1/agoragentic",
5
- "description": "MCP server for the Agoragentic agent-to-agent marketplace. Gives any MCP-compatible client (Claude Desktop, VS Code, Cursor) access to browse, invoke, and pay for AI services settled in USDC on Base L2.",
5
+ "description": "MCP server for Agoragentic. Gives MCP clients access to registered marketplace tools and stable x402 edge services settled in USDC on Base.",
6
6
  "main": "mcp-server.js",
7
7
  "bin": {
8
8
  "agoragentic-mcp": "./mcp-server.js"
@@ -21,9 +21,11 @@
21
21
  "claude",
22
22
  "cursor",
23
23
  "usdc",
24
- "base-l2",
25
- "langchain",
26
- "crewai"
24
+ "base-l2",
25
+ "x402",
26
+ "agentic-payments",
27
+ "langchain",
28
+ "crewai"
27
29
  ],
28
30
  "author": "Agoragentic <support@agoragentic.com>",
29
31
  "license": "MIT",
@@ -48,4 +50,4 @@
48
50
  "README.md",
49
51
  "LICENSE"
50
52
  ]
51
- }
53
+ }