Generic MCP server for calling x402-protected APIs with automatic payment handling
npm install @x402scan/mcpMCP server for calling x402-protected APIs with automatic payment handling.
``bash`
npx @x402scan/mcp install
`bash`
claude mcp add x402scan --scope user -- npx -y @x402scan/mcp@latest
`bash`
codex mcp add x402scan -- npx -y @x402scan/mcp@latest
Manual installation
Codex - Add to ~/.codex/config.toml:
`toml`
[mcp_servers.x402scan]
command = "npx"
args = ["-y", "@x402scan/mcp@latest"]
Cursor - Add to .cursor/mcp.json:
`json`
{
"mcpServers": {
"x402scan": {
"command": "/bin/bash",
"args": [
"-c",
"source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y @x402scan/mcp@latest"
]
}
}
}
Claude Desktop - Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
`json`
{
"mcpServers": {
"x402scan": {
"command": "/bin/bash",
"args": [
"-c",
"source $HOME/.nvm/nvm.sh 2>/dev/null; exec npx -y @x402scan/mcp@latest"
]
}
}
}
On first run, a wallet is generated at ~/.x402scan-mcp/wallet.json. Deposit USDC on Base to the wallet address before making paid API calls.
Workflow:
1. get_wallet_info - Check wallet and get deposit addressredeem_invite
2. - Redeem an invite code to fund your wallet (if you have one)discover_api_endpoints
3. - Find available x402 endpoints on an origincheck_endpoint_schema
4. - Probe endpoint for pricing/schema (optional)fetch
5. - Make the paid request (or fetch_with_auth for SIWX auth)
| Tool | Description |
| ------------------------ | ------------------------------------------------------------ |
| fetch | Fetch x402-protected resource with automatic payment |fetch_with_auth
| | Make request to SIWX-protected endpoint with automatic auth |get_wallet_info
| | Get wallet address and USDC balance |redeem_invite
| | Redeem an invite code to receive USDC |check_endpoint_schema
| | Check if endpoint is x402-protected, get pricing/schema/auth |discover_api_endpoints
| | Discover x402 resources from origin's .well-known/x402 |report_error
| | Report critical MCP tool bugs to x402scan developers |
| Variable | Description |
| ------------------ | --------------------------------- |
| X402_PRIVATE_KEY | Override wallet (optional) |X402_DEBUG
| | Set to true for verbose logging |
Base, Base Sepolia, Ethereum, Optimism, Arbitrum, Polygon (via CAIP-2)
`bash
pnpm install
Evaluations
MCP changes are automatically tested via CI. Comprehensive evaluations run in the x402-evals repository.
$3
- PR Smoke Test - Automatically runs when you modify MCP source code
- Release Eval - Full evaluation suite runs when a new version is published
$3
Comment on your PR to trigger evaluations:
| Command | Description |
| ------------------------ | ---------------------------------------- |
|
or /eval smoke | Quick validation (~2-3 min) |
| /eval full | Comprehensive testing (~10 min) |
| /eval regression | Known edge cases and historical failures |Results are posted back to your PR with a link to detailed metrics.
$3
`bash
In x402-evals repo
MCP_SERVER_DIR=/path/to/x402scan/packages/external/mcp/dist/esm pnpm --filter @x402-evals/promptfoo eval
`$3
1. Make a PR in enrichx402 and generate a preview URL with vercel
2. Make a branch in the x402scan repo
3. Replace the enrichx402.com URL in
with your preview URL
4. Push and make a PR, then comment on it with "/eval full" (or smoke, regression)Publishing
This package uses changesets for versioning and publishing.
$3
1. Create a changeset describing your changes:
`bash
pnpm changeset
`
2. Commit the changeset file with your PR
3. When merged to , the CI creates a "Version Packages" PR
4. Merging the version PR triggers automatic npm publish$3
For pre-release versions, use the
beta branch with prerelease mode:1. Enter prerelease mode:
`bash
pnpm changeset pre enter beta
`
2. Commit the generated file
3. Create changesets and merge to beta as normal
4. Versions will be published as x.x.x-beta.xTo exit prerelease mode and promote to stable:
bash
pnpm changeset pre exit
`Note: The CI enforces that
branch must have pre.json and main` branch must not.