mcp-x402 — The First MCP Server That Pays for Itself

Demo video: 30-second walkthrough — coming within 48h of launch.

AI agents should pay for their own data — instantly, autonomously, compliantly. mcp-x402 makes that real.

npx @scriptmasterlabs/mcp-x402

Why MCP Servers Are Broken (The Manifesto)

Every MCP server connecting to paid APIs today requires:

• A human to set up API keys
• A human to manage billing
• A human to top up credits when they run out
• A human to rotate keys when they expire

This defeats the entire point of autonomous agents. If your agent has to stop and ask a human for a credit card, it's not autonomous — it's a very expensive chatbot.

We built the machine-native alternative.

mcp-x402 is the first MCP server where agents provision their own wallets, negotiate prices on-chain, pay autonomously, and receive cryptographic receipts — all without human intervention. The agent's credit score goes up every time it successfully transacts. It builds financial reputation the same way humans do.

This is the infrastructure layer that makes truly autonomous AI agents possible.

One-Line Install

npm i -g @scriptmasterlabs/mcp-x402

Add to your Claude Code ~/.claude/config.json:

{
  "mcpServers": {
    "sml": {
      "command": "npx",
      "args": ["@scriptmasterlabs/mcp-x402"]
    }
  }
}

For Cursor (SSE mode), add to your MCP settings:

{
  "mcp-x402": {
    "url": "http://localhost:3402/sse"
  }
}

Then run: MCP_TRANSPORT=sse npx @scriptmasterlabs/mcp-x402

Architecture

Claude / Cursor
     │
     ▼ MCP Protocol (stdio / SSE)
  mcp-x402 Server
     ├─ Input validation (Zod, 100% coverage)
     ├─ Rate limiter (100/min per tool)
     ├─ AP2 Mandate check (deny-by-default)
     ├─ Credit Bureau check (min score 300)
     ├─ Price registry (60s max cache)
     ├─ x402 payment engine
     │    ├─ Base USDC (preferred, <3s)
     │    ├─ XRPL RLUSD (500ms fallback)
     │    └─ Solana USDC (last resort)
     ├─ 402Proof receipt generation
     ├─ SML API call (mTLS)
     └─ Append-only SHA-256 audit log
     │
     ▼ Result + receipt_id back to agent

The 6 Tools

leviathan_signal — $0.05 USDC | AP2 required

Institutional-grade squeeze signals. Multi-engine verdict (OracleEngine + RDT + SML Fractal Cascade).

await use_mcp_tool('sml', 'leviathan_signal', {
  ticker: 'MSTR',
  signal_type: 'squeeze',
  min_confidence: 75
});
// Returns: signal verdict + confidence + receipt_id

xmit_edgar_decode — $0.02 USDC | AP2 required

Parse SEC DEF 14A / 13F / 13D filings. Raw text never leaves SML servers.

await use_mcp_tool('sml', 'xmit_edgar_decode', {
  filing_url: 'https://www.sec.gov/Archives/edgar/data/...',
  parse_target: 'executive_pay',
  format: 'json'
});

xdeo_earnings_estimate — $0.02 USDC | AP2 required

Decentralized earnings oracle. Earns +2 Credit Bureau points per successful call.

await use_mcp_tool('sml', 'xdeo_earnings_estimate', {
  ticker: 'NVDA',
  fiscal_quarter: 'Q12025',
  estimate_type: 'all'
});

ftd_threshold_scan — Alerts FREE / Full $0.05 USDC

SEC Reg SHO FTD spike detection. 15-minute cache.

// Free tier:
await use_mcp_tool('sml', 'ftd_threshold_scan', { scan_type: 'alerts' });
// Paid tier:
await use_mcp_tool('sml', 'ftd_threshold_scan', { scan_type: 'full', min_spike_multiplier: 3 });

nexus_agent_hire — Query FREE / Hire 5% commission

Agent marketplace. Find and hire specialized AI agents.

// Free query:
await use_mcp_tool('sml', 'nexus_agent_hire', { capability: 'options flow analysis', max_budget: '1.00', action: 'query' });
// Hire:
await use_mcp_tool('sml', 'nexus_agent_hire', { action: 'hire', agent_id: 'agent_abc', max_budget: '0.50' });

crawl_paid_fetch — $0.005 USDC

