Agentpay

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.2.0.

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.

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 omitted from block-scoped queries. This is not an MCP request log: it 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:

• docs/agentpay-buyer-flow-parity.md covers typed payment errors and buyer flow behavior.
• docs/paid-mcp-gateway-hardening.md covers default-deny controls and quota envelopes.
• docs/agentpay-five-tool-parity-proof.md records the five-tool parity check.
• docs/agentpay-escrow-reputation-boundary.md defines the escrow and reputation boundary.
• docs/paid-mcp-proxy-discovery-readiness.md records discovery readiness evidence.
• docs/x402-chain-neutral-gateway-profile.md defines the packaged chain-neutral profile.
• docs/x402-dynamic-paid-mcp-manifest-drift.md documents checks for stale paid-tool metadata.
• docs/mcp-registry-listing-proof.md and llms.txt expose directory metadata.
• docs/smithery-paid-mcp-installation.md and examples/smithery-paid-mcp-installation document the packaged Smithery path without asserting a live listing.
• docs/paid-provider-health-proof.md defines provider-health evidence.
• docs/hosted-x402-proxy-verification.md defines hosted-proxy preflight checks.
• docs/x402-native-vs-stripe-proxy.md separates local spend control from hosted proxy billing.
• docs/dependency-pin-policy.md defines the release gate for payment-critical packages.

AgentPay pins viem exactly at 2.57.4.

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.

Related repositories

• Agent Wallet SDK provides the wallet and policy library used by this server.
• AgentPay Wallet Starter provides the combined no-funds onboarding path.
• NVIDIA NeMo Agent Toolkit Examples PR 17 is an independently merged integration example.

Support and disclosure

• File product bugs through the GitHub issue queue.
• Report security issues through SECURITY.md.
• Contribution rules live in CONTRIBUTING.md.

License

MIT. See LICENSE.