It talks to Weakspot's agent path (/api/agent/audit), which has no accounts and no sign-in: payment itself is the authentication, over x402. That is why this needs a funded wallet rather than an API key.

This spends real money. weakspot_audit pays USDC on Base with no human in the loop — an LLM decides when to call it. Fund the wallet you configure here with only what you are willing to lose, and keep the WEAKSPOT_MAX_USD cap set.

What it costs

$1 per 10 files, rounded up, capped at 40 files per audit.

Files	Price
1–10	$1
11–20	$2
21–30	$3
31–40	$4

Setup

1. Install

Published to npm, so nothing needs cloning — npx fetches it on first run and the config in step 3 does that for you.

To run it from a checkout instead (developing on it, or pinning to your own fork):

cd integrations/mcp
pnpm install --ignore-workspace   # or: npm install

(--ignore-workspace matters: the repo root has a pnpm-workspace.yaml, and without it pnpm treats this directory as part of the root workspace and installs nothing here.)

2. Fund a wallet

Create a fresh wallet — do not reuse a personal or deployer key — and send it USDC on Base mainnet (0x8335…2913). $5–10 covers a good few audits. It needs no ETH: x402 settles via EIP-3009 transferWithAuthorization, so the facilitator pays the gas, not you.

3. Register the server with your client

Claude Code:

claude mcp add weakspot \
  --env WEAKSPOT_PRIVATE_KEY=0xyour_funded_key \
  --env WEAKSPOT_MAX_USD=4 \
  -- npx -y weakspot-mcp

Or add it to your MCP config directly (~/.claude.json, Cursor's mcp.json, etc.):

{
  "mcpServers": {
    "weakspot": {
      "command": "npx",
      "args": ["-y", "weakspot-mcp"],
      "env": {
        "WEAKSPOT_PRIVATE_KEY": "0xyour_funded_key",
        "WEAKSPOT_MAX_USD": "4"
      }
    }
  }
}

Running from a checkout instead: swap those two lines for "command": "node" and "args": ["/absolute/path/to/integrations/mcp/server.mjs"].

4. Check it

Ask your client: "what's my Weakspot wallet status?" — it should report the address and, if WEAKSPOT_RPC_URL is set, the USDC balance.

Configuration

Variable	Default	Purpose
`WEAKSPOT_PRIVATE_KEY`	—	Funded Base wallet. Required only for `weakspot_audit`; the other tools work without it.
`WEAKSPOT_MAX_USD`	`4`	Hard cap per audit. Checked twice: against the tier price, then again against the amount the server actually quotes.
`WEAKSPOT_URL`	`https://weakspot.dev`	Point at another deployment.
`WEAKSPOT_RPC_URL`	—	Base RPC, used only to read the USDC balance in `weakspot_wallet_status`.

Tools

Tool	Costs money	What it does
`weakspot_estimate_price`	no	Price a given file count before committing.
`weakspot_audit`	yes	Pays, uploads, returns a `jobId` immediately.
`weakspot_audit_status`	no	Poll a `jobId` for stage, then findings.
`weakspot_wallet_status`	no	Which wallet pays, and its balance.

weakspot_audit takes paths (read off disk — preferred) or files (inline), plus an optional description and verify.

Write a real description. It is the single biggest lever on false positives — "what this does, who is trusted, what must never happen" beats any amount of prompt tuning.

Leave verify on unless you want a deliberately noisy first look. It is a second adversarial pass that re-checks every finding against the actual code and drops what does not survive; on one test run it took 48 findings down to 7. It roughly doubles audit time.

How a session goes

Audits take minutes, not seconds, so the tool returns a jobId rather than blocking:

"Audit src/Vault.sol and src/Staking.sol — it's an ETH vault where users withdraw their own balance."
The client calls weakspot_audit, pays $1, gets a jobId.
It polls weakspot_audit_status until stage is done.
Findings come back with severity, file, lines, description and recommendation.

stage runs static-analysis → batches → verify → summary → done.

Troubleshooting

"WEAKSPOT_PRIVATE_KEY is not set" — expected until you configure a key. Pricing and polling still work.

"payment was rejected (still 402)" — nearly always an unfunded wallet. Run weakspot_wallet_status with WEAKSPOT_RPC_URL set to confirm the balance. It can also mean the authorization expired (maxTimeoutSeconds, 300s) — just retry.

"server quoted $N which exceeds WEAKSPOT_MAX_USD" — the safety cap did its job. Raise it deliberately if the price is genuinely expected.

"N files needs the $M tier" — a 400 raised before any payment is requested, so nothing was charged. The server picks price by route, so the file count must match the route; this server does that for you, and seeing this means the count changed underneath it.

Anything about X-Payment — the header is Payment-Signature. This server sends the right one, but if you are writing your own client, note that a wrong header name fails as a generic 402 that looks identical to sending no payment at all.

Privacy

Your source is uploaded to Weakspot and sent to an LLM for review. Job state is deleted about an hour after the audit finishes.

The jobId is a bearer credential — anyone holding it can read the full report at /audit/<jobId>. Those pages are noindex, but treat the id as a secret.

License

MIT — see LICENSE in this directory.

The licence covers this client only, not the rest of the repository it lives in. That is deliberate: this package is a thin client that drives Weakspot's public, paid API, so forking, vendoring or rewriting it is welcome and costs the service nothing. The Worker, the audit pipeline, the prompts and the contracts are a separate matter and carry no licence grant.