tools402 as an MCP server.

Setup in 2 steps no account

1. Generate a session token (runs locally) EVM chains (default Base): sign an EIP-3009 transferWithAuthorization offline. Solana: sign an SPL Approve delegating spend to tools402's facilitator (gasless pulls afterward).
   bash · EVMcopy

   # Generate the token with the copy-paste snippet — no CLI, no package:
   #   https://tools402.dev/docs/integrations#session-token
   # Sign an EIP-3009 transferWithAuthorization offline (viem). The chain is
   # embedded in the token payload (base | polygon | …). Then:
   export TOOLS402_SESSION_TOKEN=<token>

   bash · Solanacopy

   # Solana: sign an SPL Approve delegating spend to the facilitator (gasless),
   # using a keypair file instead of an EVM hex key.
   # Full copy-paste Solana flow: https://tools402.dev/docs/integrations
   export TOOLS402_SESSION_TOKEN=<token>

2. Add the MCP server to your host Match TOOLS402_CHAIN to the chain you authorized. Package pin is hydrated from /sdk-versions.json (currently @tools402/mcp@—).
   bash · Claude Codecopy

   claude mcp add tools402 \
     --command "bunx @tools402/mcp@—" \
     --env TOOLS402_SESSION_TOKEN=<token> \
     --env TOOLS402_CHAIN=base
   
   # → 159 tools from GET /v1/_meta, including /v1/agent/*
   # Missing token → stderr points here: https://tools402.dev/docs/mcp

   Cursor / Claude Desktop JSON config:

   jsoncopy

   {
     "mcpServers": {
       "tools402": {
         "command": "bunx",
         "args": ["@tools402/mcp@—"],
         "env": {
           "TOOLS402_SESSION_TOKEN": "<token>",
           "TOOLS402_CHAIN": "base"
         }
       }
     }
   }

Chain matrix session mode

MCP session mode uses gasless facilitator pulls — you never broadcast payment txs from the agent runtime. 402 quotes accept Base, Polygon, and Solana — 3 facilitators per chain. See multi-chain docs for payout chains and CCTP.

Per-call exact (buyer-broadcasts) and Solana spl-transfer schemes remain available outside MCP via raw HTTP — see integrations.

Revoke & security honest limits

The session token is a signed spending mandate: capped at --amount USDC, expiring after --days. tools402 deducts atomic amounts off-chain until the cap is exhausted. Your wallet key never leaves your machine — only the mandate travels in the X-Session-Token header.

What you can revoke

• EVM (Base, Polygon) — wait for validBefore expiry, or consume the cap. USDC EIP-3009 authorizations are one-shot per nonce once submitted on-chain; tools402 tracks remaining budget off-chain. There is no instant on-chain cancel of an unused EIP-3009 authorization before expiry — worst case if tools402 is compromised: lose up to --amount USDC before deadline.
• Solana — run spl-token revoke <your-usdc-ata> to zero the delegate immediately. Also expires at validBefore. Already-settled transfers are not reversible.
• MCP config — remove the server or rotate TOOLS402_SESSION_TOKEN any time; that stops new calls but does not claw back on-chain delegate authority on Solana until you revoke.

What you cannot revoke

• Individual API calls already settled on-chain (USDC transfer is final).
• Off-chain session budget already consumed (generate a fresh token to continue).

# find your USDC associated token account (ATA), then:
spl-token revoke EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --owner ~/.config/solana/id.json

Copy-paste examples paid call

Session mode sends X-Session-Token instead of X-Payment. tools402's facilitator pulls USDC gaslessly. Replace <token> with your mandate. The chain is embedded in the token (the chain field in the token payload you signed) — the API reads auth.chain from the token, not an X-Tools402-Chain header.

curl · session

curl -X POST https://api.tools402.dev/v1/uuid-generate \
  -H "X-Session-Token: <token>" \
  -H "Content-Type: application/json"

# → 200 · {"uuid":"…"}  (facilitator submits EIP-3009, ~$0.00001 gas absorbed)
# Chain = the `chain` field in your signed token payload (base, polygon, solana, …)

Python · session (httpx)

# pip install httpx
import os, httpx

token = os.environ["TOOLS402_SESSION_TOKEN"]
r = httpx.post(
    "https://api.tools402.dev/v1/md-html",
    headers={"X-Session-Token": token},
    json={"markdown": "# Hello"},
)
print(r.json())

Node · session (fetch)

// Node 18+ — global fetch, zero dependencies
const token = process.env.TOOLS402_SESSION_TOKEN;

const resp = await fetch("https://api.tools402.dev/v1/slug-generate", {
  method: "POST",
  headers: {
    "X-Session-Token": token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "My Product Name" }),
});
console.log(await resp.json());

Solana · spl-transfer (402, not session)

When you are not using MCP session mode — e.g. one-off curl from a Solana wallet — the buyer pre-signs an SPL transfer and the facilitator co-signs as fee payer:

// 1 · 402 quote — pick accept where network === "solana" from the body
const q = await fetch("https://api.tools402.dev/v1/ocr", {
  method: "POST",
  body: formData,
});
// → accepts[0].scheme === "spl-transfer" · extra.feePayer === "facilitator"

// 2 · build TransferChecked, partial-sign (buyer only — do NOT broadcast)
const serializedTx = tx.serialize({ requireAllSignatures: false })
  .toString("base64");

// 3 · retry with X-Payment (facilitator stack pays gas + broadcasts)
const xPayment = Buffer.from(JSON.stringify({
  x402Version: 1,
  scheme: "spl-transfer",
  network: "solana",
  payload: {
    serializedTx,
    signature: buyerSig,
    from: buyerPubkey,
    to: quote.payTo,
    mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    amount: quote.maxAmountRequired,
  },
})).toString("base64url");

await fetch("https://api.tools402.dev/v1/ocr", {
  method: "POST",
  headers: { "X-Payment": xPayment },
  body: formData,
});

MCP on Solana uses the delegate session path instead — same gasless UX as EIP-3009 on EVM. See integrations · Solana curl for the full spl-transfer walkthrough.

Environment variables reference

AP2-compatible descriptor (touchpoint E2) is advertised in the MCP server metadata — see /docs/ap2.