twzrd-mcp 0.1.4

Auto-pay MCP server for the TWZRD Trust API (Solana x402). Free preflight/lookup/receipt-verify + auto-paid trust intel with spend caps. Payment path mainnet-proven via the official x402 SDK.

twzrd-mcp-server - auto-pay MCP for the TWZRD Trust API

Payment mechanism is mainnet-verified via the official x402 SDK (Python path, $0.001 moved 2026-06-26 - see Status). The Node package is published on npm as twzrd-mcp-server; v0.2.5 source adds the single-shot payment guard required before the next live paid proof.

Auto-pay MCP server for TWZRD's Trust API, matching the competitor GTM shape (anchor-x402, Br0ski777, BitBooth all ship one). An agent adds one mcpServers entry; paid tool calls auto-handle the x402 challenge. Free tools never pay.

Why this is a corrected rebuild

A first draft signed EIP-3009 on Base (EVM/viem). TWZRD settles x402 on Solana (scheme:"exact", USDC, sponsored feePayer) — the EVM scheme never matches the challenge, so that draft could not pay TWZRD at all (it would tsc-pass yet fail every real call). This version is Solana-native and refuses any non-Solana challenge instead of mis-signing.

Safety guardrails (enforced before any signature)

• Per-call cap TWZRD_MAX_USDC_PER_CALL (default 0.05)
• Cumulative session cap TWZRD_MAX_USDC_TOTAL (default 1.00)
• Free discovery tools never enter the payment path
• No cross-chain fallback — a non-exact/non-solana: challenge is rejected
• Paid trust calls buy intel on the target wallet by design; use the free preflight tool separately to vet a seller before paying it elsewhere.

Status — payment path VERIFIED on mainnet 2026-06-26

Two authorized settles from dev wallet 2pHjZLqs…:

1. Hand-rolled X-Payment (this MCP's original approach): FAILED — HTTP 402, no USDC moved. The intel host validates via the official x402 lib's PaymentPayload, so a hand-built header is rejected. (Green tsc ≠ settles — fail-closed default was correct.)
2. Official x402 SDK: SUCCEEDED — GET /v1/intel/quick/CqtQPaAuQ5UR… → HTTP 200, "paid":true,"charged_amount_usdc":0.001, tier Silver score 53.6. USDC balance moved 0.057236 → 0.056236 (exactly $0.001). A second call against a no-data pubkey returned 422 charged:false — the server's no-charge-on-empty guard works.

Conclusion: auto-pay works through the official x402 SDK path. Proven client wiring (Python):

from x402.client import x402ClientSync
from x402.mechanisms.svm.signers import KeypairSigner
from x402.mechanisms.svm.exact import register_exact_svm_client
from x402.http.clients.requests import x402_requests
client = x402ClientSync()
register_exact_svm_client(client, KeypairSigner(keypair), rpc_url=RPC)
session = x402_requests(client)
session.get("https://intel.twzrd.xyz/v1/intel/quick/<wallet>")  # auto-pays $0.001

TypeScript path — integrated (v0.2.5)

The TypeScript path uses the official x402 JS SDK (@x402/core client + @x402/svm ExactSvmScheme). @x402/svm reads the challenge extra.feePayer and builds the partially-signed sponsored transfer, and x402HTTPClient encodes the X-PAYMENT header the server validates. Spend caps + free/paid split are preserved — caps are enforced in the payment selector before any signature.

Important: v0.2.5 uses a single-shot paid retry. The first SDK-backed E2E found that the generic @x402/fetch wrapper can re-pay after a transient-looking settle response, moving $0.003 across two $0.001 calls. This package now performs at most one signed retry per logical tool call; any second 402 is surfaced instead of silently paying again.

Next verification step: one operator-authorized $0.001 quick_trust settle through v0.2.5, followed by offline receipt verification.

Install & Config

Python (recommended — the mainnet-proven path)

pip install twzrd-mcp

MCP client config (mcpServers):

{ "mcpServers": { "twzrd": {
  "command": "twzrd-mcp",
  "env": {
    "TWZRD_RPC_URL": "<your Solana 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"
  }
}}}

The free tools (preflight, wallet_lookup) need no wallet and no flags — leave TWZRD_MCP_PAYMENTS_ENABLED unset and they work read-only. Only the paid tools need the keypair + TWZRD_MCP_PAYMENTS_ENABLED=1.

Node (npx twzrd-mcp-server) — x402 JS SDK

npx -y twzrd-mcp-server --help

{ "mcpServers": { "twzrd": {
  "command": "npx", "args": ["-y", "twzrd-mcp-server"],
  "env": {
    "TWZRD_WALLET_SECRET_KEY": "<base58 Solana secret>",
    "TWZRD_RPC_URL": "<your Solana RPC url>",
    "TWZRD_MAX_USDC_PER_CALL": "0.05",
    "TWZRD_MAX_USDC_TOTAL": "1.00"
  }
}}}

Auto-pay is enabled whenever TWZRD_WALLET_SECRET_KEY is present (set TWZRD_MCP_PAYMENTS_ENABLED=0 to force paid tools off). Free tools need no wallet. The package is published on npm; v0.2.5 is the next source release that includes the single-shot double-settle guard.

One-command Agent Demo

The packaged demo starts the MCP server over stdio, lists the tools, and runs a live free preflight. It is no-spend by default, even if your shell has a wallet secret:

npm run build
npm run demo

Turn the same demo into the operator-authorized $0.001 settle proof by changing one env var and setting tight caps:

TWZRD_DEMO_PAID=quick \
TWZRD_WALLET_SECRET_KEY="<base58 Solana secret>" \
TWZRD_RPC_URL="<mainnet RPC>" \
TWZRD_MAX_USDC_PER_CALL=0.001 \
TWZRD_MAX_USDC_TOTAL=0.001 \
node examples/agent-drop-in.mjs

For the full signed-receipt path, use TWZRD_DEMO_PAID=full and set both caps to 0.05; the demo verifies any returned receipt through the MCP verify_receipt tool. To additionally pipe that receipt into the standalone verifier package:

TWZRD_DEMO_PAID=full \
TWZRD_DEMO_RUN_VERIFIER_SELF_TEST=1 \
TWZRD_WALLET_SECRET_KEY="<base58 Solana secret>" \
TWZRD_RPC_URL="<mainnet RPC>" \
TWZRD_MAX_USDC_PER_CALL=0.05 \
TWZRD_MAX_USDC_TOTAL=0.05 \
node examples/agent-drop-in.mjs

Tools

• preflight (free) — allow/warn/block + trust_score before you pay a seller you're about to transact with
• wallet_lookup (free) — facilitators + counterparty breadth for a Solana wallet
• verify_receipt (free) — independently verify a wallet's cNFT Receipt offline (Ed25519 vs the genesis authority 2ELSDx); no trust in any TWZRD server
• quick_trust ($0.001, auto-pay) — quick tier + score for any wallet
• full_trust ($0.05, auto-pay) — full trust intel + signed V6 receipt

Note: quick_trust/full_trust pay TWZRD a fixed micro-fee for intel on any wallet — they do not refuse "risky" targets (you look those up on purpose). Use preflight to vet a counterparty you're about to pay elsewhere.