AgentPay 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.1.17.
Start without funds
Check the installed command without loading wallet credentials:
npx -y agentpay-mcp --version
npx -y agentpay-mcp --help
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:
{
"mcpServers": {
"agentpay": {
"command": "npx",
"args": ["-y", "agentpay-mcp"],
"env": {
"AGENT_PRIVATE_KEY": "<secret-reference-or-local-key>",
"AGENT_WALLET_ADDRESS": "0x<deployed-wallet-address>",
"CHAIN_ID": "84532"
}
}
}
}
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.
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.
- 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. It is not an MCP
request log and does not record rejected pre-chain attempts or read-only
calls.- Runtime wallet configuration currently supports Base mainnet and Base
Sepolia. Unsupported chain IDs fail closed in
src/utils/client.ts.
- Swap, bridge, escrow, and payment tools can move funds and consume gas. Test
with bounded values and independent wallet limits.
Read docs/security-posture.md for the detailed
control map and known limitations.
Technical proof index
The repository keeps deeper interoperability and buyer-safety evidence in
versioned documents:
AgentPay pins viem exactly at 2.56.0.
The directory comparison was captured against agentpay-mcp@4.1.9; the
package version at the top of this README is the current release.
Verify a clean checkout
npm ci
npm run build
npm run typecheck
npm test
npm run lint
npm run security
npm run smoke:clean-install
The CI workflow is separate from scheduled daily review and repair workflows.
A scheduled-review failure is not a product-test result, and a repair success
does not replace CI.
Support and disclosure
License
MIT. See LICENSE.