up2itnow0822/clawpay-mcp

AgentPay MCP is a stdio Model Context Protocol server for x402 payments and
wallet operations. It exposes Agent Wallet SDK functions as MCP tools and loads
a caller-controlled signing key from the local process environment.
The current npm package is agentpay-mcp v4.2.0.
Start without funds
Check the installed command without loading wallet credentials:
Use the
AgentPay Wallet Starter
for a no-funds verification of allowed, approval-required, and blocked policy
outcomes.
MCP client configuration
Wallet tools read the following environment variables:
| Variable | Required for wallet tools | Meaning |
| --- | --- | --- |
| AGENT_PRIVATE_KEY | Yes | Local hot-wallet signing key |
| AGENT_WALLET_ADDRESS | Yes | Deployed AgentAccountV2 address |
| CHAIN_ID | No | 8453 or 84532; defaults to Base mainnet |
| RPC_URL | No | Caller-selected Base RPC endpoint |
| FACTORY_ADDRESS | For deployment | Wallet factory address |
| NFT_CONTRACT_ADDRESS | For deployment | Token contract bound to a wallet |
| SESSION_TTL_SECONDS | No | Local session lifetime in seconds |
Example MCP configuration:
Do not commit a real signing key. Use the client or operating system's secret
mechanism where one exists. Start on Base Sepolia before using Base mainnet.
Tool groups
The tool registry in src/index.ts exposes these groups:
| Group | Examples |
| --- | --- |
| Wallet | deploy_wallet, get_wallet_info, queue_approval |
| Payments | send_payment, x402_pay, x402 session tools |
| Policy | set_spend_policy, check_budget, OTel budget tools |
| Tokens | Lookup, custom-token registration, balances, and transfers |
| Execution | Swap, USDC bridge, and mutual-stake escrow |
| Trust | ERC-8004 identity, reputation, and UAID verification |
| History | get_transaction_history for wallet contract events |
Tool schemas and handlers live under src/tools/.
Security boundaries
These boundaries matter more than the feature list:
- The server reads AGENT_PRIVATE_KEY into its local Node.js process and uses
viem for signing. Protect the process, environment, and MCP client config.
- set_spend_policy stores policy in the MCP server process. The same agent can
call that tool again, and a process restart clears its rolling state.
- Every current value-moving handler calls the in-process policy check, but
this is still application-level enforcement.
- swap_tokens and bridge_usdc reserve spend at approve, then settle,
release, or hold-unknown. Quote, validation, and confirmed uncharged revert
failures release the reservation and stay retryable. An unclear
post-broadcast outcome locks that intent with no timer.
- On-chain limits exist only when the wallet owner configures them directly on
AgentAccountV2. set_spend_policy does not write those contract limits.
- An over-limit transaction is a human gate only when the owner key is kept
separate from the agent key.
- get_transaction_history reads on-chain wallet events and, for unscoped
all queries, also lists x402 settlements made by this server process (final URL of
the paid response, which may differ from the 402 issuer under redirects, method, amount, token, payee, tx hash, replay count). Those x402
receipts mean the payment was broadcast (a tx hash was returned), not that a receipt was confirmed. They are kept in memory only, capped at 256, and lost on restart. They are