{
  "markdown": "# AgentPay MCP\n\n[![npm](https://img.shields.io/npm/v/agentpay-mcp.svg)](https://www.npmjs.com/package/agentpay-mcp)\n[![CI](https://github.com/up2itnow0822/agentpay-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/up2itnow0822/agentpay-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nAgentPay MCP is a stdio Model Context Protocol server for x402 payments and\nwallet operations. It exposes Agent Wallet SDK functions as MCP tools and loads\na caller-controlled signing key from the local process environment.\n\nThe current npm package is `agentpay-mcp` v4.1.17.\n\n## Start without funds\n\nCheck the installed command without loading wallet credentials:\n\n```bash\nnpx -y agentpay-mcp --version\nnpx -y agentpay-mcp --help\n```\n\nUse the\n[AgentPay Wallet Starter](https://github.com/up2itnow0822/agentpay-wallet-starter)\nfor a no-funds verification of allowed, approval-required, and blocked policy\noutcomes.\n\n## MCP client configuration\n\nWallet tools read the following environment variables:\n\n| Variable | Required for wallet tools | Meaning |\n| --- | --- | --- |\n| `AGENT_PRIVATE_KEY` | Yes | Local hot-wallet signing key |\n| `AGENT_WALLET_ADDRESS` | Yes | Deployed `AgentAccountV2` address |\n| `CHAIN_ID` | No | `8453` or `84532`; defaults to Base mainnet |\n| `RPC_URL` | No | Caller-selected Base RPC endpoint |\n| `FACTORY_ADDRESS` | For deployment | Wallet factory address |\n| `NFT_CONTRACT_ADDRESS` | For deployment | Token contract bound to a wallet |\n| `SESSION_TTL_SECONDS` | No | Local session lifetime in seconds |\n\nExample MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentpay\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentpay-mcp\"],\n      \"env\": {\n        \"AGENT_PRIVATE_KEY\": \"<secret-reference-or-local-key>\",\n        \"AGENT_WALLET_ADDRESS\": \"0x<deployed-wallet-address>\",\n        \"CHAIN_ID\": \"84532\"\n      }\n    }\n  }\n}\n```\n\nDo not commit a real signing key. Use the client or operating system's secret\nmechanism where one exists. Start on Base Sepolia before using Base mainnet.\n\n## Tool groups\n\nThe tool registry in [`src/index.ts`](src/index.ts) exposes these groups:\n\n| Group | Examples |\n| --- | --- |\n| Wallet | `deploy_wallet`, `get_wallet_info`, `queue_approval` |\n| Payments | `send_payment`, `x402_pay`, x402 session tools |\n| Policy | `set_spend_policy`, `check_budget`, OTel budget tools |\n| Tokens | Lookup, custom-token registration, balances, and transfers |\n| Execution | Swap, USDC bridge, and mutual-stake escrow |\n| Trust | ERC-8004 identity, reputation, and UAID verification |\n| History | `get_transaction_history` for wallet contract events |\n\nTool schemas and handlers live under [`src/tools/`](src/tools/).\n\n## Security boundaries\n\nThese boundaries matter more than the feature list:\n\n- The server reads `AGENT_PRIVATE_KEY` into its local Node.js process and uses\n  viem for signing. Protect the process, environment, and MCP client config.\n- `set_spend_policy` stores policy in the MCP server process. The same agent can\n  call that tool again, and a process restart clears its rolling state.\n- Every current value-moving handler calls the in-process policy check, but\n  this is still application-level enforcement.\n- On-chain limits exist only when the wallet owner configures them directly on\n  `AgentAccountV2`. `set_spend_policy` does not write those contract limits.\n- An over-limit transaction is a human gate only when the owner key is kept\n  separate from the agent key.\n- `get_transaction_history` reads on-chain wallet events. It is not an MCP\n  request log and does not record rejected pre-chain attempts or read-only\n  calls.\n- Runtime wallet configuration currently supports Base mainnet and Base\n  Sepolia. Unsupported chain IDs fail closed in\n  [`src/utils/client.ts`](src/utils/client.ts).\n- Swap, bridge, escrow, and payment tools can move funds and consume gas. Test\n  with bounded values and independent wallet limits.\n\nRead [`docs/security-posture.md`](docs/security-posture.md) for the detailed\ncontrol map and known limitations.\n\n## Technical proof index\n\nThe repository keeps deeper interoperability and buyer-safety evidence in\nversioned documents:\n\n- [`docs/agentpay-buyer-flow-parity.md`](docs/agentpay-buyer-flow-parity.md)\n  covers typed payment errors and buyer flow behavior.\n- [`docs/paid-mcp-gateway-hardening.md`](docs/paid-mcp-gateway-hardening.md)\n  covers default-deny controls and quota envelopes.\n- [`docs/agentpay-five-tool-parity-proof.md`](docs/agentpay-five-tool-parity-proof.md)\n  records the five-tool parity check.\n- [`docs/agentpay-escrow-reputation-boundary.md`](docs/agentpay-escrow-reputation-boundary.md)\n  defines the escrow and reputation boundary.\n- [`docs/paid-mcp-proxy-discovery-readiness.md`](docs/paid-mcp-proxy-discovery-readiness.md)\n  records discovery readiness evidence.\n- [`docs/x402-chain-neutral-gateway-profile.md`](docs/x402-chain-neutral-gateway-profile.md)\n  defines the packaged chain-neutral profile.\n- [`docs/x402-dynamic-paid-mcp-manifest-drift.md`](docs/x402-dynamic-paid-mcp-manifest-drift.md)\n  documents checks for stale paid-tool metadata.\n- [`docs/mcp-registry-listing-proof.md`](docs/mcp-registry-listing-proof.md)\n  and [`llms.txt`](llms.txt) expose directory metadata.\n- [`docs/smithery-paid-mcp-installation.md`](docs/smithery-paid-mcp-installation.md)\n  and\n  [`examples/smithery-paid-mcp-installation`](examples/smithery-paid-mcp-installation)\n  document the packaged Smithery path without asserting a live listing.\n- [`docs/paid-provider-health-proof.md`](docs/paid-provider-health-proof.md)\n  defines provider-health evidence.\n- [`docs/hosted-x402-proxy-verification.md`](docs/hosted-x402-proxy-verification.md)\n  defines hosted-proxy preflight checks.\n- [`docs/x402-native-vs-stripe-proxy.md`](docs/x402-native-vs-stripe-proxy.md)\n  separates local spend control from hosted proxy billing.\n- [`docs/dependency-pin-policy.md`](docs/dependency-pin-policy.md) defines the\n  release gate for payment-critical packages.\n\nAgentPay pins `viem` exactly at `2.56.0`.\n\nThe directory comparison was captured against `agentpay-mcp@4.1.9`; the\npackage version at the top of this README is the current release.\n\n## Verify a clean checkout\n\n```bash\nnpm ci\nnpm run build\nnpm run typecheck\nnpm test\nnpm run lint\nnpm run security\nnpm run smoke:clean-install\n```\n\nThe CI workflow is separate from scheduled daily review and repair workflows.\nA scheduled-review failure is not a product-test result, and a repair success\ndoes not replace CI.\n\n## Related repositories\n\n- [Agent Wallet SDK](https://github.com/up2itnow0822/agent-wallet-sdk) provides\n  the wallet and policy library used by this server.\n- [AgentPay Wallet Starter](https://github.com/up2itnow0822/agentpay-wallet-starter)\n  provides the combined no-funds onboarding path.\n- [NVIDIA NeMo Agent Toolkit Examples PR 17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)\n  is an independently merged integration example.\n\n## Support and disclosure\n\n- File product bugs through the\n  [GitHub issue queue](https://github.com/up2itnow0822/agentpay-mcp/issues).\n- Report security issues through [`SECURITY.md`](SECURITY.md).\n- Contribution rules live in [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n",
  "bytes": 7294,
  "sha": "bfb547b5bbba0d7e6ffb81c6de40724d438aa465095a1fa2c591284fdcf7723e",
  "repo_slug": "up2itnow0822/agentpay-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_up2itnow0822_agentpay_75e92962/readme"
}