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 v5.0.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

Operator safety variables. They are read from the server environment only and cannot be changed through MCP:

Variable	Default	Meaning
AGENTPAY_POLICY_DAILY_LIMIT_ETH	unset	Operator 24-hour rolling limit (ETH-equivalent)
AGENTPAY_POLICY_PER_TX_CAP_ETH	unset	Operator per-transaction cap (ETH-equivalent)
AGENTPAY_POLICY_ALLOWED_RECIPIENTS	unset	Comma-separated operator recipient allowlist
AGENTPAY_ALLOW_UNPOLICED_SPEND	off	1 permits value movement with no operator policy, relying only on on-chain limits
AGENTPAY_X402_MAX_PAYMENT	unset	USDC ceiling applied on top of every per-call x402 cap; non-USDC x402 payments are refused while set
AGENTPAY_STATE_DIR	unset	Directory for the fsync'd spend-intent journal; locks and keyed settlements survive restarts, and the journal is compacted to its live state automatically. One process owns the directory at a time (spend-intents.lock). If the journal cannot be read or fsync'd, or another live process owns the directory, value movement is refused
AGENTPAY_ALLOWED_PRIVATE_HOSTS	unset	Comma-separated hosts whose private address may be reached by outbound requests
AGENTPAY_ALLOW_PRIVATE_NETWORK	off	Development only: permit private destinations and plain http

Without at least one AGENTPAY_POLICY_* variable, or AGENTPAY_ALLOW_UNPOLICED_SPEND=1, every value-moving tool refuses to spend.

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",
        "AGENTPAY_POLICY_PER_TX_CAP_ETH": "0.01",
        "AGENTPAY_POLICY_DAILY_LIMIT_ETH": "0.1",
        "AGENTPAY_X402_MAX_PAYMENT": "1",
        "AGENTPAY_STATE_DIR": "<writable-private-directory>"
      }
    }
  }
}

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_quote, 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.
• Spend policy is default-deny. The operator policy comes from AGENTPAY_POLICY_* environment variables, is loaded once, and cannot be changed or cleared through MCP. Without it, value movement is refused unless the operator sets AGENTPAY_ALLOW_UNPOLICED_SPEND=1.
• set_spend_policy can only tighten. Each call adds a layer to its scope; a request that raises a limit, drops a constraint, or widens an allowlist is refused, and earlier layers keep their rolling-window accounting. Loosening requires an operator restart. All policy state is still in-process and is reset by a restart.
• x402_pay and x402_session_start require max_payment_eth and pay_to. The asset is always bound: it defaults to the chain's USDC unless asset names another; network can be bound too. A 402 that names another payee, asset, or network, the zero address, or a debit (principal plus the 0.77% protocol fee) above the cap is refused before any wallet write. AGENTPAY_X402_MAX_PAYMENT is a USDC ceiling; with it set, non-USDC payments are refused. Use x402_quote to read the offered terms first.
• If a payment settles but its response is not delivered — the response fails, or the paid request is answered with any non-2xx status — every new x402 payment to that host (any path, port or spelling of the name) and to that payee (behind any host) is locked until an operator reconciles it. The lock is written before the wallet call, so a crash cannot lose it.
• Caller-selected outbound requests (x402, quote, sessions, OTel kill callback) use a safe transport: https only (a kill callback may use http only for a host in AGENTPAY_KILL_CALLBACK_ALLOWED_HOSTS), private, loopback, link-local and metadata destinations refused, DNS resolved once with the socket pinned to the validated address, no automatic redirects, and response bodies capped at 2 MiB (1 MiB rendered).
• send_payment, send_token, swap_tokens, bridge_usdc, create_escrow, x402_pay, and x402_session_start run inside a spend intent. Identical retries replay; idempotencyKey distinguishes equal payments; an unclear post-broadcast outcome locks the intent with no timer. Locks are process-local unless AGENTPAY_STATE_DIR journals them. Reconcile with agentpay-mcp spend-intents list and resolve <id> settled|unsettled, which is a local CLI, never an MCP tool. <id> is the shell-safe id: handle list prints for each intent. settled (the value moved) clears the lock and retires a keyed intent's idempotencyKey for good; a keyless intent has no key to retire, so an identical new request is a new payment (use idempotencyKey for retry safety). unsettled (nothing moved) clears the lock so a retry may pay. Only one process may use a state directory at a time: stop the server before resolve (list shows a read-only snapshot while it runs), and give each server its own AGENTPAY_STATE_DIR.
• idempotencyKey may not contain control, invisible formatting, or line-separator characters; keys are printed escaped and shell-inert.
• send_payment takes decimals from the token registry or the token contract; a differing token_decimals is refused before signing.
• On-chain limits exist only when the wallet owner configures them directly on AgentAccountV2. The application policy does not write those contract limits, and 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.

Upgrading from 4.x

v5.0.0 is a breaking security release. Before upgrading:

• Set an operator policy (AGENTPAY_POLICY_*) or explicitly opt out with AGENTPAY_ALLOW_UNPOLICED_SPEND=1; otherwise every spend is refused.
• Pass max_payment_eth and pay_to to every x402_pay and x402_session_start call. Use x402_quote to read the terms first.
• Stop relying on set_spend_policy to raise or clear limits.
• Move any http or private-network x402 endpoint to https, or allow it with AGENTPAY_ALLOWED_PRIVATE_HOSTS (production) or AGENTPAY_ALLOW_PRIVATE_NETWORK=1 (development only).
• Set AGENTPAY_STATE_DIR on long-lived servers.

docs/security-remediation-2026-10.md maps every finding to its fix and test.

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.