{"_id":"@cardano402/mcp-server","_rev":"6-de595e67da5613e86c177eecc4d892f5","name":"@cardano402/mcp-server","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@cardano402/mcp-server","version":"0.1.0","keywords":["x402","cardano","mcp","model-context-protocol","agent","payment","stripe-for-agents"],"license":"Apache-2.0","_id":"@cardano402/mcp-server@0.1.0","maintainers":[{"name":"morganic","email":"mschofield89@gmail.com"}],"homepage":"https://github.com/MorganOnCode/cardano402#readme","bugs":{"url":"https://github.com/MorganOnCode/cardano402/issues"},"bin":{"cardano402-mcp":"dist/cli.js"},"dist":{"shasum":"f010d81fdd7787c2c0b054852402ae39b5d3472c","tarball":"https://registry.npmjs.org/@cardano402/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":9,"integrity":"sha512-CS+2fKWVRG01eznSc6YnqAoAbPjjyTRK/3jFaSBoiKjiGzHYXVQqBZ0GJviRQaDGb0sUzN/o0/BOwm8R3iuPlA==","signatures":[{"sig":"MEUCIQCjwL+87/KlVOnQVJLQ7Gc05Y4g04Vk1itVNCa1Jp+YXQIgVYDBzPsg50DWS2e568Z7puveFuaI/UhbaC3CAxqlIpg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":203307},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"1dc48d3fa1f1545877138c7e1abfc5bee5f1fd8d","scripts":{"test":"vitest run","build":"tsup","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm clean && pnpm build && pnpm test"},"_npmUser":{"name":"morganic","email":"mschofield89@gmail.com"},"deprecated":"Broken install (workspace:^ / EUNSUPPORTEDPROTOCOL) AND\n  security gaps. Upgrade to 0.1.2. Advisory:\n  https://github.com/MorganOnCode/cardano402/security/advisories/GHSA-rp72-5v5q-2446","repository":{"url":"git+https://github.com/MorganOnCode/cardano402.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"11.14.1","description":"MCP server that exposes paid HTTP endpoints as MCP tools, paying via the x402 Cardano scheme.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^4.4.3","@cardano402/core":"workspace:^","@lucid-evolution/lucid":"0.4.29","@lucid-evolution/provider":"0.1.90","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.7","typescript":"^6.0.3","@types/node":"^25.9.1","@vitest/coverage-v8":"^4.1.7"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.0_1779504063950_0.8739964744190076","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cardano402/mcp-server","version":"0.1.1","keywords":["x402","cardano","mcp","model-context-protocol","agent","payment","stripe-for-agents"],"license":"Apache-2.0","_id":"@cardano402/mcp-server@0.1.1","maintainers":[{"name":"morganic","email":"mschofield89@gmail.com"}],"homepage":"https://github.com/MorganOnCode/cardano402#readme","bugs":{"url":"https://github.com/MorganOnCode/cardano402/issues"},"bin":{"cardano402-mcp":"dist/cli.js"},"dist":{"shasum":"680eab0761ed744b823d96be95c4df25b80d8520","tarball":"https://registry.npmjs.org/@cardano402/mcp-server/-/mcp-server-0.1.1.tgz","fileCount":9,"integrity":"sha512-8uBFiG6CMPq34rxf7suy4f0aZDRPJujdNPo4ogCP8cCHCi103ltRGKkGOEyPoyFWewUcDybATfaIwIxUyoJQPg==","signatures":[{"sig":"MEUCIQCBR3ma/lud+E2LN9SjKTJFL8dpdBOVoiTLfJWWWMarywIgTdUV2vXuveXBA6n5Fi47ssEsHDco9YUgPn/HaA/uOnQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":204338},"main":"./dist/index.js","type":"module","_from":"file:cardano402-mcp-server-0.1.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"9b87bc5db7457c909e85722b4d0d3c1720553d1d","scripts":{"test":"vitest run","build":"tsup","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","typecheck":"tsc --noEmit","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"morganic","email":"mschofield89@gmail.com"},"_resolved":"/Users/morgan/Documents/CODE/cardano402-npm/repo/packages/mcp-server/cardano402-mcp-server-0.1.1.tgz","_integrity":"sha512-8uBFiG6CMPq34rxf7suy4f0aZDRPJujdNPo4ogCP8cCHCi103ltRGKkGOEyPoyFWewUcDybATfaIwIxUyoJQPg==","deprecated":"Security: missing spending limits + LAN-exposed HTTP\n  transport + SSRF in catalog.server.url. Upgrade to 0.1.2. Advisory:\n  https://github.com/MorganOnCode/cardano402/security/advisories/GHSA-rp72-5v5q-2446","repository":{"url":"git+https://github.com/MorganOnCode/cardano402.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"11.14.1","description":"MCP server that exposes paid HTTP endpoints as MCP tools, paying via the x402 Cardano scheme.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^4.4.3","@cardano402/core":"^0.2.0","@lucid-evolution/lucid":"0.4.29","@lucid-evolution/provider":"0.1.90","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.7","typescript":"^6.0.3","@types/node":"^25.9.1","@vitest/coverage-v8":"^4.1.7"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.1_1779505143943_0.99026259027052","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@cardano402/mcp-server","version":"0.1.2","keywords":["x402","cardano","mcp","model-context-protocol","agent","payment","stripe-for-agents"],"license":"Apache-2.0","_id":"@cardano402/mcp-server@0.1.2","maintainers":[{"name":"morganic","email":"mschofield89@gmail.com"}],"homepage":"https://github.com/MorganOnCode/cardano402#readme","bugs":{"url":"https://github.com/MorganOnCode/cardano402/issues"},"bin":{"cardano402-mcp":"dist/cli.js"},"dist":{"shasum":"260c0173ff15365e3308f081307287d442052dbc","tarball":"https://registry.npmjs.org/@cardano402/mcp-server/-/mcp-server-0.1.2.tgz","fileCount":9,"integrity":"sha512-9nq33FxGNjXPUe5Ci8/oD2jpJoZ8VVfo8WuWSnsdVdReahmZ7kKpi8Y6xxSGa4D0Z1hC/+hsLu93ZxcsIdJAjQ==","signatures":[{"sig":"MEQCIHUM34YkS+fEyhdDJT3p7L8rRwGOLQHmHs4kDI2Q78mZAiAxUViEQkONobgTjy0KcmwPVINSsUSF1sDqXwPRpXVMRg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":343210},"main":"./dist/index.js","type":"module","_from":"file:/tmp/mcp-publish-clean/cardano402-mcp-server-0.1.2.tgz","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"test":"vitest run","build":"pnpm gen:version && tsup","clean":"node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"","typecheck":"tsc --noEmit","test:watch":"vitest","gen:version":"node scripts/gen-version.mjs","test:coverage":"vitest run --coverage","verify:version":"node scripts/gen-version.mjs && git diff --exit-code src/generated-version.ts"},"_npmUser":{"name":"morganic","email":"mschofield89@gmail.com"},"_resolved":"/tmp/mcp-publish-clean/cardano402-mcp-server-0.1.2.tgz","overrides":{"libsodium-sumo":"0.8.2","libsodium-wrappers-sumo":"0.8.2"},"_integrity":"sha512-9nq33FxGNjXPUe5Ci8/oD2jpJoZ8VVfo8WuWSnsdVdReahmZ7kKpi8Y6xxSGa4D0Z1hC/+hsLu93ZxcsIdJAjQ==","repository":{"url":"git+https://github.com/MorganOnCode/cardano402.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"10.9.7","description":"MCP server that exposes paid HTTP endpoints as MCP tools, paying via the x402 Cardano scheme.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^4.4.3","@cardano402/core":"^0.2.0","@lucid-evolution/lucid":"0.4.29","@lucid-evolution/provider":"0.1.90","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.7","typescript":"^6.0.3","@types/node":"^25.9.1","@vitest/coverage-v8":"^4.1.7"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.2_1779687474550_0.454331333787352","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-23T02:41:03.823Z","modified":"2026-05-25T07:29:14.988Z","0.1.0":"2026-05-23T02:41:04.140Z","0.1.1":"2026-05-23T02:59:04.132Z","0.1.2":"2026-05-25T05:37:54.698Z"},"bugs":{"url":"https://github.com/MorganOnCode/cardano402/issues"},"license":"Apache-2.0","homepage":"https://github.com/MorganOnCode/cardano402#readme","keywords":["x402","cardano","mcp","model-context-protocol","agent","payment","stripe-for-agents"],"repository":{"url":"git+https://github.com/MorganOnCode/cardano402.git","type":"git","directory":"packages/mcp-server"},"description":"MCP server that exposes paid HTTP endpoints as MCP tools, paying via the x402 Cardano scheme.","maintainers":[{"name":"morganic","email":"mschofield89@gmail.com"}],"readme":"# @cardano402/mcp-server\n\nAn MCP (Model Context Protocol) server that exposes any x402-priced HTTP\nAPI as a set of MCP tools and handles the Cardano payment cycle on the\nagent's behalf.\n\nGiven a `/.well-known/x402.json` URL and a signing wallet, this package:\n\n1. Fetches the catalog and registers one MCP tool per paid endpoint.\n2. On tool invocation, makes the HTTP call, reads the `402 Payment\n   Required` response, builds and signs a Cardano transaction with\n   [Lucid Evolution](https://github.com/Anastasia-Labs/lucid-evolution),\n   retries with the `Payment-Signature` header, and returns the resource\n   to the calling agent.\n\n## CLI\n\n```bash\nSEED_PHRASE=\"word1 word2 ... word24\" \\\nBLOCKFROST_KEY=\"preview...\" \\\n  npx @cardano402/mcp-server \\\n    --catalog https://api.example.com/.well-known/x402.json \\\n    --transport stdio\n```\n\nFlags:\n\n| Flag                              | Default       | Notes                                                                                             |\n|-----------------------------------|---------------|---------------------------------------------------------------------------------------------------|\n| `--catalog <url>`                 | required      | Or set `CARDANO402_CATALOG_URL`                                                                   |\n| `--transport <name>`              | `stdio`       | `stdio` for local clients, `http` for Streamable HTTP                                             |\n| `--port <n>`                      | `3333`        | Only used when `--transport http`                                                                 |\n| `--listen-host <host>`            | `127.0.0.1`   | HTTP listen interface. Anything non-loopback **requires** `--http-bearer-token`                   |\n| `--network <name>`                | `Preview`     | `Preview`, `Preprod`, or `Mainnet`                                                                |\n| `--max-amount-per-call <lovelace>`| `5_000_000`   | Hard cap per signed transaction (5 ADA default)                                                   |\n| `--max-amount-per-day <lovelace>` | `50_000_000`  | Rolling 24h cap on signed amount (50 ADA default)                                                 |\n| `--pay-to-allowlist <a,b,c>`      | none          | Refuse to sign to addresses outside this comma-separated list                                     |\n| `--mainnet-confirmed-tools <a,b,c>` | none        | Required to register any tool whose catalog `network` is `cardano:mainnet`                        |\n| `--elicitation-threshold <lovelace>` | per-call cap | Amount above which an MCP `elicitation/create` confirmation is requested before signing       |\n| `--http-bearer-token <token>`     | none          | Require `Authorization: Bearer <token>` on every HTTP transport request                           |\n| `--http-origin-allowlist <a,b,c>` | loopback only | Additional `Origin` header values to accept                                                       |\n| `-h`, `--help`                    |               | Print usage                                                                                       |\n\nEnvironment:\n\n| Variable                              | Notes                                                                   |\n|---------------------------------------|-------------------------------------------------------------------------|\n| `SEED_PHRASE`                         | 24-word seed phrase for the wallet that will fund payments (required)   |\n| `BLOCKFROST_KEY`                      | Blockfrost project ID for the chosen network (required)                 |\n| `CARDANO402_CATALOG_URL`              | Alternative to `--catalog`                                              |\n| `CARDANO402_NETWORK`                  | Alternative to `--network`                                              |\n| `CARDANO402_ALLOW_INSECURE`           | `true` to permit non-HTTPS catalog URLs + private-CIDR base URLs        |\n| `MAINNET`                             | `true` is required to opt into a `Mainnet` connection                   |\n| `CARDANO402_LISTEN_HOST`              | Alternative to `--listen-host`                                          |\n| `MCP_HTTP_BEARER_TOKEN`               | Alternative to `--http-bearer-token`                                    |\n| `MCP_HTTP_ORIGIN_ALLOWLIST`           | Alternative to `--http-origin-allowlist`                                |\n| `CARDANO402_MAX_AMOUNT_PER_CALL`      | Alternative to `--max-amount-per-call`                                  |\n| `CARDANO402_MAX_AMOUNT_PER_DAY`       | Alternative to `--max-amount-per-day`                                   |\n| `CARDANO402_PAY_TO_ALLOWLIST`         | Alternative to `--pay-to-allowlist`                                     |\n| `CARDANO402_MAINNET_CONFIRMED_TOOLS`  | Alternative to `--mainnet-confirmed-tools`                              |\n| `CARDANO402_ELICITATION_THRESHOLD`    | Alternative to `--elicitation-threshold`                                |\n\n## Claude Desktop / Cursor config\n\n```json\n{\n  \"mcpServers\": {\n    \"example-api\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@cardano402/mcp-server\",\n        \"--catalog\",\n        \"https://api.example.com/.well-known/x402.json\"\n      ],\n      \"env\": {\n        \"SEED_PHRASE\": \"word1 word2 ... word24\",\n        \"BLOCKFROST_KEY\": \"preview...\"\n      }\n    }\n  }\n}\n```\n\n## Programmatic use\n\n```ts\nimport { startCardano402Mcp, loadConfig } from '@cardano402/mcp-server';\n\nconst handle = await startCardano402Mcp(\n  loadConfig({ argv: process.argv.slice(2), env: process.env })\n);\n\nprocess.on('SIGTERM', () => void handle.stop());\n```\n\n## Transports\n\n- **`stdio`** — JSON-RPC over stdin/stdout. Use this with desktop MCP\n  clients (Claude Desktop, Cursor).\n- **`http`** — MCP Streamable HTTP per the\n  [MCP transport spec](https://modelcontextprotocol.io/). Sessions are\n  created on first request; the session id is returned in the\n  `Mcp-Session-Id` response header and must be echoed back on subsequent\n  requests.\n\n## Tool naming\n\nTool names follow the same recipe as\n`/.well-known/mcp/server-card.json` in cardano402's facilitator: lower-\ncased method, underscore, sanitised path. For example, a catalog entry\n`POST /api/analyze` becomes the tool `post_api_analyze`.\n\n## Security posture\n\n- **Per-call + per-day spending caps.** Refuses to sign a payment that\n  exceeds `--max-amount-per-call` (default 5 ADA) or that would push\n  the rolling 24-hour total over `--max-amount-per-day` (default 50\n  ADA). Optional `--pay-to-allowlist` rejects signings to addresses\n  outside the list. The gate runs *before* the signer touches a UTXO.\n- **MCP elicitation/confirmation for large payments.** When the\n  requested amount exceeds `--elicitation-threshold` (defaults to the\n  per-call cap), the server sends an MCP `elicitation/create` request\n  to the client and requires an explicit `yes` before signing.\n- **HTTP transport defaults to loopback.** `--transport http` binds\n  `127.0.0.1` by default. Anything else requires `--http-bearer-token`\n  (so a wallet RPC is never exposed on a LAN/WAN without auth). The\n  transport also checks the `Origin` header (loopback +\n  `--http-origin-allowlist` only) and the bearer token on every\n  request.\n- **Mainnet tools are opt-in per-tool.** Catalog endpoints whose\n  `network` is `cardano:mainnet` are dropped at register-time unless\n  the operator names the derived tool in `--mainnet-confirmed-tools`.\n  This is on top of the existing `MAINNET=true` env-var gate.\n- **SSRF guard.** `catalog.server.url` and the catalog URL itself are\n  rejected if they resolve to a private, loopback, link-local, CGNAT,\n  multicast, ULA, or IPv4-mapped IPv6 address (`169.254.169.254`,\n  `fc00::/7`, etc) — unless `CARDANO402_ALLOW_INSECURE=true`.\n- **Path validation.** Endpoint paths containing `..`, NUL bytes,\n  whitespace, CR/LF, or anything that looks like an absolute URL are\n  rejected at register-time.\n- The signing wallet's seed phrase is read from `SEED_PHRASE` and lives\n  only in process memory. It is never logged.\n- By default the server refuses to fetch a non-HTTPS catalog URL or to\n  POST signed transactions to one, unless it's a loopback host. Override\n  with `CARDANO402_ALLOW_INSECURE=true` if you really mean it.\n- Mainnet requires an explicit `MAINNET=true` env var as a guardrail\n  against accidentally pointing the signer at real ADA.\n- Before paying, the live `402` response is cross-checked against the\n  catalog: a resource server that quotes a different `payTo` / `amount`\n  / `network` at runtime than its catalog advertised is refused.\n- The resource-server response body is nested under\n  `__rawFromUntrustedResourceServer` in the tool's structured output so\n  attacker-supplied keys can't shadow `status`, `payment`, or\n  `contentType`. Catalog descriptions are stripped of control chars\n  and wrapped in an \"untrusted catalog description\" envelope.\n\nSee the cardano402 root [`SECURITY.md`](../../SECURITY.md) for the\ndisclosure channel.\n\n## Known issues / consumer-side overrides\n\n### `libsodium-wrappers-sumo` transitive resolution\n\n> **0.1.2 update:** the published package now ships an npm-format\n> `overrides` block pinning `libsodium-wrappers-sumo` and\n> `libsodium-sumo` to `0.8.2`. That covers consumers installing via\n> `npm` or `yarn` (both honor top-level `overrides` from the installed\n> package's manifest). **pnpm consumers still need their own\n> `pnpm.overrides` block** — pnpm only reads `overrides` from the\n> workspace root, not from transitives.\n\nOn a fresh `npm install` / `pnpm add` of this package, Lucid Evolution's\ndeep transitive `@cardano-sdk/crypto` pulls in\n`libsodium-wrappers-sumo@0.7.x`. That version uses a broken ESM import\n(`import e from \"./libsodium-sumo.mjs\"` — the file isn't in the package),\nso the server crashes at signer-init time with:\n\n```\nERR_MODULE_NOT_FOUND: Cannot find module\n  '.../libsodium-wrappers-sumo/dist/modules-sumo-esm/libsodium-sumo.mjs'\n```\n\nThe fix landed upstream in `libsodium-wrappers-sumo@0.8.0` (changed to a\nbare specifier, `import e from \"libsodium-sumo\"`). Until\n`@cardano-sdk/crypto` bumps its range, consumers need to override the\nversion themselves. Add one of the following to your project's\n`package.json`:\n\n**pnpm:**\n\n```json\n{\n  \"pnpm\": {\n    \"overrides\": {\n      \"libsodium-wrappers-sumo\": \"^0.8.2\",\n      \"libsodium-sumo\": \"^0.8.2\"\n    }\n  }\n}\n```\n\n**npm (>= 8.3):**\n\n```json\n{\n  \"overrides\": {\n    \"libsodium-wrappers-sumo\": \"^0.8.2\",\n    \"libsodium-sumo\": \"^0.8.2\"\n  }\n}\n```\n\nThen re-install. The package's own test suite (37 tests, mocked\nsigner) is unaffected; this only bites at runtime when Lucid is\nactually initialized.\n\nTracking upstream: [input-output-hk/cardano-js-sdk#1682](https://github.com/input-output-hk/cardano-js-sdk/issues/1682).\nThis package will bump Lucid (and drop the override note) once the\nupstream fix lands.\n\n## Smoke testing\n\n`scripts/smoke.mjs` (not shipped in the npm tarball) exercises the full\npreview-testnet path end-to-end without requiring an external resource\nserver. It boots a tiny inline HTTP server with one priced endpoint\n(pay-to-self, 2 ADA), spawns `dist/cli.js` as a stdio subprocess,\ndrives `initialize` → `tools/list` → `tools/call`, submits the signed\ntx via Blockfrost, and asserts the resulting `X-Payment-Response` is\nreal.\n\nRun from the package root:\n\n```bash\nSEED_PHRASE=\"word1 ... word24\" \\\nBLOCKFROST_KEY=\"previewXXXXXXXXXXXXXXXXXXXXXXXX\" \\\n  node scripts/smoke.mjs\n```\n\nThe wallet needs ~3 preview ADA (faucet:\nhttps://docs.cardano.org/cardano-testnets/tools/faucet/). Net cost per\nrun is the tx fee (~0.2 ADA).\n\nOn success the script prints a `preview.cardanoscan.io` URL for the\ntransaction. Use this whenever cutting a release that changes the\npayment loop or signer.\n\n## Status\n\n`0.1.2`. Security release fixing C5 (no spending limits), H10\n(LAN-exposed HTTP transport), and H11 (SSRF via `catalog.server.url`).\nSee `CHANGELOG.md` for full notes and the linked GHSA. `0.1.1` end-to-end\nproof tx (unchanged signer code path):\n`2845a731c935348ba2ba620b50640c7e3553da717773c1f8456decd49fe2dab7`.\n","readmeFilename":"README.md"}