# twzrd-mcp-server > Local, spend-capped Solana x402 client for TWZRD Agent Intelligence; prefer the hosted MCP. Latest version **0.5.7** (published 2026-10-02) · MIT license · 0 weekly downloads ## Install ```sh npm install twzrd-mcp-server pnpm add twzrd-mcp-server yarn add twzrd-mcp-server bun add twzrd-mcp-server ``` Provides the command `twzrd-mcp-server`. ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.5.7 | | Published | 2026-10-02 | | First published | 2026-06-27 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=20 | | Dependencies | 7 | | Unpacked size | 40.4 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | twzrd1111 | | Keywords | mcp, x402, solana, agent, trust, twzrd, reputation | ## Links - npm: https://www.npmjs.com/package/twzrd-mcp-server - Repository: https://github.com/twzrd-sol/twzrd-trust - Homepage: https://intel.twzrd.xyz - Issues: https://github.com/twzrd-sol/twzrd-trust/issues - npm.io page: https://npm.io/package/twzrd-mcp-server ## Dependencies (7) - [bs58](https://npm.io/package/bs58.md) ^6.0.0 - [@x402/svm](https://npm.io/package/@x402/svm.md) ^2.26.0 - [@x402/core](https://npm.io/package/@x402/core.md) ^2.26.0 - [@solana/kit](https://npm.io/package/@solana/kit.md) ^5.1.0 - [twzrd-x402-gate](https://npm.io/package/twzrd-x402-gate.md) 0.11.4 - [twzrd-receipt-verifier](https://npm.io/package/twzrd-receipt-verifier.md) ^1.4.0 - [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.0.0 ## Recent versions - 0.5.7 (latest) — 2026-10-02 - 0.5.6 — 2026-10-01 - 0.5.5 — 2026-09-18 - 0.5.4 — 2026-09-13 - 0.5.3 — 2026-09-06 - 0.5.2 — 2026-08-28 - 0.5.1 — 2026-08-17 - 0.5.0 — 2026-07-23 - 0.4.1 — 2026-07-22 - 0.4.0 — 2026-07-12 - 0.3.2 — 2026-07-11 - 0.3.1 — 2026-06-30 - 0.3.0 — 2026-06-29 - 0.2.9 — 2026-06-28 - 0.2.8 — 2026-06-27 - … 9 more at https://npm.io/package/twzrd-mcp-server/versions ## README # twzrd-mcp-server / twzrd-mcp — pre-spend seller reputation for Solana x402 Check a seller wallet and requested resource **before** you pay over Solana x402. Free tools return allow / warn / block. Paid clearance is **$0.001** `quick_trust` / `twzrd.payment_decision.v1`. Optional `$0.05` `full_trust` is Path A intel, not the primary SKU. TWZRD scores observed wallet and payment behavior. It does not prove a person, company, or autonomous agent identity. **Prefer the zero-install hosted Agent Intelligence MCP. Use this package only when you want local auto-pay for paid intel.** ```json // Recommended — full hosted tool set, no wallet, nothing to install { "mcpServers": { "twzrd": { "url": "https://intel.twzrd.xyz/mcp" } } } ``` ```bash # Local auto-pay client — 6 tools; wallet only if you enable paid calls npx -y twzrd-mcp-server # Node pip install twzrd-mcp # Python ``` - **npm** (Node): [`twzrd-mcp-server`](https://www.npmjs.com/package/twzrd-mcp-server) - **PyPI** (Python): [`twzrd-mcp`](https://pypi.org/project/twzrd-mcp/) - Agent Intelligence: · repo: [twzrd-sol/twzrd-trust](https://github.com/twzrd-sol/twzrd-trust/tree/main/twzrd-mcp-server) ## Which surface do I want? | Surface | Tool set | Wallet | Use when | |---------|-------|--------|----------| | `https://intel.twzrd.xyz/mcp` (hosted) | Full hosted set (live `tools/list`) | No | Default. Seller preflight, resource evaluation, reputation, receipts, watches, product-listing checks (`check_listing`), and observed-market research. | | `twzrd-mcp-server` / `twzrd-mcp` (this local package) | 6 local tools | Only for paid | You want `quick_trust` / `full_trust` auto-paid locally with caps. | Start with hosted `twzrd_demo_gate` for a zero-setup, zero-spend transcript of the block path: a recorded example, not a live run. The hosted MCP is also [listed on Smithery](https://smithery.ai/servers/wzrd/twzrd-agent-intel). ## The 6 local client tools | Tool | Cost | What | |------|------|------| | `preflight` | free | allow / warn / block + trust score for a **seller you're about to pay** | | `merchant_card` | free | seller graph card — `wash_flagged: true` → **don't pay** (locked sequence step 2) | | `wallet_lookup` | free | facilitators + counterparty breadth for a wallet | | `verify_receipt` | free | offline-verify a wallet's cNFT receipt (Ed25519 vs genesis authority `2ELSDxLkb7dYrN6EUG69tNtULAq4Fo7WPvXyrZPmuFif`) — trust no server | | `quick_trust` | **$0.001** | Clearance SKU: `twzrd.payment_decision.v1` / quick tier + score | | `full_trust` | $0.05 | Optional Path A intel + signed V7 receipt — not the primary SKU | > `quick_trust` / `full_trust` buy intel on **any** wallet (you look risky ones up > on purpose) — they don't refuse a target. Use `preflight` to vet a wallet you're > about to *pay elsewhere*. ## Happy path (seller-first) 1. **Free `preflight`** on the seller's receive wallet. 2. `block` → don't pay. Done, $0 spent. 3. **Free `merchant_card`** on the same wallet — `wash_flagged: true` → don't pay. 4. `warn` → **$0.001** `quick_trust` / `payment_decision.v1` clearance. Optional `$0.05` `full_trust` is Path A intel, not the primary SKU. 5. `allow` + clean card + small spend → pay. Keep the receipt; scores decay, so re-check stale decisions. ## Install & config Paid tools are **opt-in on both runtimes**: they sign only when you set `TWZRD_MCP_PAYMENTS_ENABLED=1` **and** provide a wallet key. For free tools, omit both — the server runs read-only and never signs. Spend is bounded by per-call and session caps. Before any Solana signature the Node server runs `twzrd-x402-gate@0.11.4` wash default (Python `twzrd-mcp` 0.2.2 does the same `merchant_card` check on the 402 `payTo`): abort iff `wash_flagged===true`, and fail closed if intel cannot answer (timeout, 5xx/429, unreadable body): an outage is never read as clean. That is the paying-client brake, not a Path A shop. ### Python — `pip install twzrd-mcp` ```json { "mcpServers": { "twzrd": { "command": "twzrd-mcp", "env": { "TWZRD_RPC_URL": "", "TWZRD_WALLET_KEYPAIR": "/path/to/solana-keypair.json", "TWZRD_MCP_PAYMENTS_ENABLED": "1", "TWZRD_MAX_USDC_PER_CALL": "0.05", "TWZRD_MAX_USDC_TOTAL": "1.00" } }}} ``` ### Node — `npx -y twzrd-mcp-server` ```json { "mcpServers": { "twzrd": { "command": "npx", "args": ["-y", "twzrd-mcp-server"], "env": { "TWZRD_RPC_URL": "", "TWZRD_WALLET_SECRET_KEY": "", "TWZRD_MCP_PAYMENTS_ENABLED": "1", "TWZRD_MAX_USDC_PER_CALL": "0.05", "TWZRD_MAX_USDC_TOTAL": "1.00" } }}} ``` | Env var | Default | Meaning | |---------|---------|---------| | `TWZRD_MCP_PAYMENTS_ENABLED` | unset (off) | set `1` to arm paid tools — **required on both runtimes** | | `TWZRD_WALLET_SECRET_KEY` (Node) / `TWZRD_WALLET_KEYPAIR` (Python) | — | signer for paid tools | | `TWZRD_MAX_USDC_PER_CALL` | `0.05` | per-call spend cap | | `TWZRD_MAX_USDC_TOTAL` | `1.00` | cumulative session spend cap | | `TWZRD_RPC_URL` | **none — required for paid tools** | Solana RPC. Paid tools refuse to arm without it: the public RPC is rate-limited and loses x402 races (stale blockhash / sponsored feePayer between the 402 challenge and the signed retry), and a rejected settle can still move USDC. Free tools need no RPC. The Solana Foundation public endpoints (`api.mainnet-beta`, `api.devnet` and `api.testnet` `.solana.com`, trailing dots ignored) and any URL with a `/public` path segment are refused, by the Node server and by the Python client; other shared public RPCs are not detected, so choose a dedicated one. `TWZRD_ALLOW_PUBLIC_RPC` no longer enables a refused URL. | ## Safety - **Opt-in payments** — paid tools sign only with `TWZRD_MCP_PAYMENTS_ENABLED=1`; a wallet key alone never arms spending. - **Spend caps** — per-call and session caps enforced in the payment selector *before* any signature. Caps use the mint's **true** decimals, never merchant-declared `extra.decimals`. A mismatched declaration is refused. A malformed cap env (e.g. `"$0.05"`) falls back to the default; it never becomes NaN and disables the cap. - **Known-asset only** — pay only known USD-pegged stables (USDC/USDT); unknown SPL mints are refused. - **Identifiable recipient** — a challenge with no `payTo` is refused. - **Solana-only** — a non-`exact` / non-`solana:` challenge is refused, never mis-signed. - **Single-shot retry** — at most one signed retry per tool call; a second 402 is surfaced, not silently re-paid. - **Free tools never enter the payment path.** ## Verify receipts offline (trust no one) `full_trust` returns a portable Ed25519-signed V7 receipt. Verify it without trusting any TWZRD server — new receipts use issuer key `twzrd-receipt-ed25519-v2`; legacy v1 keys remain verify-only during the bounded compatibility rollout. (`Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS`), pinned at : ```bash npx twzrd-receipt-verifier --pubkey Ak5SQwHpuQAqU7ty7ZWX7qgF39A9yi72c22KNn8sHzvS ``` ## Development This directory in the public mirror is **`dist/` only**. `npm run build` is a no-op echo. `npm run demo` exits 1 on purpose — the in-tree demo imports a gate export this workspace copy does not provide. Use hosted MCP `https://intel.twzrd.xyz/mcp` or `npx -y twzrd-mcp-server` from npm. Do not treat this checkout as a from-source MCP build. --- Links: [Agent Intelligence](https://intel.twzrd.xyz) · [hosted MCP](https://intel.twzrd.xyz/mcp) · [llms.txt](https://intel.twzrd.xyz/llms.txt) · [llms-full.txt](https://intel.twzrd.xyz/llms-full.txt) · [OpenAPI](https://intel.twzrd.xyz/openapi.json) License: MIT --- _Source: https://npm.io/package/twzrd-mcp-server · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._