twzrd-mcp 0.1.0

Auto-pay MCP server for the TWZRD Trust API (Solana x402). Free preflight/lookup + 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 bundled TypeScript path stays fail-closed until its hand-rolled header is replaced with the x402 JS SDK.

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 calls run the free preflight first; decision=block aborts the pay

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 ONLY via the official x402 SDK, not a hand-rolled header. 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

Remaining work for THIS (TypeScript) MCP

Replace the hand-rolled payAndRetry with the x402 JS SDK (SVM support) so the TS path matches the verified Python path. Note the x402 lib also ships an MCP module (x402.mcp) — a thin Python MCP over the proven client is the fastest route to a shippable auto-pay server. Keep the spend caps + preflight gate + free/paid split. Until the TS path is re-tested with the SDK it stays fail-closed; the payment mechanism itself is now proven.

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) — not yet shippable

The bundled TypeScript path is fail-closed until its hand-rolled X-Payment header is replaced with the x402 JS SDK (see Status). Use the Python package above for working auto-pay today.

Tools

• preflight (free) — allow/warn/block + trust_score before you pay
• wallet_lookup (free) — facilitators + counterparty breadth for a Solana wallet
• quick_trust ($0.001, auto-pay) — quick tier + score
• full_trust ($0.05, auto-pay) — full trust intel + signed V6 receipt (verify offline with twzrd-receipt-verifier)