Mcp Protocol Tester

mcp-protocol-tester

[](https://safeskill.dev/scan/whiteknightonhorse-mcp-protocol-tester)

[](https://github.com/whiteknightonhorse/mcp-protocol-tester/actions/workflows/security-audit.yml) [](https://github.com/whiteknightonhorse/mcp-protocol-tester/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) [](https://github.com/whiteknightonhorse/mcp-protocol-tester/actions/workflows/security-audit.yml) [](https://github.com/whiteknightonhorse/mcp-protocol-tester/actions/workflows/security-audit.yml)

Universal test suite for MCP servers with dual-rail payment testing.

Tests x402 (USDC on Base) and MPP (USDC on Tempo) protocols simultaneously across all tools on any MCP-compatible server.

Features

• 20-phase test suite — 920+ assertions across discovery, payments, security, anti-abuse, and agent UX
• Dual-rail payment testing — x402 + MPP in parallel with cross-rail price validation
• Full MCP protocol validation — initialize, tools/list, tools/call, resources/list, prompts/list, version negotiation
• 402 challenge validation — every tool checked for correct payment challenge fields (payTo, network, asset, amount)
• Payment security — replay attacks, race conditions, double-spend, amount manipulation, stale challenges
• Advanced security — SSRF, timing attacks, CORS, header injection, fuzz testing, response analysis
• Payment bypass prevention — replay, double-spend 100x, signed underpayment, cache leak, MCP session abuse, cross-rail nonce
• Resilience testing — brute force, SSL/TLS cipher/cert validation, enumeration, error cascade
• Load testing — ramp-up stress, latency percentiles (p50/p95/p99), sustained load
• Tool discovery — discover_tools prompt validation, stemming, category enumeration, abuse testing
• Platform features — usage analytics, tool quality index, batch API, cross-feature validation
• Agent experience — zero-knowledge bootstrap, description quality, error actionability, E2E lifecycle
• Provider health map — per-provider status and latency tracking
• Universal — works with ANY MCP server, not just APIbase
• Scoring — 0-100 score with A+/A/B/C/D/F grade
• CI-ready — GitHub Actions with TruffleHog, Gitleaks, CodeQL, Snyk
• Zero build — plain Node.js, no TypeScript compilation needed

Quick Start

git clone https://github.com/whiteknightonhorse/mcp-protocol-tester.git
cd mcp-protocol-tester
npm install
cp .env.example .env
# Edit .env with your server URL and wallet keys
npm test

Usage

# Full dual-rail test (all 20 phases)
npm test

# Dry run — no real payments, tests challenges and security only
npm run test:dry

# Fast mode — discovery + infrastructure + MCP only
npm run test:fast

# Security audit (basic + payment + advanced + resilience)
npm run test:security

# Payment tests only
npm run test:payments

# Custom server
API_BASE_URL=https://my-server.com npm test

# Specific phases
PHASES=0,1,7,8,9,10 npm test

# Load test with 10 concurrent requests
CONCURRENCY=10 npm test

Scoring

| Grade | Score | Meaning | |-------|---------|------------------------------------------| | A+ | 97-100 | Production-ready, all protocols verified | | A | 93-96 | Excellent, minor recommendations | | A- | 90-92 | Very good, few non-critical issues | | B+ | 87-89 | Good, some improvements needed | | B | 83-86 | Functional, recommendations available | | B- | 80-82 | Acceptable, notable gaps | | C | 70-79 | Basic functionality, significant gaps | | D | 60-69 | Critical issues found | | F | Note: Any CRITICAL (500) server error automatically caps the grade at D. Skipped phases score 0%.

Phases (20)

| Phase | Name | What it tests | Cost | |-------|--------------------|-----------------------------------------------------------------------|---------| | P0 | Discovery | Catalog fetch, schema validation, .well-known/*, dual-rail detection, internal tool leak check, well-known CORS | $0 | | P1 | Infrastructure | Health, Tempo/Base RPC, USDC + gas balances, facilitator, health info leakage check | $0 | | P2 | MPP Challenges | WWW-Authenticate: Payment on all tools + field validation (recipient, amount, chainId) | $0 | | P3 | x402 Challenges | x402 402 body on all tools + field validation (payTo, network, asset, scheme, multi-accept), challenge nonce uniqueness | $0 | | P4 | MCP Protocol | initialize, tools/list, tools/call, resources/list, prompts/list, version negotiation, JSON-RPC error codes, session fixation, oversized payload, ID type handling | $0 | | P5 | MPP Payments | Real Tempo USDC payments via mppx + response content validation | ~$0.01 | | P6 | x402 Payments | Real Base USDC payments via @x402/core + response content validation | ~$0.05 | | P7 | Basic Security | Auth bypass, forged credentials, HTTP method enforcement + override bypass, Content-Type manipulation, request ID, path traversal, expanded hidden endpoints (+10), request smuggling | $0 | | P8 | Payment Security | Replay (same/cross-tool), race condition (10 parallel), double-spend, amount manipulation (0/negative/underpay/tampered payTo/integer overflow 2^64), float precision, off-by-one (999 vs 1000), expired challenge, wrong network (testnet→mainnet), cross-rail price consistency | ~$0.01 | | P9 | Advanced Security | SSRF (AWS/GCP/localhost/file:// + IPv6/octal/decimal), timing attacks, CORS + subdomain confusion + expose-headers audit, header injection (CRLF/64KB/Host), fuzz (null bytes/unicode/JSON bomb/prototype pollution), XXE injection, SSTI payloads, ReDoS, response analysis | $0 | | P10 | Resilience | Brute force (50 keys), XFF + 5 IP spoofing headers bypass, SSL/TLS version + cipher + cert expiry + TLSv1.1 rejection, enumeration, error cascade, referrer-policy, rate limit granularity (per-key) | $0 | | P11 | Load Test | Concurrent requests, mixed endpoints, sustained load, latency p50/p95/p99, ramp-up (1→5→10→25), large body DoS (1MB) | $0 | | P12 | Provider Health | 1 tool per provider → HEALTHY/DOWN/RATELIMITED + latency, provider error sanitization | $0 | | P13 | Cache & Simulation | Cache isolation, cache leak test, cache poisoning (X-Forwarded-Host), cache key collision, User-Agent/Accept variation, REST+MCP simultaneous, error schema | $0 | | P14 | Discover Tools | Category enumeration (21 cats), category+task combos, stemming, keyword relevance, abuse (SQLi/XSS/unicode/10k chars), truncation, performance | $0 | | P15 | Platform Features | Usage Analytics (account.usage/tools/timeseries), Tool Quality Index (toolquality/rankings), Batch API (callbatch + REST), recursive batch, batch toolid injection, cross-feature validation | $0 | | P16 | Agent Experience | Zero-knowledge bootstrap, tool description quality, error actionability (400/402/429), payment UX, response consistency, E2E lifecycle (golden path), MCP protocol completeness, error path leakage | $0 | | P17 | Payment Bypass | MCP session payment enforcement, replay after 30s delay, signed underpayment, pay-cheap-use-expensive, cache leak across keys, price consistency, MCP batch abuse, header case/duplication, Content-Type bypass, prototype pollution, session ID entropy, double-spend 100x, cross-rail nonce, cross-chain replay, WebSocket upgrade bypass, burst 50 unpaid, chunked encoding bypass, nonce entropy | ~$0.01 | | P18 | CDP Facilitator | PayAI health + Base mainnet + Bazaar extension, CDP auth-gated, 402 wallet/network/asset/version consistency across tools, MPP dual-rail header, health/catalog/free/paid architecture checks, facilitator TLS, wallet constant | $0 | | P19 | Report | Score, grade, per-phase breakdown, recommendations, txt + JSON export | $0 |

Total estimated cost: ~$0.07 per full run.

Environment Variables

| Variable | Required | Default | Description | |-------------------|----------|-------------------------------------|--------------------------------------| | API_BASE_URL | Yes | https://apibase.pro | Target server base URL | | MCP_SERVER_URL | No | {API_BASE_URL}/mcp | MCP endpoint URL | | API_KEY | No | (none) | API key for authenticated requests | | PRIVATE_KEY | No* | (none) | Wallet private key for payments | | CONCURRENCY | No | 5 | Parallel requests in load test | | SKIP_PAYMENTS | No | false | Skip real payment tests | | PHASES | No | 0,1,2,...,15 (all) | Comma-separated phase numbers | | MAX_TOOLS | No | 0 (all) | Max tools to test (0 = unlimited) | | TIMEOUT_MS | No | 30000 | Per-request timeout in ms | | MAX_USDC_BUDGET | No | 0.25 | Spending cap per protocol |

> \* PRIVATE_KEY is required only for payment phases (P5, P6, P8). The same key works on both Base and Tempo chains.

Testing Your Own MCP Server

1. Your server must support MCP protocol (Streamable HTTP at /mcp)
2. For payment tests: server must return HTTP 402 with payment challenge
3. Set API_BASE_URL in .env to your server
4. Optional: set PRIVATE_KEY for real payment tests
5. Run npm test

Minimum server requirements for each phase:

| Phase | Server must support | |-------|-------------------------------------------------------------------------------| | P0 | GET /api/v1/tools + /.well-known/mcp.json | | P1 | GET /health/ready | | P2 | HTTP 402 with WWW-Authenticate: Payment header | | P3 | HTTP 402 with x402 JSON body (x402Version: 2, accepts array) | | P4 | MCP Streamable HTTP (POST /mcp) with initialize, tools/list, tools/call | | P5 | MPP payment verification via mppx | | P6 | x402 payment verification via @x402/core | | P7-P10| Standard REST API (any MCP server) | | P11 | Any HTTP endpoint | | P12 | POST /api/v1/tools/{id}/call | | P13 | REST + MCP endpoints | | P14 | MCP prompts/get with discover_tools prompt | | P15 | Platform tools: account.usage, platform.tool_quality, platform.call_batch | | P16 | .well-known/* discovery, MCP session, tool descriptions, error messages |

Reports

Reports are saved to reports/ directory (git-ignored). Each run creates:

• dual-rail-report-YYYYMMDD_HHMMSS.txt — human-readable text
• dual-rail-report-YYYYMMDD_HHMMSS.json — machine-readable JSON

JSON report structure:

{
  "timestamp": "2026-03-27T09:00:00.000Z",
  "server": "https://apibase.pro",
  "score": 85,
  "grade": "B",
  "assertions": { "total": 920, "pass": 890, "fail": 30 },
  "financial": { "x402": 0.05, "mpp": 0.01 },
  "errors": [],
  "recommendations": [],
  "failures": []
}

Payment Protocols

x402 (USDC on Base)

Standard HTTP 402 payment protocol. Client sends request, gets 402 with payment requirements (accepts array with network, asset, payTo, scheme, amount), signs USDC transfer on Base chain, retries with X-Payment + PAYMENT-SIGNATURE headers.

Validation: P3 checks every tool's 402 response for correct payTo address, network (eip155:8453), asset (USDC contract), and reasonable amount. Multi-accept entries are all validated.

MPP (USDC on Tempo)

Machine Payments Protocol by Stripe/Tempo. Client sends request, gets 402 with WWW-Authenticate: Payment header containing challenge (id, realm, method, intent, request, expires), signs payment on Tempo chain via mppx SDK, retries with Authorization: Payment .

Validation: P2 checks every tool for correct recipient, chainId (4217), and reasonable amount. P8 validates cross-rail price consistency (x402 vs MPP amounts must match).

Both protocols can coexist on the same server — this tester verifies both work correctly and consistently.

Security

This tool is safe to use

| Check | Status | How | |-------|--------|-----| | No hardcoded secrets | Verified on every commit | TruffleHog + Gitleaks scan | | No code vulnerabilities | Verified on every commit | GitHub CodeQL static analysis | | No dependency vulnerabilities | Weekly scan | npm audit + Snyk | | No data exfiltration | Verified on every commit | Custom scan for eval(), child_process, suspicious fetch calls | | No secret logging | Verified on every commit | Grep for console.log with env vars | | Private keys stay local | .env in .gitignore | Keys never leave your machine | | No telemetry | By design | Zero analytics, zero tracking, zero external calls except target server | | Open source | MIT license | Full source code available for audit |

What this tool tests on YOUR server

| Category | Tests | What it looks for | |----------|-------|-------------------| | Payment Replay | 5 | Reused payment signatures (same tool, cross-tool, modified body) | | Double-Spend | 2 | 10 + 100 parallel requests with same payment | | Amount Manipulation | 8 | Zero, negative, underpay, tampered payTo, float precision, integer overflow (2^64), off-by-one (999 vs 1000), wrong network (testnet→mainnet) | | SSRF | 7 | AWS/GCP metadata, localhost, file://, IPv6 [::1], octal 0177.0.0.1, decimal 2130706433 | | Timing Attacks | 2 | Valid vs invalid key timing differential | | CORS | 5 | Evil origin, null origin, preflight with credentials, subdomain confusion, expose-headers audit | | Header Injection | 4 | CRLF in auth, 64KB header, Host override, request smuggling (CL+TE) | | Fuzz | 5 | Null bytes, unicode, JSON bomb, prototype pollution, MAXSAFEINTEGER | | XXE/SSTI | 4 | XML entity injection, template injection {{7*7}}, ${7*7}, `` | | Brute Force | 3 | 50 random keys, XFF bypass, lockout recovery | | IP Spoofing | 5 | X-Real-IP, X-Client-IP, CF-Connecting-IP, True-Client-IP, Forwarded | | SSL/TLS | 4 | Protocol version, cipher strength, certificate expiry, TLSv1.1 rejection | | Enumeration | 4 | Uniform errors, hidden endpoints (+10 paths), tool ID injection, path traversal | | Response Analysis | 4 | Stack trace leaks, X-Powered-By, Server header, internal path leakage | | MCP Session | 4 | Payment enforcement, batch abuse, session fixation, oversized payload | | Cache | 4 | Cross-key leak, cache headers, cache poisoning (X-Forwarded-Host), cache key collision | | Signed Underpayment | 1 | Valid signature with tampered amount | | Cross-Tool Price | 1 | Cheap tool payment used for expensive tool | | Cross-Chain Replay | 2 | Tempo nonce as x402, cross-chain payment proof | | Double-Spend 100x | 1 | 100 parallel requests with single payment | | Replay After Delay

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: whiteknightonhorse
• Source: whiteknightonhorse/mcp-protocol-tester
• License: MIT
• Homepage: https://apibase.pro

Install and usage instructions live in the source repository linked above.