Toolsnap MCP Server

ToolSnap MCP

One connection, superpowers for your agent: deterministic microtools. Pay per call with USDC on Base — no account needed — or buy fiat credits with a card if you'd rather not touch crypto.

Live endpoint: https://mcp.toolsnap.app/mcp
Server card: /.well-known/mcp.json
Pricing: /.well-known/pricing.json
Docs: mcp.toolsnap.app/docs

---

Why

ToolSnap is built around three ideas:

1. Deterministic — no LLM in the loop. Most agent stacks now "clean" web pages by paying a second model to summarize them. ToolSnap's extraction is pure parsing: exact quotes, stable output, zero added inference cost, reproducible runs. What you extract is what the page said.

2. Context-efficient by design. The biggest cost for AI agents isn't generation — it's context. Loading a raw webpage can burn 50,000+ tokens on HTML boilerplate; connecting a fat MCP server can burn as many in tool definitions. ToolSnap moves the work server-side and keeps discovery compact: tools/list shows a small curated core, and the full catalog of 47 microtools (web, PDFs, CSV/JSON, sitemaps, RSS, images, media generation…) sits one free tool_catalog() call away, executed via use_tool.

Benchmark (11 real pages, June 2026):

fetch_extract is free — this saving costs nothing.

3. No account required (crypto path). Free tools work the second you connect. Paid tools settle per call with USDC on Base via x402 — an agent with a wallet can pay cold: no signup, no subscription, no key management. Rather not touch crypto? Buy fiat credits with a card and get an API key instead — same discounted per-call price, no wallet needed.

---

Connect

Any agent, one line

Hand your agent this prompt and it can do the rest on its own:

Set up https://mcp.toolsnap.app/SKILL.md — connect the MCP server it describes and save the skill for future sessions.

SKILL.md is a self-contained skill file (connect config, tool discovery, cost guardrails), generated live from the tool registry so it is never stale.

Claude Desktop

