mpp32-mcp-server 1.0.2 → 1.1.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 +84 -164
  2. package/dist/index.js +544 -244
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  <p align="center">
2
2
  <h1 align="center">MPP32</h1>
3
- <p align="center"><strong>Universal Payment Proxy for Machine-Payable APIs</strong></p>
3
+ <p align="center"><strong>The payment layer for AI agents</strong></p>
4
4
  <p align="center">
5
5
  <a href="https://www.npmjs.com/package/mpp32-mcp-server"><img src="https://img.shields.io/npm/v/mpp32-mcp-server.svg?style=flat-square&color=0052FF" alt="npm version"></a>
6
6
  <a href="https://www.npmjs.com/package/mpp32-mcp-server"><img src="https://img.shields.io/npm/dm/mpp32-mcp-server.svg?style=flat-square&color=0052FF" alt="npm downloads"></a>
@@ -9,61 +9,43 @@
9
9
  </p>
10
10
  </p>
11
11
 
12
- ---
12
+ One install. Five payment rails. Thousands of paid APIs your agent can reach without you setting up a single account.
13
13
 
14
- **MCP server that gives AI agents the ability to discover, pay for, and consume APIs autonomously.**
14
+ ## Why this beats running your own integrations
15
15
 
16
- One integration. Five payment protocols. Instant settlement. No subscriptions, no API keys, no checkout screens — just agents paying for what they use.
16
+ Most agent stacks stop at "the model can call a function." That works until the function costs money. The moment your agent needs premium data, a paid model, a trading signal, or a token analytics call, you are back to building accounts, storing API keys, watching budgets, and writing custom 402 handlers for every provider.
17
17
 
18
- ---
18
+ MPP32 replaces all of that with one MCP server. Your agent asks for a service by name. The server finds it in a federated catalog of thousands of machine payable APIs, negotiates the cheapest protocol, signs payment from a key on your own machine, and returns the data. You write zero billing code. You manage zero provider accounts. Your agent gets faster, cheaper, and reaches services other agents cannot touch.
19
19
 
20
- ## Why MPP32
20
+ ## What your agent can do once this is installed
21
21
 
22
- The agent economy needs a payment layer. Today, agents can browse the web and call APIs — but they can't pay for premium data or services without a human setting up accounts and credentials for each provider.
22
+ * Browse a live catalog of over 4,500 paid and free APIs across categories like token intelligence, market data, web search, image generation, embeddings, DeFi analytics, wallet scoring, on chain queries, and trading signals.
23
+ * Pay any provider in the catalog using whichever protocol fits, with settlement that lands in seconds.
24
+ * Run real time Solana token intelligence with alpha scoring, rug risk, whale flow, and 24 hour pump probability.
25
+ * Track every call, every dollar settled, and every protocol used from a dashboard at mpp32.org.
26
+ * Get an automatic 20 percent or 40 percent discount on native services for holding M32 once your wallet is verified.
23
27
 
24
- MPP32 solves this. It's a universal proxy that sits between agents and API providers, handling payment negotiation across **five protocols** so neither side has to implement the others:
28
+ ## Payment rails it speaks natively
25
29
 
26
- ```
27
- ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐
28
- │ AI Agent │ ──────> │ MPP32 │ ──────> │ API Provider │
29
- │ (Claude, │ 402 │ Payment │ paid │ (Data, Intel, │
30
- │ GPT, etc.) │ <────── │ Proxy │ <────── │ Services) │
31
- │ │ retry │ │ response│ │
32
- │ │ ──────> │ ✓ verified │ ──────> │ │
33
- └─────────────┘ └─────────────┘ └──────────────────┘
34
- ```
35
-
36
- **For agents:** Pay-per-call access to any API in the ecosystem. No accounts. No subscriptions.
37
-
38
- **For providers:** List once, get paid via any protocol. No payment integration needed.
39
-
40
- ---
30
+ | Rail | Settles in | Network |
31
+ |:-----|:-----------|:--------|
32
+ | x402 | USDC | Solana |
33
+ | Tempo | pathUSD | Ethereum L2 |
34
+ | ACP | Checkout session | Multi chain |
35
+ | AP2 | W3C verifiable credentials | Chain agnostic |
36
+ | AGTP | HMAC signed agent certificates | Chain agnostic |
41
37
 
