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.

Related MCP server: 402-mcp

MCP client configuration

Wallet tools read the following environment variables:

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:

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.