mcp-server-madeonsol 1.27.1 → 3.0.0

package/README.md

@@ -15,6 +15,10 @@ MCP server for [MadeOnSol](https://madeonsol.com) Solana KOL intelligence API. U
 
 > Real-time Solana trading intelligence: track 2,000+ KOL wallets with <3s latency on paid keys and x402 pay-per-call (free-tier live feeds are 5-min delayed), score 85K+ Pump.fun deployers, surface deshred deploy signals **~500ms before on-chain confirmation**, detect multi-KOL coordination, surface bundle-cohort holdings (which same-slot wallets still hold a token's supply), verify any wallet's CURRENT on-chain holdings straight from its token accounts, and stream every DEX trade across 9+ programs. Free tier: 200 requests/day across 40+ endpoints (live feeds 5-min delayed) — no signup payment. Get a key at [madeonsol.com/pricing](https://madeonsol.com/pricing).
 
+> **New in 3.0.0 — BREAKING for x402 (keyless) mode only: five env vars are now required and startup FAILS instead of silently degrading (security fix, SDK-01).** Set `X402_PAY_TO`, `X402_FEE_PAYER`, `X402_MAX_AMOUNT_ATOMIC`, `X402_MAX_TOTAL_AMOUNT_ATOMIC` and `SVM_RPC_URL` alongside `SVM_PRIVATE_KEY`. Before, keyless mode signed whatever Solana USDC amount, recipient and fee payer a 402 challenge asked for. Now every challenge is checked BEFORE signing against a trusted merchant `payTo`, a trusted facilitator `feePayer` (which must differ from your wallet), the USDC mint, `solana:5eykt…` mainnet, the `exact` scheme, a per-call cap and a lifetime cap. Use the canonical values in the keyless section below; caps must be at least `20000` (0.02 USDC) per call to reach every endpoint. The budget is per client instance / process: not wallet-wide, not shared between processes, reset on a new instance or restart. Keyless requires the base URL exactly `https://madeonsol.com`. **API-key (`msk_`) users: no change, no new config.** HTTP mode still refuses wallet signers (SEC-02, unchanged).
+
+> **New in 2.0.0 — BREAKING: HTTP mode now requires a separate token (security fix, SEC-02).** If you run this server with `MCP_TRANSPORT=http`, you must now also set `MCP_HTTP_TOKEN` (a random secret you generate) and send it as `Authorization: Bearer <token>` on **every** request, including `GET /health` and the server-card endpoint — previously, anything that could reach the bound port could call every tool using the operator's own API key with no authentication at all. HTTP mode is now hard-restricted to literal loopback (`127.0.0.1` / `::1`), rejects `Origin`/`X-Forwarded-*` headers and duplicate `Authorization`/`Host` headers outright, exposes only `POST /mcp` plus the two GET routes, and **refuses to start** if a wallet/payment signer is configured — HTTP mode can never carry a payer key. **If you use the default `stdio` transport (Claude Desktop, Cursor, most MCP clients), nothing changes — no action needed.** This is a single shared-operator-token fix, not a new multi-user or OAuth system; each HTTP caller still shares the operator's own MadeOnSol API key. Full writeup: `docs/audit/SEC02_PRIVATE_HTTP_MCP.md`.
+>
 > **New in 1.27.1 — the server now reports MCP `instructions`.** The `initialize` response's `instructions` field (operational guidance for the calling agent — distinct from this README/package description) was never set; directories that introspect the live server (Glama) reported "no recorded MCP instructions." No new tools; still 104 total.
 >
 > **New in 1.27.0 — top traders, sniper watchlist management, and two update tools (104 tools total).** Six additions found by an internal agentic-infra coverage audit. `madeonsol_token_top_traders` (`GET /tokens/{mint}/top-traders`, PRO/ULTRA) ranks a token's wallets by realized PnL or ROI, enriched with KOL/alpha-wallet identity — this endpoint already existed on the REST API and x402 rail but had no MCP tool. `madeonsol_sniper_watchlist_list` / `_add` / `_remove` (PRO+/ULTRA) manage your custom sniper-deploy watchlist (`madeonsol_sniper_recent(watchlist: true)` narrows to it) — previously only reachable via raw HTTP. `madeonsol_update_webhook` (PATCH) changes a webhook's URL, events, or active state without deleting and recreating it. `madeonsol_wallet_tracker_relabel` (PATCH) renames or clears a tracked wallet's label.
@@ -97,7 +101,7 @@ Restart Claude Desktop and ask: *"What are KOLs buying right now?"*
 
 ## AI agent quickstart (x402 / pay-per-call)
 
-Building an autonomous agent? Skip the signup. Point a **funded Solana wallet** at the server and every tool call **auto-pays a micropayment** over [x402](https://x402.org) — no API key, no account, no rate-limit dance.
+Building an autonomous agent? Skip the signup. Configure a **funded Solana wallet** and an explicit payment budget. Paid tool calls authorize micropayments within that budget over [x402](https://x402.org) — no API key, no account, no rate-limit dance.
 
 ```json
 {
@@ -105,7 +109,12 @@ Building an autonomous agent? Skip the signup. Point a **funded Solana wallet**
     "madeonsol": {
       "command": "mcp-server-madeonsol",
       "env": {
-        "SVM_PRIVATE_KEY": "<base58 solana private key>"
+        "SVM_PRIVATE_KEY": "<base58 solana private key>",
+        "X402_PAY_TO": "GLu63pRCYrp4BJu5P5ciYKxgeZFW9c8TJ8jWzK3TB9AR",
+        "X402_FEE_PAYER": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4",
+        "X402_MAX_AMOUNT_ATOMIC": "20000",
+        "X402_MAX_TOTAL_AMOUNT_ATOMIC": "1000000",
+        "SVM_RPC_URL": "https://<your-trusted-solana-rpc>"
       }
     }
   }
@@ -114,7 +123,7 @@ Building an autonomous agent? Skip the signup. Point a **funded Solana wallet**
 
 How it works:
 
-- The wallet behind `SVM_PRIVATE_KEY` settles each request as a **USDC micropayment on Solana** (~$0.005–$0.02 per call, settled on-chain). No subscription, no quota.
+- The wallet behind `SVM_PRIVATE_KEY` settles each request as a **USDC micropayment on Solana** (~$0.005–$0.02 per call, settled on-chain). No subscription; the configured authorization budget bounds spending.
 - The keyless catalog covers **25 endpoints** — the latest additions: token candles ($0.01), almost-bonded ($0.01), top-traders ($0.02), cap-table ($0.02), sniper recent deploys ($0.01), token flow ($0.01), and deployer trajectory ($0.01).
 - The free **`madeonsol_discovery`** tool needs no auth and returns every endpoint with its exact per-call price — call it first to see what each tool costs.
 - Install the x402 peer deps alongside the server (only required for this mode):
@@ -127,6 +136,34 @@ How it works:
 
 Prefer a fixed monthly bill, free tier, or no wallet? Use the developer path below.
 
+## Required payment policy (breaking keyless upgrade)
+
+Keyless Solana payments require an explicit trusted merchant, facilitator and authorization budget. API-key mode is unchanged and takes precedence over a configured wallet.
+
+Only exact payments in mainnet USDC are permitted. Set the two addresses from your trusted operator configuration, independently of a server challenge. `SVM_RPC_URL` must be your trusted HTTPS RPC; there is no public RPC fallback. The agent wallet cannot also be the facilitator fee payer.
+
+| Setting | Meaning |
+|---|---|
+| `X402_PAY_TO` | Trusted merchant wallet receiving USDC |
+| `X402_FEE_PAYER` | Trusted facilitator wallet paying transaction fees |
+| `X402_MAX_AMOUNT_ATOMIC` | Maximum per payment, as a positive integer string |
+| `X402_MAX_TOTAL_AMOUNT_ATOMIC` | Lifetime authorization allowance, as a positive integer string |
+| `SVM_RPC_URL` | Explicit trusted HTTPS Solana RPC URL |
+
+USDC uses 6 decimals: `20000` = 0.02 USDC and `1000000` = 1 USDC. Choose limits that cover the endpoints you intend to use; these examples are not a price guarantee.
+
+**Canonical MadeOnSol values (Solana mainnet USDC).** Pinned here (GitHub + npm README) so you do not have to take them from a 402:
+- merchant `payTo` / `X402_PAY_TO`: `GLu63pRCYrp4BJu5P5ciYKxgeZFW9c8TJ8jWzK3TB9AR` (also shown on https://madeonsol.com/x402 and https://madeonsol.com/.well-known/x402)
+- facilitator `feePayer` / `X402_FEE_PAYER`: `2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4`. This is the fee payer of **PayAI**, the third-party facilitator MadeOnSol's Solana rail uses. If PayAI rotates it, keyless calls fail closed (the client refuses to sign) until you update this value; a MadeOnSol release will announce the new one.
+- prices: Solana legs are 5000–20000 atomic (0.005–0.02 USDC), so `maxAmountAtomic` / `X402_MAX_AMOUNT_ATOMIC` must be at least `20000` to reach every endpoint.
+
+The budget is per client instance / process: not wallet-wide, not shared between processes, reset when a new instance or process starts. Keyless mode requires the base URL exactly `https://madeonsol.com`.
+
+
+The allowance is reserved before concurrent calls can approve/sign. An unsigned denial releases it; entering payment creation retains it even if RPC, signing or the paid response fails. It measures **authorized attempts, not settled spend**. There is no automatic refund or payment replay. A timeout cannot undo a proof already sent.
+
+The allowance is per server process; restarting starts a new allowance. Reuse the running process. Multiple MCP servers or other clients sharing a wallet need an external shared budget. Missing/invalid keyless settings stop startup; wallet signing remains restricted to stdio. The payment attempt timeout defaults to 30 seconds.
+
 ## Authentication
 
 Two options (in priority order):
@@ -169,6 +206,24 @@ Add to `claude_desktop_config.json`:
 
 Add to MCP settings with the same command and env vars.
 
+
+## Private HTTP transport (SEC-02)
+
+Stdio remains the default for Claude Desktop, Cursor and other local MCP clients. HTTP now requires an explicit private-operator configuration; previously unauthenticated HTTP launch settings will fail closed.
+
+1. Set `MADEONSOL_API_KEY` to the operator's `msk_` key.
+2. Generate a separate random access token, for example `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`, and store it as `MCP_HTTP_TOKEN`. Do not reuse the upstream API key or put either credential in a URL.
+3. Set `MCP_TRANSPORT=http`, `HOST=127.0.0.1` (default, or `::1`) and optionally `PORT` (default `3100`). Non-loopback bindings, missing credentials and any `SVM_PRIVATE_KEY` or `RHC_PAYER_KEY` are refused before startup. Solana wallet/x402 mode remains available through stdio.
+4. Connect to `http://127.0.0.1:3100/mcp` with `Authorization: Bearer <MCP_HTTP_TOKEN>` on **every request**, plus the normal MCP `Content-Type` and `Accept` headers. Use stdio if the client cannot attach headers. The local token is checked by the MCP adapter; only `MADEONSOL_API_KEY` is sent upstream.
+
+Only `POST /mcp`, `GET /health` and `GET /.well-known/mcp/server-card.json` are exposed, all authenticated. `/` and arbitrary paths are no longer MCP endpoints. The adapter is stateless: it does not issue session IDs, rejects supplied `Mcp-Session-Id`, and returns 405 for GET/DELETE on `/mcp`. Host must be the selected loopback literal with its port, or `localhost` with that exact port. Browser Origin headers, forwarded/proxy headers and cross-origin requests are rejected; no CORS access is granted.
+
+Limits: 256 KiB uncompressed JSON bodies, 8 KiB headers, a 10-second body-upload deadline, and 16 active authenticated requests. Oversized or malformed inputs are rejected before tool dispatch. This is not an overall tool-execution deadline; an upstream action already submitted may continue after a disconnect.
+
+Everyone holding the local token acts as the **same operator**, including access to that operator's mutation tools. This is not a multi-user/OAuth server: do not put it behind a public proxy, share it with untrusted users or expose a funded signer. Separate users require isolated processes/credentials or a future transport that authenticates each principal and maps their own credentials. Restart with a new `MCP_HTTP_TOKEN` to rotate access.
+
+The Docker image uses the same loopback restriction and requires both environment credentials. Its healthcheck authenticates without putting the token in the URL. It does not support a publicly published Docker port; use stdio or a client in the same trusted network namespace.
+
 ## Tools
 
 ### KOL Intelligence
@@ -369,3 +424,4 @@ Free tier returns the full REST response shape on 40+ endpoints — real wallets
 ## License
 
 MIT
+

package/dist/http-security.d.ts

@@ -0,0 +1,14 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+export declare const MAX_BODY_BYTES: number;
+export declare const BODY_TIMEOUT_MS = 10000;
+export declare const MAX_ACTIVE_REQUESTS = 16;
+export interface HttpConfig {
+    host: "127.0.0.1" | "::1";
+    port: number;
+    allowedHosts: string[];
+    tokenDigest: Buffer;
+}
+export declare function readHttpConfig(env?: NodeJS.ProcessEnv): HttpConfig;
+/** Bounded body ingestion; callers must authenticate before invoking this. */
+export declare function readJsonBody(req: IncomingMessage, maxBytes?: number, timeoutMs?: number): Promise<unknown>;
+export declare function createPrivateHttpServer(config: HttpConfig, handle: (req: IncomingMessage, res: ServerResponse, body?: unknown) => Promise<void>): import("http").Server<typeof IncomingMessage, typeof ServerResponse>;

package/dist/http-security.js

@@ -0,0 +1,180 @@
+// Keep this standalone-package helper identical in both MCP packages.
+// HTTP is a private, single-operator adapter. Public/multi-user hosting is
+// intentionally unsupported until credentials can be scoped per principal.
+import { createServer } from "node:http";
+import { createHash, timingSafeEqual } from "node:crypto";
+export const MAX_BODY_BYTES = 256 * 1024;
+export const BODY_TIMEOUT_MS = 10_000;
+export const MAX_ACTIVE_REQUESTS = 16;
+export function readHttpConfig(env = process.env) {
+    const host = env.HOST || "127.0.0.1";
+    if (host !== "127.0.0.1" && host !== "::1") {
+        throw new Error("HTTP MCP requires HOST=127.0.0.1 or ::1; public binding is unsupported. Use stdio for local clients.");
+    }
+    const portText = env.PORT || "3100";
+    const port = Number(portText);
+    if (!/^\d+$/.test(portText) || !Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("HTTP MCP requires a valid PORT between 1 and 65535.");
+    }
+    if (env.SVM_PRIVATE_KEY || env.RHC_PAYER_KEY) {
+        throw new Error("HTTP MCP cannot expose a payment signer. Remove wallet credentials or use stdio.");
+    }
+    if (!env.MADEONSOL_API_KEY?.startsWith("msk_")) {
+        throw new Error("HTTP MCP requires the operator's MADEONSOL_API_KEY.");
+    }
+    const token = env.MCP_HTTP_TOKEN || "";
+    if (!/^[A-Za-z0-9_-]{32,256}$/.test(token) || token === env.MADEONSOL_API_KEY) {
+        throw new Error("HTTP MCP requires a separate random MCP_HTTP_TOKEN (32–256 base64url characters).");
+    }
+    const authority = host === "::1" ? `[::1]:${port}` : `${host}:${port}`;
+    return {
+        host, port, allowedHosts: [authority, `localhost:${port}`],
+        tokenDigest: createHash("sha256").update(token).digest(),
+    };
+}
+class HttpFailure extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function fail(res, status, message) {
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+        "Connection": "close",
+        ...(status === 401 ? { "WWW-Authenticate": 'Bearer realm="private-mcp"' } : {}),
+    });
+    res.end(JSON.stringify({ error: message }));
+}
+function headerCount(req, name) {
+    let count = 0;
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        if (req.rawHeaders[i].toLowerCase() === name)
+            count++;
+    }
+    return count;
+}
+function authorize(req, res, config) {
+    const remote = req.socket.remoteAddress;
+    if ((remote !== "127.0.0.1" && remote !== "::1") ||
+        headerCount(req, "host") !== 1 || !config.allowedHosts.includes(req.headers.host || "")) {
+        fail(res, 403, "Forbidden host");
+        return false;
+    }
+    // Native local MCP clients do not need browser origins, CORS or proxy headers.
+    if (req.headers.origin !== undefined || Object.keys(req.headers).some(h => h === "forwarded" || h.startsWith("x-forwarded-"))) {
+        fail(res, 403, "Browser origins and forwarded requests are unsupported");
+        return false;
+    }
+    const auth = req.headers.authorization;
+    const match = typeof auth === "string" ? /^Bearer ([A-Za-z0-9_-]{32,256})$/i.exec(auth) : null;
+    if (headerCount(req, "authorization") !== 1 || !match || !timingSafeEqual(createHash("sha256").update(match[1]).digest(), config.tokenDigest)) {
+        fail(res, 401, "Unauthorized");
+        return false;
+    }
+    return true;
+}
+/** Bounded body ingestion; callers must authenticate before invoking this. */
+export function readJsonBody(req, maxBytes = MAX_BODY_BYTES, timeoutMs = BODY_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        const cleanup = () => {
+            clearTimeout(timer);
+            req.off("data", data);
+            req.off("end", end);
+            req.off("aborted", aborted);
+            req.off("error", error);
+        };
+        const stop = (reason) => { cleanup(); req.pause(); reject(reason); };
+        const timer = setTimeout(() => stop(new HttpFailure(408, "Request body timed out")), timeoutMs);
+        const data = (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                stop(new HttpFailure(413, "Request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        };
+        const end = () => {
+            cleanup();
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                reject(new HttpFailure(400, "Invalid JSON"));
+            }
+        };
+        const aborted = () => stop(new HttpFailure(400, "Request aborted"));
+        const error = () => stop(new HttpFailure(400, "Request failed"));
+        req.on("data", data);
+        req.once("end", end);
+        req.once("aborted", aborted);
+        req.once("error", error);
+    });
+}
+export function createPrivateHttpServer(config, handle) {
+    let active = 0;
+    const server = createServer({ maxHeaderSize: 8192 }, (req, res) => {
+        void (async () => {
+            if (!authorize(req, res, config))
+                return;
+            const isMcp = req.url === "/mcp";
+            const isInfo = req.url === "/health" || req.url === "/.well-known/mcp/server-card.json";
+            if (!isMcp && !isInfo) {
+                fail(res, 404, "Not found");
+                return;
+            }
+            const method = isMcp ? "POST" : "GET";
+            if (req.method !== method) {
+                res.setHeader("Allow", method);
+                fail(res, 405, "Method not allowed");
+                return;
+            }
+            if (isMcp && (req.headers["content-type"]?.split(";")[0].trim().toLowerCase() !== "application/json" ||
+                (req.headers["content-encoding"] !== undefined && req.headers["content-encoding"] !== "identity"))) {
+                fail(res, 415, "Only uncompressed application/json is supported");
+                return;
+            }
+            if (Number(req.headers["content-length"] || 0) > MAX_BODY_BYTES) {
+                fail(res, 413, "Request body too large");
+                return;
+            }
+            // No sessions are issued: a supplied session id must never become an auth bypass.
+            if (req.headers["mcp-session-id"] !== undefined) {
+                fail(res, 400, "HTTP MCP is stateless; session identifiers are unsupported");
+                return;
+            }
+            if (active >= MAX_ACTIVE_REQUESTS) {
+                fail(res, 503, "Too many active requests");
+                return;
+            }
+            active++;
+            let released = false;
+            const release = () => { if (!released) {
+                released = true;
+                active--;
+            } };
+            res.once("close", release);
+            res.once("finish", release);
+            res.setHeader("Cache-Control", "no-store");
+            const body = isMcp ? await readJsonBody(req) : undefined;
+            if (!res.destroyed)
+                await handle(req, res, body);
+        })().catch(error => {
+            if (!res.destroyed)
+                fail(res, error instanceof HttpFailure ? error.status : 500, error instanceof HttpFailure ? error.message : "Internal server error");
+        });
+    });
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 15_000;
+    server.keepAliveTimeout = 5_000;
+    server.maxRequestsPerSocket = 100;
+    return server;
+}

package/dist/index.js

@@ -3,8 +3,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
+import { SolanaPaymentBudget, createSolanaPaidFetch, solanaPaymentPolicyFromConfig } from "./solana-payment.js";
 import { VERSION } from "./version.js";
-import { createServer } from "node:http";
+import { createPrivateHttpServer, readHttpConfig } from "./http-security.js";
 // MCP `initialize` response `instructions` field (ServerOptions.instructions in
 // the SDK) — operational guidance for the calling agent, distinct from the
 // package/marketing description in package.json and glama.json. Left unset
@@ -14,7 +15,6 @@ const SERVER_INSTRUCTIONS = "Real-time Solana on-chain intelligence: KOL wallet
 const BASE_URL = process.env.MADEONSOL_API_URL || "https://madeonsol.com";
 const MADEONSOL_API_KEY = process.env.MADEONSOL_API_KEY; // Native key from madeonsol.com/pricing
 const PRIVATE_KEY = process.env.SVM_PRIVATE_KEY; // x402 micropayments (for AI agents)
-const PORT = parseInt(process.env.PORT || "3100", 10);
 const MODE = process.env.MCP_TRANSPORT || "stdio"; // "stdio" or "http"
 let authMode = "none";
 let paidFetch = fetch;
@@ -56,22 +56,16 @@ async function initAuth() {
         return;
     }
     if (mode === "x402" && PRIVATE_KEY) {
+        const budget = new SolanaPaymentBudget(solanaPaymentPolicyFromConfig(key => process.env[key]));
         try {
-            const { wrapFetchWithPayment } = await import("@x402/fetch");
-            const { x402Client } = await import("@x402/core/client");
-            const { ExactSvmScheme } = await import("@x402/svm/exact/client");
-            const { createKeyPairSignerFromBytes } = await import("@solana/kit");
-            const { base58 } = await import("@scure/base");
-            const signer = await createKeyPairSignerFromBytes(base58.decode(PRIVATE_KEY));
-            const client = new x402Client();
-            client.register("solana:*", new ExactSvmScheme(signer));
-            paidFetch = wrapFetchWithPayment(fetch, client);
+            paidFetch = await createSolanaPaidFetch(PRIVATE_KEY, budget, BASE_URL);
             authMode = "x402";
-            console.error(`[madeonsol-mcp] x402 payments enabled, wallet: ${signer.address}`);
+            console.error("[madeonsol-mcp] x402 payments enabled with an explicit authorization budget");
             return;
         }
         catch (err) {
-            console.error("[madeonsol-mcp] x402 setup failed:", err);
+            // Never silently fall back to unauthenticated mode after a policy/setup failure.
+            throw new Error("[madeonsol-mcp] x402 setup failed", { cause: err });
         }
     }
     console.error("\n[madeonsol-mcp] No auth configured — every tool call will fail.\n" +
@@ -1275,12 +1269,11 @@ function registerTools(server) {
     });
 }
 async function main() {
+    const httpConfig = MODE === "http" ? readHttpConfig() : undefined;
     await initAuth();
     if (MODE === "http") {
-        // HTTP transport for hosted environments (Smithery, etc.)
-        const httpServer = createServer();
-        const transports = new Map();
-        httpServer.on("request", async (req, res) => {
+        // Configuration is validated before authentication can initialize a signer.
+        const httpServer = createPrivateHttpServer(httpConfig, async (req, res, body) => {
             // Health check
             if (req.method === "GET" && req.url === "/health") {
                 res.writeHead(200, { "Content-Type": "application/json" });
@@ -1292,7 +1285,7 @@ async function main() {
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({
                     name: "madeonsol",
-                    description: "Solana KOL trading intelligence and deployer analytics. Real-time data from 1,000+ KOL wallets, 15,500+ Pump.fun deployers, 25,000+ scored alpha wallets, copy-trade rules, and wallet tracker. Supports MadeOnSol API key (msk_) or x402 micropayments.",
+                    description: "Solana KOL trading intelligence and deployer analytics. Real-time data from 1,000+ KOL wallets, 15,500+ Pump.fun deployers, 25,000+ scored alpha wallets, copy-trade rules, and wallet tracker. Private HTTP access with the operator's MadeOnSol API key (msk_).",
                     version: VERSION,
                     tools: [
                         { name: "madeonsol_kol_feed", description: "Get real-time Solana KOL trades from 1,000+ tracked wallets." },
@@ -1390,49 +1383,30 @@ async function main() {
                 }));
                 return;
             }
-            // MCP endpoint
-            const sessionId = req.headers["mcp-session-id"];
-            {
-                if (req.method === "POST") {
-                    let transport = sessionId ? transports.get(sessionId) : undefined;
-                    if (!transport) {
-                        transport = new StreamableHTTPServerTransport({
-                            sessionIdGenerator: undefined,
-                        });
-                        const server = new McpServer({ name: "madeonsol", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
-                        registerTools(server);
-                        await server.connect(transport);
-                    }
-                    await transport.handleRequest(req, res);
-                    return;
-                }
-                if (req.method === "GET" && sessionId) {
-                    const transport = transports.get(sessionId);
-                    if (transport) {
-                        await transport.handleRequest(req, res);
-                        return;
-                    }
-                }
-                if (req.method === "DELETE" && sessionId) {
-                    const transport = transports.get(sessionId);
-                    if (transport) {
-                        await transport.handleRequest(req, res);
-                        transports.delete(sessionId);
-                        return;
-                    }
-                }
+            // One server/transport per authenticated stateless POST /mcp.
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+                enableDnsRebindingProtection: true,
+                allowedHosts: httpConfig.allowedHosts,
+                allowedOrigins: [],
+            });
+            const server = new McpServer({ name: "madeonsol", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
+            res.once("close", () => { void server.close().catch(() => { }); });
+            registerTools(server);
+            await server.connect(transport);
+            if (res.destroyed) {
+                await server.close();
+                return;
             }
-            res.writeHead(404);
-            res.end("Not found");
+            await transport.handleRequest(req, res, body);
         });
-        // Bind to 127.0.0.1 only — defense in depth. UFW already blocks the port
-        // externally, but binding to all interfaces would expose the server to any
-        // misconfigured firewall rule. Override with HOST=0.0.0.0 if you ever need
-        // to expose it directly (e.g. for hosted environments behind a separate
-        // reverse proxy).
-        const HOST = process.env.HOST || "127.0.0.1";
-        httpServer.listen(PORT, HOST, () => {
-            console.error(`[madeonsol-mcp] HTTP server listening on ${HOST}:${PORT}`);
+        httpServer.on("error", () => {
+            console.error("[madeonsol-mcp] HTTP listener failed");
+            process.exitCode = 1;
+        });
+        httpServer.listen(httpConfig.port, httpConfig.host, () => {
+            console.error(`[madeonsol-mcp] HTTP server listening on ${httpConfig.host}:${httpConfig.port}/mcp (private operator only)`);
         });
     }
     else {
@@ -1446,5 +1420,8 @@ async function main() {
 // Only auto-run when executed as a program (CLI / spawned process), not when
 // the module is imported by a test for its exported pure helpers.
 if (process.env.MADEONSOL_MCP_NO_AUTORUN !== "1") {
-    main().catch(console.error);
+    main().catch(error => {
+        console.error(error instanceof Error ? error.message : "MCP startup failed");
+        process.exitCode = 1;
+    });
 }

package/dist/solana-payment.d.ts

@@ -0,0 +1,59 @@
+export declare const SOLANA_PAYMENT_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export declare const SOLANA_PAYMENT_ASSET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+interface ApprovedOffer {
+    scheme: "exact";
+    network: typeof SOLANA_PAYMENT_NETWORK;
+    asset: string;
+    payTo: string;
+    amount: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        feePayer: string;
+    };
+}
+interface ApprovedChallenge {
+    x402Version: 2;
+    resource: {
+        url: string;
+    };
+    accepts: ApprovedOffer[];
+}
+export interface SolanaPaymentProposal {
+    readonly url: string;
+    readonly network: string;
+    readonly asset: string;
+    readonly payTo: string;
+    readonly feePayer: string;
+    readonly amountAtomic: string;
+}
+export interface SolanaPaymentPolicy {
+    /** Trusted merchant wallet, obtained independently of a payment challenge. */
+    payTo: string;
+    /** Trusted facilitator wallet; must not be the paying agent's wallet. */
+    feePayer: string;
+    /** Positive atomic USDC integers (6 decimals); numbers are not accepted. */
+    maxAmountAtomic: string | bigint;
+    maxTotalAmountAtomic: string | bigint;
+    /** Explicit trusted HTTPS RPC; there is no public RPC fallback. */
+    rpcUrl: string;
+    /** Whole payment attempt deadline, default 30 seconds. */
+    timeoutMs?: number;
+    /** Optional additional approval; only literal true permits signing. */
+    beforePayment?: (proposal: SolanaPaymentProposal) => boolean | Promise<boolean>;
+}
+/** Lifetime authorization allowance, not settled spend. Share one long-lived instance.
+ * Retained after entering payment creation, including uncertain/failed outcomes.
+ */
+export declare class SolanaPaymentBudget {
+    #private;
+    readonly policy: Readonly<SolanaPaymentPolicy>;
+    constructor(policy: SolanaPaymentPolicy);
+    get authorizedAmountAtomic(): string;
+    select(envelope: unknown, requestUrl: string): ApprovedChallenge;
+    /** Atomic synchronous reservation before any approval/signing await. */
+    reserve(atomic: string): () => void;
+}
+export declare function solanaPaymentPolicyFromConfig(get: (key: string) => string | undefined): SolanaPaymentPolicy;
+/** One challenge and at most one paid request. No automatic payment replay. */
+export declare function createSolanaPaidFetch(privateKey: string, budget: SolanaPaymentBudget, baseUrl: string, transport?: typeof fetch): Promise<typeof fetch>;
+export {};

package/dist/solana-payment.js

@@ -0,0 +1,259 @@
+// Canonical source. Mirrored into the two Solana adapters by
+// packages/sync-solana-payment.mjs; CI rejects drift between published copies.
+export const SOLANA_PAYMENT_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export const SOLANA_PAYMENT_ASSET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+function fail(message) { throw new Error(`Solana payment policy: ${message}`); }
+const MAX_AMOUNT = (1n << 64n) - 1n;
+function amount(value) {
+    if (typeof value !== "bigint" && (typeof value !== "string" || !/^[1-9][0-9]{0,19}$/.test(value))) {
+        return fail("amount must be a positive atomic integer string or bigint");
+    }
+    const parsed = BigInt(value);
+    if (parsed <= 0n || parsed > MAX_AMOUNT)
+        return fail("amount exceeds uint64 range");
+    return parsed;
+}
+function wallet(value) {
+    if (typeof value !== "string" || !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value))
+        return fail("invalid wallet address");
+    const alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    let decoded = 0n;
+    for (const char of value)
+        decoded = decoded * 58n + BigInt(alphabet.indexOf(char));
+    const bytes = decoded === 0n ? 0 : Math.ceil(decoded.toString(16).length / 2);
+    if (decoded === 0n || bytes + (value.match(/^1*/)?.[0].length ?? 0) !== 32)
+        return fail("invalid wallet address");
+    return value;
+}
+function httpsUrl(value) {
+    if (typeof value !== "string")
+        return fail("invalid HTTPS URL");
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return fail("invalid HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash)
+        return fail("HTTPS URL without credentials or fragment required");
+    return url;
+}
+/** Lifetime authorization allowance, not settled spend. Share one long-lived instance.
+ * Retained after entering payment creation, including uncertain/failed outcomes.
+ */
+export class SolanaPaymentBudget {
+    policy;
+    #authorized = 0n;
+    #max;
+    #total;
+    constructor(policy) {
+        if (!policy)
+            fail("paymentPolicy is required for keyless payments");
+        const payTo = wallet(policy.payTo), feePayer = wallet(policy.feePayer);
+        this.#max = amount(policy.maxAmountAtomic);
+        this.#total = amount(policy.maxTotalAmountAtomic);
+        const rpcUrl = httpsUrl(policy.rpcUrl).href;
+        const timeoutMs = policy.timeoutMs ?? 30_000;
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647)
+            fail("invalid timeoutMs");
+        if (policy.beforePayment !== undefined && typeof policy.beforePayment !== "function")
+            fail("invalid beforePayment hook");
+        this.policy = Object.freeze({ payTo, feePayer, rpcUrl, timeoutMs,
+            maxAmountAtomic: this.#max.toString(), maxTotalAmountAtomic: this.#total.toString(), beforePayment: policy.beforePayment });
+    }
+    get authorizedAmountAtomic() { return this.#authorized.toString(); }
+    select(envelope, requestUrl) {
+        const challenge = envelope;
+        if (!challenge || challenge.x402Version !== 2 || !Array.isArray(challenge.accepts) ||
+            challenge.accepts.length < 1 || challenge.accepts.length > 32)
+            fail("unsupported payment challenge");
+        const request = httpsUrl(requestUrl);
+        if (challenge.resource !== undefined) {
+            const resource = httpsUrl(challenge.resource?.url);
+            // The current server advertises its path without the request query.
+            if (resource.origin !== request.origin || resource.pathname !== request.pathname ||
+                (resource.search && resource.search !== request.search))
+                fail("resource mismatch");
+        }
+        for (const offer of challenge.accepts) {
+            if (!offer || offer.scheme !== "exact" || offer.network !== SOLANA_PAYMENT_NETWORK ||
+                offer.asset !== SOLANA_PAYMENT_ASSET || offer.payTo !== this.policy.payTo ||
+                offer.extra?.feePayer !== this.policy.feePayer)
+                continue;
+            if (typeof offer.amount !== "string")
+                continue;
+            let cost;
+            try {
+                cost = amount(offer.amount);
+            }
+            catch {
+                continue;
+            }
+            if (cost > this.#max || !Number.isSafeInteger(offer.maxTimeoutSeconds) || offer.maxTimeoutSeconds <= 0)
+                continue;
+            // Rebuild instead of forwarding arbitrary remote fields/extensions to a signer.
+            const accepted = Object.freeze({ scheme: "exact", network: SOLANA_PAYMENT_NETWORK,
+                asset: SOLANA_PAYMENT_ASSET, payTo: this.policy.payTo, amount: cost.toString(),
+                maxTimeoutSeconds: offer.maxTimeoutSeconds, extra: Object.freeze({ feePayer: this.policy.feePayer }) });
+            return { x402Version: 2, resource: { url: request.href }, accepts: [accepted] };
+        }
+        return fail("no permitted exact mainnet USDC offer");
+    }
+    /** Atomic synchronous reservation before any approval/signing await. */
+    reserve(atomic) {
+        const cost = amount(atomic);
+        if (cost > this.#max || this.#authorized + cost > this.#total)
+            fail("authorization budget exceeded");
+        this.#authorized += cost;
+        let released = false;
+        return () => { if (!released) {
+            this.#authorized -= cost;
+            released = true;
+        } };
+    }
+}
+export function solanaPaymentPolicyFromConfig(get) {
+    const required = (name) => get(name) || fail(`${name} is required in keyless mode`);
+    return {
+        payTo: required("X402_PAY_TO"), feePayer: required("X402_FEE_PAYER"),
+        maxAmountAtomic: required("X402_MAX_AMOUNT_ATOMIC"), maxTotalAmountAtomic: required("X402_MAX_TOTAL_AMOUNT_ATOMIC"),
+        rpcUrl: required("SVM_RPC_URL"),
+    };
+}
+async function challengeBody(response) {
+    const header = response.headers.get("PAYMENT-REQUIRED");
+    if (header) {
+        if (header.length > 65_536)
+            fail("payment header too large");
+        // The protocol library decodes the header. Do not buffer an unrelated body.
+        void response.body?.cancel().catch(() => { });
+        return undefined;
+    }
+    if (!response.body)
+        return undefined;
+    const reader = response.body.getReader();
+    let size = 0;
+    const chunks = [];
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 65_536)
+                fail("payment challenge too large");
+            chunks.push(value);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return fail("invalid payment challenge JSON");
+    }
+}
+/** One challenge and at most one paid request. No automatic payment replay. */
+export async function createSolanaPaidFetch(privateKey, budget, baseUrl, transport = fetch) {
+    const origin = httpsUrl(baseUrl).origin;
+    const { x402Client, x402HTTPClient } = await import("@x402/core/client");
+    const { ExactSvmScheme } = await import("@x402/svm/exact/client");
+    const { createKeyPairSignerFromBytes } = await import("@solana/kit");
+    const { base58 } = await import("@scure/base");
+    const signer = await createKeyPairSignerFromBytes(base58.decode(privateKey));
+    if (signer.address === budget.policy.feePayer)
+        fail("the agent wallet cannot pay facilitator gas");
+    return async (input, init) => {
+        const original = new Request(input, init);
+        if (httpsUrl(original.url).origin !== origin)
+            fail("request origin mismatch");
+        if (original.headers.has("PAYMENT-SIGNATURE") || original.headers.has("X-PAYMENT"))
+            fail("payment already attempted");
+        const controller = new AbortController();
+        const deadline = Date.now() + budget.policy.timeoutMs;
+        const check = () => {
+            if (Date.now() >= deadline && !controller.signal.aborted)
+                controller.abort(new Error("Solana payment timeout"));
+            controller.signal.throwIfAborted();
+        };
+        const abort = () => controller.abort(original.signal.reason);
+        original.signal.addEventListener("abort", abort, { once: true });
+        if (original.signal.aborted)
+            abort();
+        const timer = setTimeout(() => controller.abort(new Error("Solana payment timeout")), budget.policy.timeoutMs);
+        let onAbort = () => { };
+        const cancelled = new Promise((_, reject) => {
+            onAbort = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        const bounded = async (work) => {
+            const result = await Promise.race([work, cancelled]);
+            check();
+            return result;
+        };
+        let release;
+        let creating = false;
+        try {
+            check();
+            const request = new Request(original, { redirect: "error", signal: controller.signal });
+            const retry = request.clone();
+            const response = await bounded(transport(request));
+            if (response.status !== 402)
+                return response;
+            const client = new x402Client();
+            const http = new x402HTTPClient(client);
+            const body = await bounded(challengeBody(response));
+            // v2 normally uses PAYMENT-REQUIRED; accept the same validated envelope
+            // in JSON too. The upstream HTTP decoder's body fallback is v1-only.
+            let envelope;
+            try {
+                envelope = response.headers.has("PAYMENT-REQUIRED")
+                    ? http.getPaymentRequiredResponse(name => response.headers.get(name))
+                    : body;
+            }
+            catch {
+                return fail("invalid payment challenge header");
+            }
+            const required = budget.select(envelope, request.url);
+            const offer = required.accepts[0];
+            release = budget.reserve(offer.amount);
+            if (budget.policy.beforePayment) {
+                const approved = await bounded(Promise.resolve(budget.policy.beforePayment(Object.freeze({ url: request.url,
+                    network: offer.network, asset: offer.asset, payTo: offer.payTo,
+                    feePayer: budget.policy.feePayer, amountAtomic: offer.amount }))));
+                if (approved !== true)
+                    fail("payment declined");
+            }
+            check();
+            // RPC work can finish after our deadline. Guard the actual signer too so
+            // an abandoned payment creation cannot sign later in the background.
+            const guardedSigner = { ...signer, signTransactions: async (...args) => {
+                    check();
+                    return signer.signTransactions(...args);
+                } };
+            client.register(SOLANA_PAYMENT_NETWORK, new ExactSvmScheme(guardedSigner, { rpcUrl: budget.policy.rpcUrl }));
+            creating = true;
+            const payload = await bounded(client.createPaymentPayload(required));
+            check();
+            for (const [name, value] of Object.entries(http.encodePaymentSignatureHeader(payload)))
+                retry.headers.set(name, value);
+            return await bounded(transport(retry));
+        }
+        finally {
+            if (!creating)
+                release?.();
+            clearTimeout(timer);
+            original.signal.removeEventListener("abort", abort);
+            controller.signal.removeEventListener("abort", onAbort);
+        }
+    };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.27.1";
+export declare const VERSION = "3.0.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED by ../gen-version.mjs (npm prebuild) from package.json. Do not edit.
-export const VERSION = "1.27.1";
+export const VERSION = "3.0.0";

package/glama.json

@@ -453,9 +453,6 @@
       "description": "Wallets that made (or lost) the most on a token, ranked by realized PnL or ROI, enriched with KOL/alpha-wallet identity."
     }
   ],
-  "transports": [
-    "stdio",
-    "http"
-  ],
+  "transports": ["stdio"],
   "runtime": "node"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-madeonsol",
-  "version": "1.27.1",
+  "version": "3.0.0",
   "mcpName": "io.github.MadeOnSol/madeonsol",
   "description": "MCP server for MadeOnSol Solana KOL intelligence API — use from Claude, Cursor, or any MCP client. Free tier 200 req/day (live feeds 5-min delayed; paid is real-time), no payment to start.",
   "type": "module",