42
- ## Supported Payment Protocols
38
+ Every native endpoint accepts all five. The server picks whichever your wallet is funded for and falls back gracefully if the first attempt fails.
43
39
 
44
- | Protocol | Type | Settlement | Network | Speed |
45
- |:---------|:-----|:-----------|:--------|:------|
46
- | **x402** | Payment | USDC | Solana Mainnet | ~200ms |
47
- | **Tempo** | Payment | pathUSD | Ethereum L2 | ~500ms |
48
- | **ACP** | Payment | Checkout sessions | Multi-chain | Session-based |
49
- | **AP2** | Authorization | W3C Verifiable Credentials | Chain-agnostic | Instant |
50
- | **AGTP** | Identity | HMAC-signed agent certs | Chain-agnostic | Instant |
51
-
52
- All five protocols are accepted on every endpoint. Agents choose their preferred method. MPP32 handles verification and settlement.
53
-
54
- ---
55
-
56
- ## Quick Start
57
-
58
- ### Install
40
+ ## Install
59
41
 
60
42
  ```bash
61
43
  npx mpp32-mcp-server
62
44
  ```
63
45
 
64
- ### Claude Desktop & Claude Code
46
+ ### Claude Desktop, Claude Code, Cursor, Windsurf
65
47
 
66
- Add to your MCP configuration file:
48
+ Drop this into the MCP servers section of your client config.
67
49
 
68
50
  ```json
69
51
  {
@@ -72,164 +54,108 @@ Add to your MCP configuration file:
72
54
  "command": "npx",
73
55
  "args": ["mpp32-mcp-server"],
74
56
  "env": {
75
- "MPP32_SOLANA_PRIVATE_KEY": "your-solana-private-key-for-usdc-payments"
57
+ "MPP32_AGENT_KEY": "mpp32_agent_…",
58
+ "MPP32_SOLANA_PRIVATE_KEY": "your_solana_private_key_for_usdc"
76
59
  }
77
60
  }
78
61
  }
79
62
  }
80
63
  ```
81
64
 