Pay-per-fetch web scraping. Humans bypass automatically.

await use_mcp_tool('sml', 'crawl_paid_fetch', {
  url: 'https://example.com/data',
  extract: 'tables'
});

Payment Flow

1. Discover — Agent reads agents.json or llms.txt, sees tool prices
2. Authorize — AP2 mandate checked. Credit Bureau score ≥ 300 auto-approves
3. Pay — x402 stablecoin on cheapest/fastest chain (<3s on Base)
4. Prove — 402Proof receipt in every response
5. Earn — Credit Bureau score updates after success

Every successful tool call returns a _meta block:

{
  "_meta": {
    "receipt_id": "uuid-here",
    "tx_hash": "0xabc...",
    "chain": "base",
    "amount_paid": "0.05 USDC",
    "timestamp": 1750000000000
  }
}

SDK — For MCP Server Authors

Install in one line:

npm i @scriptmasterlabs/mcp-x402-sdk

Drop into any MCP server in 5 lines:

import { x402Payment } from '@scriptmasterlabs/mcp-x402-sdk';

server.tool(
  'my_paid_tool',
  myInputSchema,
  x402Payment({
    price: '0.01',
    currency: 'USDC',
    inputSchema: MyZodSchema,
    handler: async (input, receipt) => ({
      content: [{ type: 'text', text: JSON.stringify({ result: await myApi(input), receipt }) }],
    }),
  }),
);

That's it. The SDK handles wallet provisioning, AP2 mandate, chain routing, receipts, and audit logging.

Security

| Requirement | Implementation | |-------------|----------------| | Keys in OS keychain only | keytar — macOS Keychain / Windows DPAPI / Linux Secret Service | | mTLS on SML APIs | Pinned cert via node-forge | | No PII in logs | Wallet addresses hashed (SHA-256 prefix), filing content redacted | | Zod on all inputs | 100% coverage, validated before any execution | | Append-only audit log | SHA-256 HMAC chained log, 7-day local + cloud backup | | AP2 mandate required | Verified before every paid call, fail-closed | | 402Proof receipt | Every transaction, registered with proof server | | Credit Bureau check | min score 300 for auto-approve | | $50 daily spend cap | Per wallet, enforced in-process | | Testnet in CI | Base Sepolia only, max $0.10 test value | | <3s end-to-end | Base mainnet target, 500ms multi-chain fallback |

Environment Variables

See .env.example for the full list. Key variables:

MCP_TRANSPORT=stdio          # stdio (Claude Code) or sse (Cursor/remote)
SML_API_BASE=https://api.scriptmasterlabs.com
BASE_RPC_URL=https://mainnet.base.org
XRPL_RPC_URL=wss://xrplcluster.com
DAILY_SPEND_CAP_USD=50
AUTO_APPROVE_THRESHOLD_USD=1
TESTNET=false                # Set true + CI_WALLET_SEED for CI

Private keys: Stored in your OS keychain automatically on first run. Never in env vars.

Running Locally

git clone https://github.com/timwal78/sml_portfolio
cd mcp-x402
npm install
npm run build
npm start

With Docker:

docker build -t mcp-x402 .
docker run -p 3402:3402 -e MCP_TRANSPORT=sse mcp-x402

Testing

npm test              # All unit tests
npm run test:coverage # Coverage report (target: 90%)
TESTNET=true CI_WALLET_SEED="your mnemonic" npm run test:integration

Ecosystem

| Service | URL | Role | |---------|-----|------| | SqueezeOS API | squeezeos-api.onrender.com | Market intelligence | | 402Proof | four02proof.onrender.com | Payment receipts + Credit Bureau | | Ghost Layer | ghost-layer.onrender.com | XRPL+Base toll gateway | | ScriptMasterLabs | scriptmasterlabs.com | Operator homepage |

MOAT

• Only MCP server with live x402 + AP2 + multi-chain production stack
• Only one with Agent Credit Bureau (300–850 scores)
• Only one backed by live financial intelligence marketplace
• Only one with SDVOSB federal credibility
• MIT licensed. No proprietary core.

License

MIT — see LICENSE

Owner: @TimmyCrypto78 / ScriptMasterLabs
Launch Target: 2026-07-02
Target: 50K GitHub stars, 5K npm weekly downloads