> [!WARNING] > **Paused for security maintenance. Do not use in production.** # AgentPay MCP [![npm](https://img.shields.io/npm/v/agentpay-mcp.svg)](https://www.npmjs.com/package/agentpay-mcp) [![CI](https://github.com/up2itnow0822/agentpay-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/up2itnow0822/agentpay-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) 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.2.0. ## Start without funds Check the installed command without loading wallet credentials: ```bash npx -y agentpay-mcp --version npx -y agentpay-mcp --help ``` Use the [AgentPay Wallet Starter](https://github.com/up2itnow0822/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: ```json { "mcpServers": { "agentpay": { "command": "npx", "args": ["-y", "agentpay-mcp"], "env": { "AGENT_PRIVATE_KEY": "", "AGENT_WALLET_ADDRESS": "0x", "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`](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/`](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. - `swap_tokens` and `bridge_usdc` reserve spend at approve, then settle, release, or hold-unknown. Quote, validation, and confirmed uncharged revert failures release the reservation and stay retryable. An unclear post-broadcast outcome locks that intent with no timer. - 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 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`](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`](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`](docs/agentpay-buyer-flow-parity.md) covers typed payment errors and buyer flow behavior. - [`docs/paid-mcp-gateway-hardening.md`](docs/paid-mcp-gateway-hardening.md) covers default-deny controls and quota envelopes. - [`docs/agentpay-five-tool-parity-proof.md`](docs/agentpay-five-tool-parity-proof.md) records the five-tool parity check. - [`docs/agentpay-escrow-reputation-boundary.md`](docs/agentpay-escrow-reputation-boundary.md) defines the escrow and reputation boundary. - [`docs/paid-mcp-proxy-discovery-readiness.md`](docs/paid-mcp-proxy-discovery-readiness.md) records discovery readiness evidence. - [`docs/x402-chain-neutral-gateway-profile.md`](docs/x402-chain-neutral-gateway-profile.md) defines the packaged chain-neutral profile. - [`docs/x402-dynamic-paid-mcp-manifest-drift.md`](docs/x402-dynamic-paid-mcp-manifest-drift.md) documents checks for stale paid-tool metadata. - [`docs/mcp-registry-listing-proof.md`](docs/mcp-registry-listing-proof.md) and [`llms.txt`](llms.txt) expose directory metadata. - [`docs/smithery-paid-mcp-installation.md`](docs/smithery-paid-mcp-installation.md) and [`examples/smithery-paid-mcp-installation`](examples/smithery-paid-mcp-installation) document the packaged Smithery path without asserting a live listing. - [`docs/paid-provider-health-proof.md`](docs/paid-provider-health-proof.md) defines provider-health evidence. - [`docs/hosted-x402-proxy-verification.md`](docs/hosted-x402-proxy-verification.md) defines hosted-proxy preflight checks. - [`docs/x402-native-vs-stripe-proxy.md`](docs/x402-native-vs-stripe-proxy.md) separates local spend control from hosted proxy billing. - [`docs/dependency-pin-policy.md`](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 ```bash 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](https://github.com/up2itnow0822/agent-wallet-sdk) provides the wallet and policy library used by this server. - [AgentPay Wallet Starter](https://github.com/up2itnow0822/agentpay-wallet-starter) provides the combined no-funds onboarding path. - [NVIDIA NeMo Agent Toolkit Examples PR 17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) is an independently merged integration example. ## Support and disclosure - File product bugs through the [GitHub issue queue](https://github.com/up2itnow0822/agentpay-mcp/issues). - Report security issues through [`SECURITY.md`](SECURITY.md). - Contribution rules live in [`CONTRIBUTING.md`](CONTRIBUTING.md). ## License MIT. See [`LICENSE`](LICENSE).