lock-smith-mcp

Standalone home: QuincyGB/lock-smith-mcp — sibling of the fleet's token-verdict-mcp, route-verdict-mcp and list-smith-mcp wrappers.

MCP server for LockSmith — an automated security audit for x402 endpoints, sold pay-per-call over x402: $0.50 USDC on Base, no account, no API key. Give it the URL of a paid x402 route and it reports whether that endpoint would pass an informed buyer's security screen — paywall presence, challenge sanity, garbage/forged payment rejection, exposure surface (.env/.git/debug paths), error hygiene, body caps, discovery consistency — as a SECURE / FINDINGS / EXPOSED verdict with per-check evidence.

Scope, stated plainly: these are automated security checks run with unpaid probes only — not a penetration test, and a SECURE verdict is not a guarantee. It is a fast, cheap, repeatable screen.

This package gives any MCP host (Claude Desktop, Cursor, …) a native lock_audit tool that handles the full x402 v2 payment flow itself — 402 challenge → EIP-3009 TransferWithAuthorization signature (USDC on Base, EIP-712) → paid retry — using your agent wallet.

Tools

Related MCP server: x402-gateway-mcp

Install

pip install lock-smith-mcp
# or run without installing:
uvx lock-smith-mcp

Configuration

All configuration is environment variables — set them on the MCP server process in your host's config. Your key never leaves your machine; the service only ever sees a signed payment authorization.

Without a signer the tool never pays. It returns the parsed 402 challenge as a structured error — {"error": "payment_required", "accepts": […], …} — so the calling agent can see the exact price, asset, network and payTo and decide what to do. With a signer, charges above the spend guard are likewise refused before signing.

MCP host config

{
  "mcpServers": {
    "lock-smith": {
      "command": "uvx",
      "args": ["lock-smith-mcp"],
      "env": {
        "AGENT_PRIVATE_KEY": "0xYOUR_AGENT_WALLET_KEY"
      }
    }
  }
}

The endpoint being wrapped

POST https://lock-smith-production.up.railway.app/v1/audit
{"endpoint_url": "https://token-verdict-production.up.railway.app/v1/verdict"}
→ 200 {"ok": true, "service": "lock-smith", "audit_version": "1.0.0",
      "target": {...}, "verdict": "SECURE",
      "summary": {"passed": 8, "findings": 0, ...},
      "checks": [{"id": "paywall_present", "status": "pass", ...}, ...],
      "scope_note": "Automated security checks, not a penetration test. ..."}

The schemas in src/lock_smith_mcp/schemas.py are copied verbatim from the service's own discovery document (/.well-known/x402) — the published contract, not a paraphrase.

Development

pip install -e ".[dev]"
pytest

Tests mock the HTTP layer and use a throwaway signer generated at test time — no network, no real money, no key material in the repo. The 402 fixture in tests/fixtures/ is real: captured from an unpaid probe of production on 2026-10-27.

License

MIT