DEV Community

Eidon Ze
Eidon Ze

Posted on

Five read-only diagnostic CLIs for AI agents on Web3 (x402, MCP, Solana)

#web3 #ai #solana #npm

AI agents are starting to pay for things (x402, USDC per call on Solana and Base). That creates two failure modes nobody has good tooling for:

  1. The endpoint answers the wrong thing. An x402 endpoint that returns 400 instead of 402, or a payment document missing payTo, breaks every agent that touches it — usually silently.
  2. Nobody can prove what was delivered. An agent pays, gets a response, and has no independent evidence of what the seller actually delivered.

I kept running into both, so I built a suite of five read-only diagnostic CLIs — and released them all on npm this week. They share one philosophy: CLI-first, no private keys, no auto-payments, JSON output, PASS / FAIL / UNKNOWN, and every tool documents what it does not cover.

Suite index with all commands: https://x402-endpoint-inspection.app.workbuddy.host/tools.html

The five tools

1. mcpdoctor — is your MCP/x402 endpoint discoverable? 

npx mcpdoctor inspect https://your-endpoint/mcp --json
Enter fullscreen mode Exit fullscreen mode

Checks the HTTP 402 payment document (headers and body), MCP initialize, tools/list, and every tool's name, description, inputSchema, and required fields. One real bug it caught during development: an endpoint advertising a vendor hint header with no accepts[] — which shadowed the real payment document.

2. x402-reconcile — what does an x402 endpoint demand? 

npx x402-reconcile inspect https://api.example.com/paid --method=POST --json
Enter fullscreen mode Exit fullscreen mode

Parses the 402 challenge: scheme (exact/base), network (CAIP-2), asset, amount, payTo, timeout — plus response latency and a SHA-256 of the raw response bytes. Verified against a real public endpoint (a notary service returning 402 / exact / USDC / amount 1000). It never signs or pays anything — settlement and delivery stay explicitly NOT_TESTED.

3. oauthdoctor — can an agent even discover your OAuth metadata? 

npx oauthdoctor inspect https://mcp.example.com/mcp --json
Enter fullscreen mode Exit fullscreen mode

Walks the MCP authorization discovery flow: unauthenticated request → 401 challenge → WWW-Authenticate resource_metadata → Protected Resource Metadata → Authorization Server Metadata → PKCE S256 declaration. Discovery-only by design: no login, no token exchange, no stored credentials.

4. wallet-evidence — what does one Solana RPC actually see? 

npx wallet-evidence inspect <signature> --rpc=https://api.mainnet-beta.solana.com --json
Enter fullscreen mode Exit fullscreen mode

Slot, block time, execution error, parsed instructions, fee — and a SHA-256 of the raw RPC response so the report is re-checkable. The interesting finding while testing: the same transaction signature was visible on one public RPC and not found on another. The tool therefore returns UNKNOWN when an RPC can't see a transaction — it never conflates that with "the transaction does not exist."

5. crosschain-incident — normalize a cross-chain incident export 

npx crosschain-incident inspect --input ./message.json --json
Enter fullscreen mode Exit fullscreen mode

Takes operator-supplied source/destination status JSON and produces a conservative evidence report. Missing fields stay UNKNOWN; failures become machine-readable findings. Protocol APIs (LayerZero/Hyperlane) are the roadmap — today it's an offline formatter and says so.

The honest part

Only parts of this stack have real-world validation so far, and the tools label their own coverage. Examples: x402-reconcile has parsed one real public 402 challenge but has never verified a settlement; oauthdoctor passes local positive/negative fixtures but hasn't met a public OAuth-protected MCP endpoint yet. The ReceiptRail MCP service behind the suite has its declared core (initialize, ping, tools/list) passing the official MCP conformance tests — not full-conformance, and it doesn't claim to be.

Every README has a "NOT covered" section. If a claim isn't backed by a test or a real observation, it's not in the report.

Try it

All five are one npx away, MIT licensed, zero runtime dependencies:

npx mcpdoctor inspect https://your-endpoint/mcp --json
Enter fullscreen mode Exit fullscreen mode

Suite index: https://x402-endpoint-inspection.app.workbuddy.host/tools.html

If you run an x402 endpoint and want a human inspection of the full payment-to-delivery path (not just the challenge), that's the manual service the suite grew out of: https://x402-endpoint-inspection.app.workbuddy.host/

Top comments (0)