{
  "mcpServers": {
    "toolsnap": {
      "url": "https://mcp.toolsnap.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Free tools work immediately with the URL connection above. Paid tools need an x402 payment client — a wallet alone is not enough, because most MCP clients can't satisfy a 402 Payment Required on their own. Use the pay-proxy below (re-download it if your copy predates the 2026-10 spec-shaped 402, see Payment).

Claude Code

claude mcp add --transport http toolsnap https://mcp.toolsnap.app/mcp

Or install the Claude Code plugin (MCP connection + the toolsnap skill, bundled):

/plugin marketplace add ToolSnap-app/toolsnap-claude-plugin
/plugin install toolsnap

Paid tools — connect through the pay-proxy

scripts/pay-proxy.mjs is a local stdio MCP server that wraps the remote endpoint, reads your wallet, and signs + retries automatically when the server asks for payment. The private key never leaves your host; only signatures are sent.

{
  "mcpServers": {
    "toolsnap": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/to/toolsnap-mcp/scripts/pay-proxy.mjs"]
    }
  }
}

No wallet yet? Call the wallet_setup tool — it generates a wallet you control, helps your human fund it with USDC on Base, and wires this proxy. Key resolution order: TOOLSNAP_WALLET_KEY → ~/.toolsnap/wallet.key → macOS Keychain (toolsnap-agent-wallet/default).

Useful env: TOOLSNAP_MAX_PRICE_USDC (per-call spend cap, default 0.10), TOOLSNAP_PREPAID=1 + TOOLSNAP_AUTO_DEPOSIT_USDC (use the cheaper prepaid balance).

Paid tools — no wallet, pay with a card

Buy credits at mcp.toolsnap.app/checkout (handled by Polar, our Merchant of Record). You'll get an API key in a one-time pop-up — connect with it directly, no proxy needed:

{
  "mcpServers": {
    "toolsnap": {
      "url": "https://mcp.toolsnap.app/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Clients that can't send custom headers (some claude.ai connectors) can embed the key in the URL instead: https://mcp.toolsnap.app/mcp/sk_live_... (the key may then appear in that client's request logs — prefer the header when your client supports it).

Direct MCP call

curl -X POST https://mcp.toolsnap.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

Tools

47 tools total. tools/list shows a curated core of 17; discover everything else with the free tool_catalog tool and run it with use_tool(name, args).

Paid (x402)

No first-call-free: these tools have real per-call cost, so every call settles from the start. Media tools are priced per call from your own args (the table shows the floor). Pay-per-call is USDC on Base using x402 v2 (EIP-3009 transferWithAuthorization); prepaid (deposit once, debit off-chain, crypto or card) is cheaper per call.

Free (always)

Flagship: fetch_extract (URL → clean text, median 98.1% fewer tokens than raw HTML) and fetch_html (URL → clean structured HTML). Plus a wide utility catalog:

Call tool_catalog() for the complete, current list with schemas and prices.

---

Payment (x402)

When an agent calls a paid tool (e.g. screenshot_url) without payment, the server returns a tool result in the x402 v2 MCP transport shape: isError: true, the payment requirements in structuredContent, and the same object JSON-encoded in content[0].text (a second text block carries the next steps):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "x402Version": 2,
      "error": "Payment required to use this tool",
      "resource": { "url": "https://mcp.toolsnap.app/mcp#screenshot_url", "serviceName": "ToolSnap" },
      "accepts": [{
        "scheme": "exact",
        "network": "eip155:8453",
        "amount": "40000",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0x…",
        "maxTimeoutSeconds": 300
      }],
      "extensions": { "bazaar": { "info": { "input": { "type": "mcp" } } } }
    },
    "content": [{ "type": "text", "text": "<the same JSON>" }, { "type": "text", "text": "Payment required: …" }]
  }
}

Until 2026-10 this was a JSON-RPC error (error.code: 402, error.data). If you downloaded scripts/pay-proxy.mjs before then, download it again: older copies only recognise the old shape and will not pay on their own. (The prepaid-deposit challenge, account_deposit, still answers with the JSON-RPC 402 error.)

An x402-enabled client reads accepts[0], signs an EIP-3009 TransferWithAuthorization, and retries with _meta["x402/payment"] set. See x402 spec.

---

Run locally

npm install
cp .dev.vars.example .dev.vars  # fill in wallet secrets
npm run dev
# Worker at http://localhost:8787

Type-check

npm run typecheck

Deploy

npm run deploy

Production deploys come from .github/workflows/deploy.yml (push to main).

Alerta de despliegues inesperados

Vigila que nadie publique toolsnap-mcp ni toolsnap-portal fuera del workflow (acción A14 del plan de seguridad). Corre en el cron de 5 minutos que ya existe (src/alerts/deploy-watch.ts): lee los últimos deployments de cada Worker por la API de Cloudflare con un token de solo lectura y, si hay uno nuevo que no está registrado como esperado, avisa por Telegram (el canal de las demás alertas) con Worker, deployment, versión, fecha, author_email, origen y mensaje. La primera pasada sin estado solo guarda el último deployment. Un rollback avisa siempre, esté o no registrado.

Lo esperado vive en el KV X402_NONCES: esperado:{worker}:dep:{deploymentId} (caduca a los 90 días) y ultimo-visto:{worker}. Se registra el deployment y no la versión a propósito: un wrangler rollback crea un deployment nuevo con una versión ya conocida. El workflow registra el suyo tras wrangler deploy. Cualquier otra cosa avisa, también un wrangler secret put (crea una versión nueva): si lo has hecho tú, regístralo. Si el aviso no consigue salir por Telegram se reintenta cada pasada y, pasada 1 hora, el cron falla y lo ve /analytics (tarea deploy-watch).

Deploy manual desde el Mac (o tras un wrangler secret put):

CLOUDFLARE_API_TOKEN=... scripts/registrar-deploy.sh toolsnap-mcp

Hazlo en los tres minutos siguientes al deploy: es el margen de cortesía antes de que la alerta salga. toolsnap-portal se despliega desde otro repositorio: su workflow tiene que llamar a este mismo script con toolsnap-portal.

Qué hay que poner (una sola vez):

npx wrangler secret put VIGIA_CF_TOKEN
# TELEGRAM_BOT_TOKEN y TELEGRAM_CHAT_ID ya existen (alertas de error); no hay que tocarlos.

• VIGIA_CF_TOKEN: token de solo lectura en la cuenta ToolSnap con el permiso Workers Metadata Read-Only (la documentación de la API lo acepta para GET .../deployments; no es el de «Workers Scripts Read», que además permite descargar el código de todos los Workers). Sin el secret, la vigilancia no hace nada.
• El token CLOUDFLARE_API_TOKEN del environment production de GitHub necesita además Workers KV Storage: Edit (cuenta ToolSnap) para el paso «Register deployment as expected» (y para scripts/registrar-deploy.sh); sin él, cada deploy dará una alerta. Pon el secret y el permiso antes de fusionar.
• VIGIA_WORKERS incluye también toolsnap-x-personal (Worker de los tokens personales de X, A16), cuyo job deploy-x-personal registra su deployment con el token CLOUDFLARE_API_TOKEN_X_PERSONAL. Ese token (Editor solo de ese Worker) necesita además Workers KV Storage: Edit (cuenta ToolSnap) para escribir en X402_NONCES. Dáselo antes de fusionar, como se hizo con el token principal: hasta entonces el paso «Register deployment as expected» de ese job falla sin cortar el deploy (continue-on-error) y cada merge a main hace saltar una alerta de la vigilancia por toolsnap-x-personal. Con el permiso de KV el token puede escribir en el mismo KV que usa el vigilante: es el coste de vigilar ese Worker con la misma lista de esperados.

Límite estructural. El vigilante corre dentro de toolsnap-mcp, que es uno de los vigilados, y el repositorio es público: quien pueda desplegar toolsnap-mcp puede quitar la llamada, escribir ultimo-visto y esperado:* en el KV y leer VIGIA_CF_TOKEN. Cubre un deploy descuidado del socio y cualquier deploy de toolsnap-portal; no cubre a un adversario con permiso de deploy sobre toolsnap-mcp. Para eso haría falta vigilar desde fuera (un schedule de GitHub Actions o un Worker aparte con su propio KV y token).

---

Stack

• Runtime: Cloudflare Workers (edge, 0 ms cold start)
• Protocol: MCP streamable-http (JSON-RPC 2.0)
• Payment: x402 v2 · EIP-3009 on Base mainnet · USDC
• Verification: off-chain EIP-712 signature recovery (viem)
• Settlement: on-chain transferWithAuthorization via relayer wallet
• Anti-replay: Cloudflare KV nonce store (7-day TTL)
• First-call-free: mechanism exists in code (KV key first_free:{address}) for future flat-rate tools; all current paid tools have real COGS and are excluded, so every call settles

---

Contributing

PRs welcome for new free tools in src/tools/. Follow the pattern in src/tools/text-stats.ts and add the tool to src/tools/index.ts.

For paid tools or changes to the x402 payment logic, open an issue first.

Do not commit wallet private keys, .dev.vars, or any secrets.

---

---

License

MIT