TollWarden — Claude Code MCP server: x402 payment screening
Screens an outgoing x402 payment before it settles and answers allow, flag or block. Built for agents that pay for data and APIs.
claude mcp add tollwarden -- npx -y tollwardenWhat TollWarden does
TollWarden sits between the agent's decision to pay and the wallet signature. The agent posts the payment to POST /v1/scan/outgoing and gets a verdict with per-check reasons: allow lets the wallet settle, flag tells the agent to pause and confirm intent, block stops the signature. Nothing is held on the server side — keys, wallets and funds stay with you, and the verdict is advice only.
Several failure modes are covered. Secrets leaking through payment metadata: EVM private keys, seed phrases, cloud and AI service keys, JWTs, credentials embedded in URLs. A nonce that has already been used. The same purchase authorized twice — an x402 client signs a fresh authorization for every 402 it meets, so a retried request arrives as a second valid payment. A quoted price far above the expected one. And payments whose decision came from a page or tool result the agent had just read rather than from its own plan.
An API key is required; the @tollwarden/client package mints one on its own and includes 100 free scans. SDKs exist for TypeScript and Python, with integrations for LangChain, CrewAI, NeMo Agent Toolkit, Coinbase AgentKit and Vercel AI SDK. Wallet authors can use TollWardenEnforcer, which wraps a viem or ethers signer and refuses to sign an authorization unless a fresh allow-verdict bound to that payment is present.
What it helps with
- catch a leaked private key or API key in payment metadata before it goes out
- reject a payment authorization whose nonce was already spent
- spot a second signature for a purchase that was already paid
- stop a payment triggered by content the agent just read
- block a payment priced above the expected amount
Example prompts for the agent
- Run this x402 payment through TollWarden before signing it
- Tag the page text the agent just read and check whether it pushes toward a payment
- Wire TollWarden into the wallet so it won't sign without an allow verdict
How to install TollWarden
Platform CLI
claude mcp add tollwarden -- npx -y tollwardenPlatform CLI
codex mcp add tollwarden -- npx -y tollwardenConfig file
{
"mcpServers": {
"tollwarden": {
"command": "npx",
"args": [
"-y",
"tollwarden"
]
}
}
}Config file
{
"servers": {
"tollwarden": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"tollwarden"
]
}
}
}Platform CLI
gemini mcp add tollwarden npx -y tollwardenStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about TollWarden
How do I install TollWarden in Claude Code?
With one command: claude mcp add tollwarden -- npx -y tollwarden.
What does TollWarden do?
It screens an outgoing x402 payment before settlement and returns allow, flag or block with reasons per check. Leaked secrets, nonce reuse, duplicate purchases, inflated prices and payments prompted by read content all get flagged.
Does TollWarden need access to my wallet?
No. It never touches keys or funds, it only issues a verdict. For hard enforcement there is TollWardenEnforcer, which wraps a viem or ethers signer.
