x402lint MCP server
Commit Oct 29, 2026Lints x402 endpoint unpaid paths to identify potential client or directory integration issues before deployment.
Also known as something-agent/x402lint
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.0
- Last commit
- Oct 29, 2026
- License
- MIT
What is x402lint MCP?
x402lint lints x402 endpoint unpaid paths to identify potential client or directory integration issues before deployment.
Summary generated from the project's README
About x402lint MCP server
Identifying potential integration issues in x402 endpoint unpaid paths is what this tool enables for developers before they announce a new service. It acts as a read-only linter that examines how a client or directory might interact with a paid URL. By analyzing the unpaid path, it flags errors in challenge formats, transport methods, and discovery files without ever attempting to sign or settle a payment.
Users can interact with the service via a remote MCP implementation at the /mcp endpoint or through a direct HTTP API. The server performs checks on specific rules including x402Version, CAIP-2 network requirements, EIP-55 checksums, and CORS configurations. It also verifies directory readiness for platforms like the CDP/PayAI Bazaar by checking for bazaar extensions and schema descriptions.
Because this is a free, unpaid service, it cannot test settlement or on-chain transfers. For testing those specific seller-side failures like paid-replay or response delivery, developers must use the separate paidpath CLI. The linter is limited to approximately six subrequests per call and a 256 KB read limit per response.
What you can do with it
- 1Validate x402 endpoint configurationCheck if an x402 endpoint correctly handles GET and POST methods and adheres to transport rules.
- 2Verify directory listing readinessDetermine if an endpoint meets the specific requirements to be listed in a directory like the CDP/PayAI Bazaar.
- 3Lint manual payment challengesAnalyze a specific payment-required header without making a network request to the host.
Written from the project's README. Every use case is checked against a quote from it.
How to install x402lint MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall x402lint MCP in Claude Code
$ claude mcp add --transport http x402lint https://x402lint.something-agent.workers.dev/mcpInstall x402lint MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"x402lint": {
"url": "https://x402lint.something-agent.workers.dev/mcp"
}
}
}Install x402lint MCP in VS Code
.vscode/mcp.json
{
"servers": {
"x402lint": {
"type": "http",
"url": "https://x402lint.something-agent.workers.dev/mcp"
}
}
}Install x402lint MCP in VS Code CLI
$ code --add-mcp '{"name":"x402lint","type":"http","url":"https://x402lint.something-agent.workers.dev/mcp"}'Install x402lint MCP in Codex
$ codex mcp add x402lint --url https://x402lint.something-agent.workers.dev/mcpInstall x402lint MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.x402lint] url = "https://x402lint.something-agent.workers.dev/mcp"
Install x402lint MCP in Gemini CLI
$ gemini mcp add -s user --transport http x402lint https://x402lint.something-agent.workers.dev/mcpInstall x402lint MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"x402lint": {
"url": "https://x402lint.something-agent.workers.dev/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesomething-agent/x402lint is public and reachablegithub.com/something-agent/x402lint ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-29github.com/something-agent/x402lint ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 80 msPass
README
View on GitHubx402lint
Free, read-only linter for the unpaid path of an x402 endpoint. Point it at a paid URL and it tells you what a client or a directory would trip over, before you announce it. It never pays and never signs, so it cannot test settlement.
- Live: https://x402lint.something-agent.workers.dev (HTTP API + remote MCP at
/mcp,/llms.txt,/openapi.json) - Official MCP Registry name:
io.github.something-agent/x402lint - Paid path: paidpath, a CLI you run against your OWN endpoint with your own key (settlement, on-chain transfer, delivery, replay and underpayment rejection). Same lint rules locally, so it also works for
*.workers.devhosts this Worker cannot reach. - Sibling: ProofCheck (signed offers and receipts)
curl -H 'user-agent: me/1.0' 'https://x402lint.something-agent.workers.dev/v1/lint?url=https://mart402.com/v1/extract'
What it checks (rule ids at /v1/rules)
- Challenge: x402Version, accepts[] required fields (v2
amount, v1maxAmountRequired), CAIP-2network, testnets,payToformat (EIP-55 checksum, zero/burn, equals the asset contract, Solana base58 length), amount is an integer in base units (and price for known USDC), asset/network pair, EIP-712extra.name/extra.versionfor EIP-3009 USDC (and known-USDC values),maxTimeoutSeconds, v2resource, bazaar extension, header vs body delivery. - Transport: GET vs POST both answer 402 and agree, redirects, plain http, cacheable 402, content-type, slow challenge, CORS (expose
PAYMENT-REQUIRED, preflight allowsPAYMENT-SIGNATURE). - Discovery:
/.well-known/x402payTo agrees with the live challenge,/llms.txt,/openapi.json; X133 when only one of the GET/POST 402s carries the bazaar extension. - Directory readiness (v0.2.0,
/v1/directories): per directory, what it was known to check before listing, with the source and date. x402dash: unpaid GET must return 402. x402scan: runtime v2 402, discovery via/openapi.jsonx-payment-infoor/.well-known/x402, an input schema. the402: validator verdict "payable" (v2 header challenge, no errors). CDP/PayAI Bazaar:extensions.bazaarwith input/output and schema, description ≤ 500 chars, non-tunnel https host; then one settled payment through their facilitator (statusneeds_payment). "Ready" means it passes those checks, not that it will be listed. - When both GET and POST return a 402, the challenge whose bazaar extension declares the method is the one linted.
API
GET /v1/lint?url=<paid URL>[&method=auto|GET|POST]fetch and lint.POST /v1/lint/payment-required{"payment_required": <object | JSON string | base64 PAYMENT-REQUIRED header>, "url"?}lint a challenge you hold, no network.GET /v1/directories?url=<paid URL>(or/v1/lint?...&directories=1) lint plus adirectories[]array{directory, status: ready|not_ready|needs_payment, checks[], note, source}.POST /mcpStreamable HTTP MCP (stateless):lint_x402_endpoint,check_directory_readiness,lint_payment_required.- Output:
{verdict: ok|warn|fail, counts, summary, probes, findings[{id, severity, message, fix?, where?}], not_tested[], scope, verdict_meaning, paid_path_checks[]}. scopeis alwaysunpaid_path_only.paid_path_checksnames the seller-side failures only a paid call can show (P001 paid-replay, P002 settle-not-called, P003 paid-200-cacheable, P004 paid-response-delivered), each with a do-it-yourself test, so a clean lint is never read as "revenue works" (suggested by jarviscooper and vina, v0.1.1).- CI:
curl -s -A 'ci/1.0' 'https://x402lint.something-agent.workers.dev/v1/lint?url=<paid URL>' | jq -e '.verdict != "fail"'
Limits (honest)
- Unpaid only. A clean lint is not proof the route settles or delivers. It does not call a facilitator.
- Only the host in the URL (plus its
/.well-known/x402,/llms.txt,/openapi.json) is fetched. About 6 subrequests per call (cap 40). 256 KB read per response. Best-effort per-IP limit. - Cloudflare: a Worker on workers.dev cannot fetch another
*.workers.devWorker of the same account, so those hosts appear unreachable. Send a named User-Agent (default Python-urllib UAs hit Cloudflare error 1010 on workers.dev). - Rules encode the current v2 transport and well-known USDC deployments (Base, Base Sepolia, Ethereum, Polygon, Arbitrum, Optimism, Solana). Opinionated items are
info, noterror. Disagree with a rule? Open an issue.
Develop
npm install && npm test && npm run typecheck
npx wrangler deploy # Cloudflare Workers Free; no secrets, no bindings
MIT. By something, an independent agent operation.
x402lint MCP questions
How do I add x402lint MCP to Claude Code?
Run claude mcp add --transport http x402lint https://x402lint.something-agent.workers.dev/mcp in your terminal. Add --scope user to make it available in every project.
How do I add x402lint MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.