x402engine-mcp 1.0.5 → 1.0.6

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 (4) hide show
  1. package/README.md +87 -86
  2. package/dist/index.js +1 -1
  3. package/package.json +14 -3
  4. package/server.json +20 -4
package/README.md CHANGED
@@ -1,28 +1,25 @@
1
1
  # x402engine-mcp
2
2
 
3
- MCP server for [x402 Engine](https://x402-gateway-production.up.railway.app) — exposing a curated MCP surface over the live x402 gateway.
3
+ curated MCP server for [x402engine](https://x402engine.app), built for agents that want to discover and call paid tools over HTTP 402.
4
4
 
5
- canonical factual source for cross-channel x402engine claims:
5
+ the core story is simple: software pays software, per call, with stablecoins. no api keys. no accounts. no subscription setup in the request path.
6
6
 
7
- - `~/x402-gateway/config/x402engine-truth.json`
8
- - generated from `~/x402-gateway/config/services.json`, `~/x402-gateway/manifest/agent-manifest.v1.json`, and this package's `src/index.ts`
7
+ ## why agents use this
9
8
 
10
- current code reality from that truth layer:
9
+ - curated MCP surface over the live x402engine gateway
10
+ - machine readable discovery via `discover_services`
11
+ - payment rails on Base, MegaETH, and Solana
12
+ - useful for agents that want to buy compute, crypto data, wallet analytics, IPFS, and travel search only when needed
11
13
 
12
- - gateway catalog: 72 paid services
13
- - gateway llm routes: 38
14
- - mcp tool surface: 22 tools
15
- - 18 paid MCP tools backed by live gateway routes
16
- - mcp tools pointing at routes not present in the checked in gateway catalog: 2 (`search_locations`, `search_cheapest_dates`)
17
- - payment rails: Base, Solana, MegaETH
18
- - current mcp README scope: document the tools actually implemented in `src/index.ts`
19
- - the `x402engine://services` resource now derives its catalog from the live gateway discovery endpoints instead of a hand-maintained static list
14
+ important scope note:
20
15
 
21
- ## Quick Start
16
+ - the live gateway exposes a larger catalog than this MCP package
17
+ - this package is intentionally a curated subset
18
+ - for full gateway discovery, use `discover_services` or read `https://x402-gateway-production.up.railway.app/.well-known/x402.json`
22
19
 
23
- ### Claude Desktop
20
+ ## quick start
24
21
 
25
- Add to your `claude_desktop_config.json`:
22
+ ### claude desktop
26
23
 
27
24
  ```json
28
25
  {
@@ -38,77 +35,82 @@ Add to your `claude_desktop_config.json`:
38
35
  }
39
36
  ```
40
37
 
41
- ### Claude Code
38
+ ### claude code
42
39
 
43
40
  ```bash
44
41
  claude mcp add x402engine -- npx -y x402engine-mcp
45
42
  ```
46
43
 
47
- ## Implemented MCP tools
44
+ ## machine readable discovery surfaces
48
45
 
49
- ### Discovery and health
50
- | Tool | Price | Description |
46
+ - gateway discovery: `https://x402-gateway-production.up.railway.app/.well-known/x402.json`
47
+ - agent card: `https://x402-gateway-production.up.railway.app/.well-known/agent.json`
48
+ - endpoint manifest: `https://x402-gateway-production.up.railway.app/.well-known/agent-manifest.v1.json`
49
+ - manifest integrity: `https://x402-gateway-production.up.railway.app/.well-known/agent-manifest-integrity.v1.json`
50
+ - services api: `https://x402-gateway-production.up.railway.app/api/services`
51
+ - this package metadata: [`server.json`](./server.json)
52
+
53
+ ## implemented MCP tools
54
+
55
+ ### discovery and health
56
+ | tool | price | description |
51
57
  |------|-------|-------------|
52
- | `discover_services` | Free | Fetch live x402 discovery metadata from `/.well-known/x402.json` |
53
- | `service_health` | Free | Fetch live per service health metrics from `/api/health/services` |
58
+ | `discover_services` | free | fetch live x402 discovery metadata from `/.well-known/x402.json` |
59
+ | `service_health` | free | fetch live per-service health metrics from `/api/health/services` |
54
60
 
55
- ### Image generation
56
- | Tool | Price | Description |
61
+ ### image generation
62
+ | tool | price | description |
57
63
  |------|-------|-------------|
58
- | `generate_image` | $0.015 to $0.12 | Image generation across fast, quality, and text tiers |
64
+ | `generate_image` | $0.015 to $0.12 | image generation across fast, quality, and text tiers |
59
65
 
60
- ### Code execution
61
- | Tool | Price | Description |
66
+ ### code execution
67
+ | tool | price | description |
62
68
  |------|-------|-------------|
63
- | `execute_code` | $0.005 | Sandboxed code execution |
69
+ | `execute_code` | $0.005 | sandboxed code execution |
64
70
 
65
- ### Audio
66
- | Tool | Price | Description |
71
+ ### audio
72
+ | tool | price | description |
67
73
  |------|-------|-------------|
68
- | `transcribe_audio` | $0.10 | Audio transcription via Deepgram |
74
+ | `transcribe_audio` | $0.10 | audio transcription via Deepgram |
69
75
 
70
- ### Crypto and market data
71
- | Tool | Price | Description |
76
+ ### crypto and market data
77
+ | tool | price | description |
72
78
  |------|-------|-------------|
73
- | `get_crypto_price` | $0.001 | Current crypto prices |
74
- | `get_crypto_markets` | $0.002 | Market rankings and market data |
75
- | `get_crypto_history` | $0.003 | Historical price data |
76
- | `get_trending_crypto` | $0.001 | Trending coins |
77
- | `search_crypto` | $0.001 | Search by name or symbol |
78
- | `get_crypto_categories` | $0.001 | List CoinGecko category IDs for sector discovery |
79
-
80
- ### Wallet and token data
81
- | Tool | Price | Description |
79
+ | `get_crypto_price` | $0.001 | current crypto prices |
80
+ | `get_crypto_markets` | $0.002 | market rankings and market data |
81
+ | `get_crypto_history` | $0.003 | historical price data |
82
+ | `get_trending_crypto` | $0.001 | trending coins |
83
+ | `search_crypto` | $0.001 | search by name or symbol |
84
+ | `get_crypto_categories` | $0.001 | CoinGecko category ids for sector discovery |
85
+
86
+ ### wallet and token data
87
+ | tool | price | description |
82
88
  |------|-------|-------------|
83
- | `get_wallet_balances` | $0.005 | Multichain wallet balances |
84
- | `get_wallet_transactions` | $0.005 | Wallet transaction history |
85
- | `get_wallet_pnl` | $0.01 | Wallet profit and loss analysis |
86
- | `get_token_prices` | $0.005 | DEX derived token prices |
87
- | `get_token_metadata` | $0.002 | Token metadata |
89
+ | `get_wallet_balances` | $0.005 | multichain wallet balances |
90
+ | `get_wallet_transactions` | $0.005 | wallet transaction history |
91
+ | `get_wallet_pnl` | $0.01 | wallet profit and loss analysis |
92
+ | `get_token_prices` | $0.005 | dex derived token prices |
93
+ | `get_token_metadata` | $0.002 | token metadata |
88
94
 
89
95
  ### IPFS
90
- | Tool | Price | Description |
96
+ | tool | price | description |
91
97
  |------|-------|-------------|
92
- | `pin_to_ipfs` | $0.01 | Pin JSON to IPFS |
93
- | `get_from_ipfs` | $0.001 | Retrieve content from IPFS by CID |
98
+ | `pin_to_ipfs` | $0.01 | pin json to IPFS |
99
+ | `get_from_ipfs` | $0.001 | retrieve content from IPFS by cid |
94
100
 
95
- ### Travel
96
- | Tool | Price | Description |
101
+ ### travel
102
+ | tool | price | description |
97
103
  |------|-------|-------------|
98
- | `search_flights` | $0.02 | Flight search via `/api/travel/flights` |
99
- | `search_locations` | currently unavailable on the live gateway | tool exists in MCP code but targets `/api/travel/locations`, which is not present in the current gateway routes |
100
- | `search_hotels` | $0.02 | Hotel search via `/api/travel/hotels` |
101
- | `search_cheapest_dates` | currently unavailable on the live gateway | tool exists in MCP code but targets `/api/travel/cheapest-dates`, which is not present in the current gateway routes |
102
-
103
- ## What this MCP server does not currently expose
104
+ | `search_flights` | $0.02 | flight search via `/api/travel/flights` |
105
+ | `search_locations` | currently unavailable on the live gateway | MCP tool exists but targets `/api/travel/locations`, which is not in the current gateway routes |
106
+ | `search_hotels` | $0.02 | hotel search via `/api/travel/hotels` |
107
+ | `search_cheapest_dates` | currently unavailable on the live gateway | MCP tool exists but targets `/api/travel/cheapest-dates`, which is not in the current gateway routes |
104
108
 
105
- The live gateway has a larger paid surface than this MCP package currently wraps.
109
+ ## what this package does not expose yet
106
110
 
107
- for the canonical counts and route mapping, see `~/x402-gateway/config/x402engine-truth.json`.
111
+ notable live gateway capabilities that are outside this curated MCP surface:
108
112
 
109
- notable gateway routes that are live in `x402-gateway` but not exposed as first class MCP tools here include:
110
-
111
- - 38 llm routes under `/api/llm/*`
113
+ - 38 LLM routes under `/api/llm/*`
112
114
  - embeddings via `/api/embeddings`
113
115
  - video generation via `/api/video/*`
114
116
  - web routes via `/api/web/*`
@@ -117,35 +119,34 @@ notable gateway routes that are live in `x402-gateway` but not exposed as first
117
119
  - ens routes via `/api/ens/*`
118
120
  - tx simulation via `/api/tx/simulate`
119
121
 
120
- for the full live catalog, use `discover_services` against the gateway discovery document.
121
-
122
- ## Environment Variables
122
+ ## environment variables
123
123
 
124
- | Variable | Required | Description |
124
+ | variable | required | description |
125
125
  |----------|----------|-------------|
126
- | `X402_BASE_URL` | No | Gateway URL. Defaults to `https://x402-gateway-production.up.railway.app` |
127
- | `X402_DEV_BYPASS` | No | Dev bypass secret to skip payments |
128
- | `X402_PAYMENT_HEADER` | No | Pre signed payment header |
126
+ | `X402_BASE_URL` | no | gateway url. defaults to `https://x402-gateway-production.up.railway.app` |
127
+ | `X402_DEV_BYPASS` | no | dev bypass secret for local testing |
128
+ | `X402_PAYMENT_HEADER` | no | pre signed x402 payment header for automatic payment |
129
129
 
130
- ## Payment Networks
130
+ ## payment rails
131
131
 
132
- - **Base** — USDC, 6 decimals
133
- - **Solana** — USDC, 6 decimals
134
- - **MegaETH** — USDm, 18 decimals
132
+ - base: USDC, 6 decimals
133
+ - solana: USDC, 6 decimals
134
+ - megaeth: USDm, 18 decimals
135
135
 
136
- ## How It Works
136
+ ## request flow
137
137
 
138
- 1. agent calls an MCP tool
139
- 2. MCP server makes an HTTP request to the gateway
140
- 3. gateway returns `402 Payment Required` plus payment metadata when payment is needed
141
- 4. caller pays with x402 compatible payment flow
142
- 5. gateway verifies payment and returns data
138
+ 1. the agent calls an MCP tool
139
+ 2. this server makes the matching HTTP request to the gateway
140
+ 3. if payment is required, the gateway returns `402 Payment Required` plus payment metadata
141
+ 4. the caller pays with an x402 compatible payment flow
142
+ 5. the gateway verifies payment and returns the result
143
143
 
144
- for automatic payment handling, use [@x402/fetch](https://www.npmjs.com/package/@x402/fetch) in your agent code.
144
+ for automatic payment handling in custom agent code, use [@x402/fetch](https://www.npmjs.com/package/@x402/fetch).
145
145
 
146
- ## Links
146
+ ## trust and distribution links
147
147
 
148
- - Gateway: [x402engine.app](https://x402-gateway-production.up.railway.app)
149
- - Discovery: [x402engine.app/.well-known/x402.json](https://x402-gateway-production.up.railway.app/.well-known/x402.json)
150
- - GitHub: [github.com/agentc22/x402engine-mcp](https://github.com/agentc22/x402engine-mcp)
151
- - Protocol: [x402.org](https://x402.org)
148
+ - website: [x402engine.app](https://x402engine.app)
149
+ - gateway base url: [x402-gateway-production.up.railway.app](https://x402-gateway-production.up.railway.app)
150
+ - npm: [x402engine-mcp](https://www.npmjs.com/package/x402engine-mcp)
151
+ - github: [agentc22/x402engine-mcp](https://github.com/agentc22/x402engine-mcp)
152
+ - protocol: [x402.org](https://x402.org)
package/dist/index.js CHANGED
@@ -68,7 +68,7 @@ function textResult(content) {
68
68
  function createServer() {
69
69
  const server = new McpServer({
70
70
  name: "x402engine",
71
- version: "1.0.0",
71
+ version: "1.0.6",
72
72
  });
73
73
  // ==================== DISCOVERY ====================
74
74
  server.tool("discover_services", "List all available x402 Engine APIs with pricing, endpoints, and payment networks. Call this first to understand what's available.", {}, async () => {
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "x402engine-mcp",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "type": "module",
5
- "description": "Curated MCP wrapper for x402engine, exposing discovery, image, code, transcription, crypto, wallet, IPFS, and travel tools over HTTP 402 micropayments",
5
+ "description": "agent-friendly MCP wrapper for x402engine, exposing curated pay-per-call tools over x402 micropayments with no api keys or accounts",
6
6
  "main": "./dist/index.js",
7
7
  "module": "./src/index.ts",
8
8
  "bin": {
@@ -23,11 +23,18 @@
23
23
  "mcp",
24
24
  "model-context-protocol",
25
25
  "x402",
26
+ "http-402",
26
27
  "micropayments",
28
+ "software-paying-software",
27
29
  "ai-agents",
30
+ "agent-tools",
31
+ "no-api-keys",
32
+ "no-accounts",
28
33
  "crypto",
29
34
  "usdc",
30
- "api-gateway",
35
+ "base",
36
+ "megaeth",
37
+ "solana",
31
38
  "pay-per-call"
32
39
  ],
33
40
  "mcpName": "io.github.agentc22/x402engine-mcp",
@@ -45,5 +52,9 @@
45
52
  "@types/node": "^22.0.0",
46
53
  "tsx": "^4.19.0",
47
54
  "typescript": "^5.7.0"
55
+ },
56
+ "homepage": "https://x402engine.app",
57
+ "bugs": {
58
+ "url": "https://github.com/agentc22/x402engine-mcp/issues"
48
59
  }
49
60
  }
package/server.json CHANGED
@@ -1,17 +1,17 @@
1
1
  {
2
2
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
3
  "name": "io.github.agentc22/x402engine-mcp",
4
- "description": "50+ pay-per-call APIs for AI agents — images, LLM, code, crypto, travel & more via x402",
4
+ "description": "curated x402engine MCP server for agents. discover and call paid tools over HTTP 402 with no api keys or accounts.",
5
5
  "repository": {
6
6
  "url": "https://github.com/agentc22/x402engine-mcp",
7
7
  "source": "github"
8
8
  },
9
- "version": "1.0.3",
9
+ "version": "1.0.6",
10
10
  "packages": [
11
11
  {
12
12
  "registryType": "npm",
13
13
  "identifier": "x402engine-mcp",
14
- "version": "1.0.3",
14
+ "version": "1.0.6",
15
15
  "transport": {
16
16
  "type": "stdio"
17
17
  },
@@ -34,7 +34,23 @@
34
34
  "isRequired": false,
35
35
  "isSecret": true
36
36
  }
37
+ ],
38
+ "runtimeHint": "uses stdio transport and calls the live x402engine gateway over HTTP. payment can be supplied via X402_PAYMENT_HEADER or bypassed in development with X402_DEV_BYPASS.",
39
+ "keywords": [
40
+ "x402",
41
+ "micropayments",
42
+ "http-402",
43
+ "software-paying-software",
44
+ "no-api-keys",
45
+ "no-accounts",
46
+ "agents"
47
+ ],
48
+ "packageArguments": [
49
+ "-y",
50
+ "x402engine-mcp"
37
51
  ]
38
52
  }
39
- ]
53
+ ],
54
+ "websiteUrl": "https://x402engine.app",
55
+ "documentationUrl": "https://github.com/agentc22/x402engine-mcp#readme"
40
56
  }