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.

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.
• 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:

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

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.