@arispay/payagent-mcp 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Polar Industries Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @arispay/payagent-mcp
+
+MCP server for [ArisPay](https://arispay.app)-delegated x402 USDC payments. Lets AI agents call paid APIs and settle HTTP 402 challenges with USDC on Base — no private keys ever live in this process.
+
+Works with Claude Desktop, Cursor, Windsurf, or any MCP client. A thin wrapper around the [`payagent`](https://www.npmjs.com/package/payagent) SDK.
+
+## Setup
+
+1. Provision an agent at [payagent.arispay.app](https://payagent.arispay.app). You'll get:
+   - A CDP-managed wallet address to fund with USDC on Base
+   - An `ARISPAY_AGENT_KEY` (returned exactly once — store it securely)
+2. Fund the wallet with USDC on Base.
+3. Add the MCP server to your client config:
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "arispay": {
+      "command": "npx",
+      "args": ["-y", "@arispay/payagent-mcp"],
+      "env": {
+        "ARISPAY_AGENT_KEY": "ap_live_...",
+        "PAYAGENT_WALLET": "0x..."
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Edit `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "arispay": {
+      "command": "npx",
+      "args": ["-y", "@arispay/payagent-mcp"],
+      "env": {
+        "ARISPAY_AGENT_KEY": "ap_live_...",
+        "PAYAGENT_WALLET": "0x..."
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json` with the same pattern.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ARISPAY_AGENT_KEY` | Yes | — | Agent-scoped API key from `payagent.arispay.app` |
+| `ARISPAY_URL` | No | `https://api.arispay.app` | ArisPay API base URL |
+| `PAYAGENT_WALLET` | No | — | Wallet address (for `check_wallet` tool output) |
+
+## Tools
+
+### `pay_api`
+
+Make an HTTP request to a paid API. Automatically handles HTTP 402 payment challenges via ArisPay-delegated signing.
+
+**Parameters:**
+- `url` (string, required) — The API endpoint URL
+- `method` (string, default: "GET") — HTTP method
+- `headers` (object, optional) — Additional HTTP headers
+- `body` (string, optional) — Request body
+
+Spend caps (`maxPerTx`, `maxDaily`, `maxMonthly`, `allowedDomains`) are set on the agent at provisioning time and enforced server-side by ArisPay. There is no client-side budget parameter — attempts that exceed the delegation return a `PaymentRejectedError`.
+
+**Example prompt:** "Use pay_api to fetch https://api.example.com/premium-data"
+
+### `check_wallet`
+
+Report the configured agent, and — if `PAYAGENT_WALLET` is set — the on-chain USDC balance on Base.
+
+**Parameters:** None
+
+**Example prompt:** "Check my agent wallet"
+
+Full delegation limits and spend history live at [payagent.arispay.app](https://payagent.arispay.app).
+
+## How It Works
+
+1. Agent calls `pay_api` with a URL.
+2. If the server returns HTTP 402, `payagent` asks ArisPay to sign via CDP.
+3. ArisPay validates the request against the agent's delegation limits and signs.
+4. `payagent` retries with the signed `X-PAYMENT` header; the seller's facilitator settles on-chain.
+
+No private key lives in this process. The signing key is held by Coinbase CDP; ArisPay enforces limits before signing. If a payment breaches the delegation, it's rejected before any on-chain action.
+
+## Install
+
+```bash
+npm install @arispay/payagent-mcp
+```
+
+Or invoke directly via `npx @arispay/payagent-mcp` from an MCP client config — no pre-install required.
+
+## Related
+
+- [payagent](https://www.npmjs.com/package/payagent) — the SDK for programmatic use
+- [x402 protocol](https://github.com/coinbase/x402) — HTTP 402 payment standard
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { payFetchDelegated, getUSDCBalance, formatUSDC } from "payagent";
+var arispayUrl = process.env.ARISPAY_URL ?? "https://api.arispay.app";
+var agentKey = process.env.ARISPAY_AGENT_KEY;
+var walletAddress = process.env.PAYAGENT_WALLET;
+if (!agentKey) {
+  console.error(
+    "Error: ARISPAY_AGENT_KEY environment variable is required.\nProvision an agent at https://payagent.arispay.app to get a key."
+  );
+  process.exit(1);
+}
+var fetch402 = payFetchDelegated({
+  arispayUrl,
+  apiKey: agentKey
+});
+var server = new McpServer({
+  name: "payagent",
+  version: "2.0.0"
+});
+server.tool(
+  "pay_api",
+  {
+    url: z.string().describe("The full URL of the API endpoint to call"),
+    method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("GET").describe("HTTP method"),
+    headers: z.record(z.string(), z.string()).optional().describe("Additional HTTP headers to include"),
+    body: z.string().optional().describe("Request body (for POST/PUT/PATCH)")
+  },
+  async ({ url, method, headers, body }) => {
+    try {
+      const response = await fetch402(url, {
+        method,
+        headers,
+        body
+      });
+      const responseBody = await response.text();
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `HTTP ${response.status}`,
+              "",
+              responseBody
+            ].join("\n")
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "check_wallet",
+  {},
+  async () => {
+    const lines = [
+      `ArisPay URL: ${arispayUrl}`,
+      `Agent key:   ${agentKey.slice(0, 10)}\u2026`
+    ];
+    if (walletAddress) {
+      lines.push(`Wallet:      ${walletAddress}`);
+      try {
+        const raw = await getUSDCBalance(walletAddress, "base");
+        lines.push(`Balance:     ${formatUSDC(raw)} USDC on Base`);
+      } catch (err) {
+        lines.push(`Balance:     unavailable (${err instanceof Error ? err.message : String(err)})`);
+      }
+    } else {
+      lines.push("", "Set PAYAGENT_WALLET=0x\u2026 in env to include on-chain balance.");
+    }
+    lines.push("", "Delegation limits + full spend history: https://payagent.arispay.app");
+    return {
+      content: [{ type: "text", text: lines.join("\n") }]
+    };
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * payagent-mcp — MCP server that lets AI agents pay for APIs.\n *\n * Thin wrapper around `payagent`'s delegated signing path. No private keys\n * touch this process — ArisPay holds a Coinbase CDP-managed wallet and\n * enforces spend limits server-side.\n *\n * Configuration via environment variables:\n *   - ARISPAY_URL:         ArisPay API base URL (default: https://api.arispay.app)\n *   - ARISPAY_AGENT_KEY:   The agent-scoped API key returned by createX402Agent (required)\n *   - PAYAGENT_WALLET:     Optional wallet address for `check_wallet` tool output\n */\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { z } from 'zod';\nimport { payFetchDelegated, getUSDCBalance, formatUSDC } from 'payagent';\n\n// ── Config from env ─────────────────────────────────\n\nconst arispayUrl = process.env.ARISPAY_URL ?? 'https://api.arispay.app';\nconst agentKey = process.env.ARISPAY_AGENT_KEY;\nconst walletAddress = process.env.PAYAGENT_WALLET;\n\nif (!agentKey) {\n  console.error(\n    'Error: ARISPAY_AGENT_KEY environment variable is required.\\n' +\n    'Provision an agent at https://payagent.arispay.app to get a key.',\n  );\n  process.exit(1);\n}\n\nconst fetch402 = payFetchDelegated({\n  arispayUrl,\n  apiKey: agentKey,\n});\n\n// ── MCP Server ──────────────────────────────────────\n\nconst server = new McpServer({\n  name: 'payagent',\n  version: '2.0.0',\n});\n\nserver.tool(\n  'pay_api',\n  {\n    url: z.string().describe('The full URL of the API endpoint to call'),\n    method: z\n      .enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])\n      .default('GET')\n      .describe('HTTP method'),\n    headers: z\n      .record(z.string(), z.string())\n      .optional()\n      .describe('Additional HTTP headers to include'),\n    body: z\n      .string()\n      .optional()\n      .describe('Request body (for POST/PUT/PATCH)'),\n  },\n  async ({ url, method, headers, body }) => {\n    try {\n      const response = await fetch402(url, {\n        method,\n        headers,\n        body,\n      });\n      const responseBody = await response.text();\n\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: [\n              `HTTP ${response.status}`,\n              '',\n              responseBody,\n            ].join('\\n'),\n          },\n        ],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  'check_wallet',\n  {},\n  async () => {\n    const lines = [\n      `ArisPay URL: ${arispayUrl}`,\n      `Agent key:   ${agentKey.slice(0, 10)}…`,\n    ];\n\n    if (walletAddress) {\n      lines.push(`Wallet:      ${walletAddress}`);\n      try {\n        const raw = await getUSDCBalance(walletAddress, 'base');\n        lines.push(`Balance:     ${formatUSDC(raw)} USDC on Base`);\n      } catch (err) {\n        lines.push(`Balance:     unavailable (${err instanceof Error ? err.message : String(err)})`);\n      }\n    } else {\n      lines.push('', 'Set PAYAGENT_WALLET=0x… in env to include on-chain balance.');\n    }\n\n    lines.push('', 'Delegation limits + full spend history: https://payagent.arispay.app');\n\n    return {\n      content: [{ type: 'text' as const, text: lines.join('\\n') }],\n    };\n  },\n);\n\n// ── Start ───────────────────────────────────────────\n\nasync function main() {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\nmain().catch((err) => {\n  console.error('Fatal:', err);\n  process.exit(1);\n});\n"],"mappings":";;;AAYA,SAAS,iBAAiB;AAC1B,SAAS,4BAA4B;AACrC,SAAS,SAAS;AAClB,SAAS,mBAAmB,gBAAgB,kBAAkB;AAI9D,IAAM,aAAa,QAAQ,IAAI,eAAe;AAC9C,IAAM,WAAW,QAAQ,IAAI;AAC7B,IAAM,gBAAgB,QAAQ,IAAI;AAElC,IAAI,CAAC,UAAU;AACb,UAAQ;AAAA,IACN;AAAA,EAEF;AACA,UAAQ,KAAK,CAAC;AAChB;AAEA,IAAM,WAAW,kBAAkB;AAAA,EACjC;AAAA,EACA,QAAQ;AACV,CAAC;AAID,IAAM,SAAS,IAAI,UAAU;AAAA,EAC3B,MAAM;AAAA,EACN,SAAS;AACX,CAAC;AAED,OAAO;AAAA,EACL;AAAA,EACA;AAAA,IACE,KAAK,EAAE,OAAO,EAAE,SAAS,0CAA0C;AAAA,IACnE,QAAQ,EACL,KAAK,CAAC,OAAO,QAAQ,OAAO,UAAU,OAAO,CAAC,EAC9C,QAAQ,KAAK,EACb,SAAS,aAAa;AAAA,IACzB,SAAS,EACN,OAAO,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC,EAC7B,SAAS,EACT,SAAS,oCAAoC;AAAA,IAChD,MAAM,EACH,OAAO,EACP,SAAS,EACT,SAAS,mCAAmC;AAAA,EACjD;AAAA,EACA,OAAO,EAAE,KAAK,QAAQ,SAAS,KAAK,MAAM;AACxC,QAAI;AACF,YAAM,WAAW,MAAM,SAAS,KAAK;AAAA,QACnC;AAAA,QACA;AAAA,QACA;AAAA,MACF,CAAC;AACD,YAAM,eAAe,MAAM,SAAS,KAAK;AAEzC,aAAO;AAAA,QACL,SAAS;AAAA,UACP;AAAA,YACE,MAAM;AAAA,YACN,MAAM;AAAA,cACJ,QAAQ,SAAS,MAAM;AAAA,cACvB;AAAA,cACA;AAAA,YACF,EAAE,KAAK,IAAI;AAAA,UACb;AAAA,QACF;AAAA,MACF;AAAA,IACF,SAAS,KAAK;AACZ,aAAO;AAAA,QACL,SAAS;AAAA,UACP;AAAA,YACE,MAAM;AAAA,YACN,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,UAClE;AAAA,QACF;AAAA,QACA,SAAS;AAAA,MACX;AAAA,IACF;AAAA,EACF;AACF;AAEA,OAAO;AAAA,EACL;AAAA,EACA,CAAC;AAAA,EACD,YAAY;AACV,UAAM,QAAQ;AAAA,MACZ,gBAAgB,UAAU;AAAA,MAC1B,gBAAgB,SAAS,MAAM,GAAG,EAAE,CAAC;AAAA,IACvC;AAEA,QAAI,eAAe;AACjB,YAAM,KAAK,gBAAgB,aAAa,EAAE;AAC1C,UAAI;AACF,cAAM,MAAM,MAAM,eAAe,eAAe,MAAM;AACtD,cAAM,KAAK,gBAAgB,WAAW,GAAG,CAAC,eAAe;AAAA,MAC3D,SAAS,KAAK;AACZ,cAAM,KAAK,6BAA6B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC,GAAG;AAAA,MAC7F;AAAA,IACF,OAAO;AACL,YAAM,KAAK,IAAI,kEAA6D;AAAA,IAC9E;AAEA,UAAM,KAAK,IAAI,sEAAsE;AAErF,WAAO;AAAA,MACL,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,MAAM,KAAK,IAAI,EAAE,CAAC;AAAA,IAC7D;AAAA,EACF;AACF;AAIA,eAAe,OAAO;AACpB,QAAM,YAAY,IAAI,qBAAqB;AAC3C,QAAM,OAAO,QAAQ,SAAS;AAChC;AAEA,KAAK,EAAE,MAAM,CAAC,QAAQ;AACpB,UAAQ,MAAM,UAAU,GAAG;AAC3B,UAAQ,KAAK,CAAC;AAChB,CAAC;","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@arispay/payagent-mcp",
+  "version": "2.0.0",
+  "description": "MCP server for ArisPay-delegated x402 USDC payments. Use with Claude Desktop, Cursor, or any MCP client — no private keys in your process.",
+  "type": "module",
+  "bin": {
+    "payagent-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "arispay",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "ai-agent",
+    "http-402",
+    "x402",
+    "payment",
+    "usdc",
+    "stablecoin",
+    "claude",
+    "cursor",
+    "windsurf",
+    "agent-tool",
+    "delegated-custody"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Polar Industries Ltd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevemilton/payagent-mcp.git"
+  },
+  "homepage": "https://github.com/stevemilton/payagent-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "payagent": "^2.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  }
+}