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:

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

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:

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 [email protected]; 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.