82
- ### Cursor, Windsurf, and Other MCP Clients
83
-
84
- Same configuration format — add `mpp32` to your MCP server list with at least one payment key.
65
+ Get an `MPP32_AGENT_KEY` at [mpp32.org/agent-console](https://mpp32.org/agent-console). No signup, no email, just a session form. With an agent key every call is attributed to your dashboard so you can see spend, success rate, and protocol breakdown. Without it the server still works but you only see native services and the calls stay anonymous.
85
66
 
86
- ---
67
+ `MPP32_SOLANA_PRIVATE_KEY` and `MPP32_PRIVATE_KEY` are only needed for paid services. Free services in the catalog work without any key.
87
68
 
88
- ## Tools
89
-
90
- This server exposes three tools that any MCP-compatible agent can call:
91
-
92
- ### `list_mpp32_services`
93
-
94
- **Browse the API marketplace.** Returns all registered services with names, categories, pricing, and proxy URLs.
95
-
96
- ```typescript
97
- // Example: find all crypto data providers
98
- { category: "token-scanner" }
69
+ ## Configuration
99
70
 
100
- // Returns:
101
- // - MPP32 Solana Intelligence Oracle ($0.008/query)
102
- // - ... more services as providers register
103
- ```
71
+ | Variable | When you need it | What it does |
72
+ |:---------|:-----------------|:-------------|
73
+ | `MPP32_AGENT_KEY` | Recommended | Session key from mpp32.org/agent-console. Unlocks the full federated catalog and dashboard tracking. Also accepted as `MPP32_API_KEY`. |
74
+ | `MPP32_SOLANA_PRIVATE_KEY` | Paid x402 calls | Solana key used to sign USDC payments locally. |
75
+ | `MPP32_PRIVATE_KEY` | Paid Tempo calls | EVM key used to sign pathUSD payments locally on Ethereum L2. |
76
+ | `MPP32_API_URL` | Custom deployments | Override the API base URL. Defaults to `https://mpp32.org`. |
104
77
 
105
- > **30+ categories:** ai-inference, token-scanner, price-oracle, web-search, trading-signal, defi-analytics, wallet-intelligence, on-chain-data, market-data, image-generation, embeddings, and more.
78
+ Private keys stay on your machine. They sign payments locally and never travel to MPP32 servers. Provide one or both for paid calls. If both are present, x402 is tried first and Tempo is used as a fallback.
106
79
 
107
- ---
80
+ ## Tools your agent will see
108
81
 
109
- ### `get_solana_token_intelligence`
82
+ ### `list_mpp32_services`
110
83
 
111
- **Real-time Solana token analysis.** Aggregates data from DexScreener, Jupiter, and CoinGecko into a single intelligence report.
84
+ Browse the federated catalog. Returns native, curated free, x402 bazaar, and MCP registry entries with pricing, supported protocols, and a clear flag on every row that tells the agent whether it can actually call the service through this MCP or whether the entry is for discovery only.
112
85
 
113
- ```typescript
114
- { token: "BONK" }
115
- // or
116
- { token: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" }
86
+ ```json
87
+ { "category": "token-scanner", "q": "solana", "source": "native" }
117
88
  ```
118
89
 
119
- **Returns:**
120
-
121
- | Field | Description |
122
- |:------|:------------|
123
- | Alpha Score | 0-100 trading viability assessment |
124
- | Rug Risk | Score + level + contributing factors |
125
- | Whale Activity | Volume-to-liquidity ratio with buy/sell breakdown |
126
- | Smart Money Signals | Pattern detection from transaction data |
127
- | Pump Probability | Statistical 24h price movement prediction |
128
- | Projected ROI | Low/high scenarios with timeframe |
129
- | Market Data | Price, volume, liquidity, market cap, pair age |
130
-
131
- **Pricing:** $0.008 per query. M32 token holders receive automatic discounts (20% at 250K, 40% at 1M tokens).
132
-
133
- ---
134
-
135
90
  ### `call_mpp32_endpoint`
136
91
 
137
- **Call any API in the ecosystem.** Handles the complete HTTP 402 payment flow automatically:
92
+ Call any HTTP callable service in the catalog. Free services return immediately. Paid services return a 402 challenge that this tool signs and retries automatically when a payment key is configured.
138
93
 
139
- ```typescript
94
+ ```json
140
95
  {
141
- slug: "mpp32-intelligence",
142
- method: "POST",
143
- body: "{\"token\": \"SOL\"}"
96
+ "slug": "mpp32-intelligence",
97
+ "method": "POST",
98
+ "body": { "token": "SOL" }
144
99
  }
145
100
  ```
146
101
 
147
- **Payment flow (fully automatic):**
148
-
149
- 1. Sends request to the MPP32 proxy
150
- 2. Receives HTTP 402 with payment challenge headers
151
- 3. Selects best available payment protocol
152
- 4. Signs transaction with your configured key
153
- 5. Retries request with payment receipt attached
154
- 6. Returns the API response to your agent
155
-
156
- No manual payment logic. No API keys to manage. No accounts to create.
102
+ Under the hood:
157
103
 
158
- ---
159
-
160
- ## Configuration
104
+ 1. Send the request to `/api/agent/execute`.
105
+ 2. If the service is free, hand the response back.
106
+ 3. If the service is paid, read the 402 challenge.
107
+ 4. Pick the protocol your wallet can satisfy.
108
+ 5. Sign the transaction locally.
109
+ 6. Retry with the receipt attached.
110
+ 7. Return the data with the settled amount, the protocol used, and the on chain settlement signature.
161
111
 
162
- | Variable | Required | Description |
163
- |:---------|:---------|:------------|
164
- | `MPP32_SOLANA_PRIVATE_KEY` | Recommended | Solana private key for **x402** payments (USDC). Fastest settlement (~200ms). |
165
- | `MPP32_PRIVATE_KEY` | Alternative | EVM private key for **Tempo** payments (pathUSD on Ethereum L2). |
166
- | `MPP32_API_URL` | No | Override the API base URL. Default: `https://mpp32.org` |
112
+ No payment logic in your code. No per provider keys to juggle.
167
113
 
168
- > **Security:** Private keys are used locally to sign payment transactions. They are never transmitted to MPP32 servers. The MCP server runs on your machine.
114
+ ### `get_solana_token_intelligence`
169
115
 
170
- Set at least one payment key. Set both for maximum protocol compatibility and automatic fallback.
116
+ Real time analysis of any Solana token. Pulls live data from DexScreener, Jupiter, and CoinGecko and merges it into one report. Returns an alpha score from 0 to 100, rug risk, whale activity, smart money signals, 24 hour pump probability, projected ROI ranges, and full market data. Costs $0.008 per call, paid automatically through x402 or Tempo when a key is set.
171
117
 
172
- ---
118
+ ```json
119
+ { "token": "BONK" }
120
+ ```
173
121
 
174
- ## Architecture
122
+ M32 holders get tiered discounts (20 percent at 250k, 40 percent at 1M) the moment their wallet is verified at the agent console.
175
123
 
176
- ```
177
- ┌─────────────────────────────────────┐
178
- │ MPP32 Platform │
179
- │ │
180
- ┌──────────┐ HTTP │ ┌───────────┐ ┌──────────────┐ │ HTTP ┌──────────────┐
181
- │ │ ──────────> │ │ Payment │ │ Provider │ │ ────────> │ │
182
- │ MCP │ 402 │ │ Middleware │───>│ Registry │ │ │ Upstream │
183
- │ Server │ <────────── │ │ │ │ │ │ │ API │
184
- │ (this) │ + key │ │ x402 │ │ Verification │ │ <──────── │ Provider │
185
- │ │ ──────────> │ │ Tempo │ │ 24h re-check │ │ │ │
186
- │ │ 200 │ │ ACP │ │ 3-strike │ │ │ │
187
- │ │ <────────── │ │ AP2 │ │ suspension │ │ └──────────────┘
188
- └──────────┘ │ │ AGTP │ └──────────────┘ │
189
- │ └───────────┘ │
190
- │ │
191
- │ ┌───────────────────────────────┐ │
192
- │ │ Discovery Layer │ │
193
- │ │ OpenAPI 3.1 · A2A Agent Card │ │
194
- │ │ MCP Config · Service Directory│ │
195
- │ └───────────────────────────────┘ │
196
- └─────────────────────────────────────┘
197
- ```
124
+ ## How discovery works
198
125
 
199
- **Payment verification is real.** x402 payments are verified on-chain via the Solana facilitator. Tempo payments are verified cryptographically via the mppx SDK. ACP sessions are database-backed with checkout flow. AP2 mandates use ECDSA P-256 signature verification. AGTP requires HMAC-SHA256 signed agent certificates.
126
+ MPP32 keeps a federated index of machine payable services so your agent can find what is out there without crawling every provider on its own. Four sources feed it.
200
127
 
201
- ---
128
+ | Source | What it is | Callable through this MCP |
129
+ |:-------|:-----------|:--------------------------|
130
+ | MPP32 native | APIs registered through mpp32.org/build. Verified, payable end to end. | Yes |
131
+ | Curated free | Hand maintained list of DexScreener, Jupiter, CoinGecko, OpenAI, and similar public APIs. | Yes when `MPP32_AGENT_KEY` is set |
132
+ | x402 Bazaar | Resources discovered through the Coinbase x402 facilitator. | Listing only. Pay providers directly via x402. |
133
+ | MCP Registry | Servers from the official Model Context Protocol registry. | No. Install via npx and run them as a separate stdio server. |
202
134
 
203
- ## Discovery & Interoperability
135
+ Every row in `list_mpp32_services` carries a callable flag so it stays obvious which slugs can be passed to `call_mpp32_endpoint`.
204
136
 
205
- MPP32 implements standard discovery protocols so any agent framework can find and integrate with the ecosystem:
137
+ ## Sessions for autonomous agents
206
138
 
207
- | Standard | Endpoint | Purpose |
208
- |:---------|:---------|:--------|
209
- | **OpenAPI 3.1** | [`/openapi.json`](https://mpp32.org/openapi.json) | Full API specification with payment metadata |
210
- | **A2A Agent Card** | [`/.well-known/agent.json`](https://mpp32.org/.well-known/agent.json) | Agent-to-agent capability discovery |
211
- | **MCP Config** | [`/api/mcp-config`](https://mpp32.org/api/mcp-config) | Model Context Protocol server configuration |
212
- | **Service Directory** | [`/api/submissions`](https://mpp32.org/api/submissions) | Live registry of all API providers |
139
+ For longer running workflows, MPP32 issues server side session keys with a 30 day expiry and full per call accounting. Sessions let an agent run inside a budget instead of negotiating payment every single call.
213
140
 
214
- Every paid endpoint returns HTTP 402 with challenge headers for all active protocols, enabling any compliant agent to complete payment regardless of which protocol it implements.
141
+ 1. Create a session at [mpp32.org/agent-console](https://mpp32.org/agent-console) or by posting to `/api/agent/sessions`.
142
+ 2. Get a key in the form `mpp32_agent_*`.
143
+ 3. Put it in `MPP32_AGENT_KEY` in your MCP config, or send it as `X-Agent-Key` on direct API calls.
144
+ 4. Watch spend, latency, and protocol mix live in the dashboard.
215
145
 
216
- ---
146
+ Sessions are scoped, revocable, and rotate cleanly. The key is hashed at rest on the server, so a database leak does not surrender live credentials.
217
147
 
218
- ## For API Providers
148
+ ## How payment verification actually works
219
149
 
220
- **Register your API once. Get paid via five protocols automatically.**
150
+ x402 payments are verified on chain through the Solana facilitator. Tempo payments are verified cryptographically through the mppx SDK. ACP sessions are database backed with a real checkout flow. AP2 mandates use ECDSA P-256 signature verification. AGTP uses HMAC SHA256 signed agent certificates with a server held salt so signatures cannot be forged from a public agent id alone.
221
151
 
222
- MPP32 acts as a reverse proxy — you provide the endpoint, we handle:
152
+ Every protocol has its own verification path. None of them are stubbed. MPP32 never holds custody of funds. Every paid call settles directly from the caller's wallet to the provider's wallet.
223
153
 
224
- - Payment negotiation and verification across all 5 protocols
225
- - Endpoint health monitoring with 24-hour re-verification
226
- - Discovery listing via OpenAPI, A2A, and MCP standards
227
- - Analytics dashboard with query counts, revenue, and latency metrics
228
- - USDC and pathUSD settlement to your wallet
154
+ ## For API providers
229
155
 
230
- Register at **[mpp32.org/build](https://mpp32.org/build)**.
156
+ List your endpoint once and get paid through every protocol automatically. MPP32 handles the payment negotiation, the on chain verification, the discovery listings via OpenAPI and A2A and MCP standards, the 24 hour health re check, and the analytics dashboard. Settlement lands in USDC or pathUSD straight to your wallet.
231
157
 
232
- ---
158
+ Register at [mpp32.org/build](https://mpp32.org/build).
233
159
 
234
160
  ## Links
235
161
 
@@ -237,17 +163,11 @@ Register at **[mpp32.org/build](https://mpp32.org/build)**.
237
163
  |:---------|:----|
238
164
  | Website | [mpp32.org](https://mpp32.org) |
239
165
  | Documentation | [mpp32.org/docs](https://mpp32.org/docs) |
240
- | API Playground | [mpp32.org/playground](https://mpp32.org/playground) |
166
+ | Playground | [mpp32.org/playground](https://mpp32.org/playground) |
241
167
  | Ecosystem | [mpp32.org/ecosystem](https://mpp32.org/ecosystem) |
242
- | Use Cases | [mpp32.org/use-cases](https://mpp32.org/use-cases) |
168
+ | Agent Console | [mpp32.org/agent-console](https://mpp32.org/agent-console) |
243
169
  | GitHub | [github.com/MPP32/MPP32](https://github.com/MPP32/MPP32) |
244
170
 
245
- ---
246
-
247
- <p align="center">
248
- <strong>MPP32</strong> — The payment layer for the agent economy.
249
- </p>
250
-
251
171
  ## License
252
172
 
253
173
  MIT