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.

agentpay mcp