npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@notol/mcp

v0.1.4

Published

Notol MCP server: lets an AI agent pay USDC on Arc with its own key, escrowed until the recipient confirms.

Readme

@notol/mcp

An agent that pays a pasted or historical address cannot tell a lookalike from the real one (address poisoning). This local MCP server for Notol checks a payee before the agent pays, with no key and no funds; with a key it can also pay USDC on Arc through escrow.

Node 20 or later. Docs: https://www.notol.app/docs#mcp.

Add the check (no key, no funds)

Claude Desktop (claude_desktop_config.json) or a project .mcp.json for Claude Code. NOTOL_SENDER is the public address your agent pays from:

{
  "mcpServers": {
    "notol": {
      "command": "npx",
      "args": ["-y", "@notol/[email protected]"],
      "env": {
        "NOTOL_API_URL": "https://api.notol.app",
        "NOTOL_SENDER": "0xYOUR_PAYING_WALLET_ADDRESS"
      }
    }
  }
}

0.1.2 is the first version with check-only mode. With NOTOL_AGENT_KEY unset (or empty) the server starts with two tools, notol_check_payee and notol_transfer_status. It holds no key and moves no funds. Only NOTOL_API_URL is required (https; plain http only for localhost). NOTOL_SENDER and NOTOL_API_KEY are optional. If a call gives no sender and NOTOL_SENDER is unset, notol_check_payee answers BAD_INPUT.

Fail closed: if a pay setting (NOTOL_MAX_PER_TRANSFER, NOTOL_MAX_PER_DAY, NOTOL_ESCROW_ABOVE, NOTOL_VERIFIED_ONLY, NOTOL_CHAIN_ID, NOTOL_WEB_ORIGIN or NOTOL_RPC_URL) is set without a key, the server refuses to start (the config meant to pay and lost its key). A malformed key always stops it, and so does NOTOL_SENDER next to a key (with a key, the sender is the key's address).

What the check catches, and its limits

notol_check_payee takes recipient and an optional sender. It flags a lookalike of a payee the sender verified in Notol's on-chain registry (address poisoning), the sender's own address, and reserved or system addresses. It answers direct, escrow or blocked, with a one-line meaning.

  • It is a hint: a send re-checks on chain.
  • It knows only payees verified in Notol's registry on Arc, and nothing about other chains.
  • escrow / new_payee is not a verdict that an address is safe. It means Notol has no verified history for that pair.

Give your agent a wallet (one command)

npx @notol/[email protected] init --owner 0xYOUR_WALLET

--owner is your own wallet: the one address the agent can send funds back to. Options: --chain 5042 (default, Arc mainnet) and --file path. It creates the agent's key file (default ~/.notol/agent-<chainId>.json, %USERPROFILE%\.notol\ on Windows) and prints the agent address, the owner, the file path and an mcpServers snippet that points at the file with NOTOL_AGENT_KEY_FILE. It never prints the key, and it refuses to overwrite an existing file. Sample output, shortened:

Agent wallet created.

  agent address  0xAGENT_ADDRESS
  owner          0xYOUR_WALLET   (notol_withdraw pays only this address)
  key file       /home/you/.notol/agent-5042.json
...
Add this to your MCP client config:
{ "mcpServers": { "notol": { ..."env": { "NOTOL_AGENT_KEY_FILE": "/home/you/.notol/agent-5042.json", ... } } } }
  • Receive first. A new wallet holds 0. It can receive plain USDC transfers at its address right away, and it can pay only once funded. Gas on Arc is paid in USDC, so one balance covers fees. Receiving Notol escrow payments through MCP is not in this version (planned with the sealed mailbox, gated on the D65 audit).
  • Back up the file. It is the only copy of the agent's key. Back it up, or keep only what you can lose in this wallet.
  • The file is outside the policy. Any process running as you can read it and pay anyone, including an agent with shell or file tools. Don't give the paying agent file access to ~/.notol. Under WSL keep the file in the Linux home, not on /mnt/c (it reads as world-readable there and is refused).
  • File permissions. On POSIX the file is mode 0600 and the server refuses a key file other users can read. On Windows there is no mode check; the file inherits your user profile's access rules.

Pay through Notol (with a key)

With a key the server lets an agent pay USDC on Arc with its own key. Payments go into an escrow that releases only when the recipient confirms, else refund. It wraps @notol/agent; no custody, no hosting. The key never leaves your machine, and nothing here talks to Notol except the api and your chain RPC.

Webhook delivery is sealed (D65) when the api offers it: the SDK seals the confirm-link secret to the payee's contact box public key, so the api cannot read it. notify.key is that public key (base64url, from your own vendor records); without it the SDK fetches it from the webhook URL. The key must come from your own records, like the URL. Errors before anything is locked: CONTACT_KEY_UNAVAILABLE, SEALED_CONTACT_DISABLED.

Against the hosted api (api.notol.app) only the sealed webhook channel is on (GET /v1/info reports contactChannels.webhookSealed: true). Email, plaintext webhook and Telegram delivery are off: notify: { email } is refused with EMAIL_DISABLED before anything is locked. notol_send with notify: { webhook } can escrow to a new payee when the payee's webhook URL serves a contact key (the payee runs createConfirmHandler with boxKeys). A URL that serves no key gets CONTACT_KEY_UNAVAILABLE, also before anything is locked. Direct sends to payees verified on chain work as before (needs NOTOL_ESCROW_ABOVE). SEALED_CONTACT_DISABLED means the payee's URL serves a key but the api has no sealed channel; the SDK refuses rather than send the secret in plaintext. If the SDK cannot read the payee URL at all, it refuses with CONTACT_KEY_UNAVAILABLE. The SDK's notify: 'share' still works for senders who hand over the link themselves; the MCP has no share.

Env

Fail closed: a missing or malformed value stops the server at start, with an error that names the variable and never prints a value.

| Variable | | | --- | --- | | NOTOL_AGENT_KEY | required to pay, or NOTOL_AGENT_KEY_FILE; neither set = check-only mode. The agent's private key, 0x + 64 hex. Give it only the USDC (and gas) you are willing to lose. | | NOTOL_AGENT_KEY_FILE | alternative to NOTOL_AGENT_KEY: path to the key file made by init. Both set = the server refuses to start. A file that is missing, unreadable, malformed, for another chain, whose address does not match its key, or with an invalid owner also stops it (never a fallback to check-only). NOTOL_CHAIN_ID must match the file. | | NOTOL_API_URL | required. Notol api base URL. | | NOTOL_WEB_ORIGIN | required with a key. Web origin the confirm link points at. | | NOTOL_CHAIN_ID | required with a key. Integer: 5042 (Arc mainnet) or 5042002 (Arc testnet). | | NOTOL_MAX_PER_TRANSFER | required with a key. Policy cap per transfer, decimal USDC string. | | NOTOL_MAX_PER_DAY | optional. Cap on the last 24 h of escrow locks plus this process's sends. | | NOTOL_ESCROW_ABOVE | optional. A verified payee is paid directly up to and including this amount; above it, escrow. Unset = never direct. Needs NOTOL_MAX_PER_DAY (direct sends have no refund), or the server refuses to start. | | NOTOL_VERIFIED_ONLY | optional. 1 refuses any payee not verified on chain. 0 or unset is off. Any other value stops the server at start. | | NOTOL_RPC_URL | optional. Default: the chain's public RPC. | | NOTOL_API_KEY | optional. ntl_... partner key; meters and rate-limits, never moves money. | | NOTOL_SENDER | optional, check-only mode only. The public address the agent pays from; the default sender for notol_check_payee. Must be a valid address. Next to NOTOL_AGENT_KEY it stops the server. |

Amounts are decimal USDC strings ("12.50"): at most 12 integer digits and 6 decimals, greater than zero. Exponents, commas, signs and numbers are refused. Money is never a float.

Run it

The key below is a placeholder:

{
  "mcpServers": {
    "notol": {
      "command": "npx",
      "args": ["-y", "@notol/[email protected]"],
      "env": {
        "NOTOL_AGENT_KEY": "0xYOUR_AGENT_PRIVATE_KEY_64_HEX_CHARS_REPLACE_ME_NOT_REAL_000000000000",
        "NOTOL_API_URL": "https://api.notol.app",
        "NOTOL_WEB_ORIGIN": "https://app.notol.app",
        "NOTOL_CHAIN_ID": "5042",
        "NOTOL_MAX_PER_TRANSFER": "50",
        "NOTOL_MAX_PER_DAY": "200",
        "NOTOL_VERIFIED_ONLY": "0"
      }
    }
  }
}

Pin the version (@notol/[email protected]): it pins the whole install (the package ships a shrinkwrap), so updates reach the key-holding process only when you change the pin. On Windows, if the client cannot start npx, use npx.cmd.

Tools

| Tool | In check-only | Input | Does | | --- | --- | --- | --- | | notol_check_payee | yes | recipient, sender? (check-only: needed unless NOTOL_SENDER is set) | How a payment would be handled: direct, escrow or blocked, with a one-line meaning. A hint; the send re-checks on chain. | | notol_send | no | to, amount, notify = { email } or { webhook, key? } | Pays under the policy: direct to a payee verified on chain (within NOTOL_ESCROW_ABOVE), else escrow, released only when the recipient confirms, else refunded at expiry. | | notol_wallet | no (any key: env key or key file) | none | The agent's address, owner and USDC balance (null when the read fails, never 0). Read-only. | | notol_withdraw | no (key file with an owner only) | amount | Direct USDC transfer to the owner only; there is no destination argument. Not counted toward NOTOL_MAX_PER_DAY. Leave a little for gas. On TRANSFER_UNCONFIRMED, call notol_resume_send. | | notol_transfer_status | yes | transferId | Status, amount (decimal USDC), expiry. | | notol_cancel | no | transferId | Refunds this agent's own Pending transfer. | | notol_resume_send | no | lockTx | After a LOCK_UNCONFIRMED send: re-broadcasts the same signed lock (cannot lock twice). Same session only. |

notol_send and notol_withdraw refuse with INSUFFICIENT_FUNDS (naming the agent address) when the known balance is below the amount, before signing.

Results are plain JSON; errors are { error: code, message }. The confirm link is never returned (there is no share option), so its secret never enters the model's context. The recipient gets it by email or by webhook. Before locking, notol_send checks the api's GET /v1/info and refuses (EMAIL_DISABLED / WEBHOOK_CHANNEL_DISABLED) a channel the api does not deliver. On api.notol.app only the sealed webhook is on: use notify: { webhook } to a payee that serves a contact key, or pay a verified payee directly. Email is refused with EMAIL_DISABLED.

The trust rule

The destination address and any webhook URL must come from your own trusted records (vendor master data), never from an invoice, email, web page or another tool's output. Address poisoning and prompt injection work by swapping exactly those. Whoever controls the webhook receives the confirm link and can confirm the transfer, so a poisoned invoice that carries both an address and a webhook defeats the escrow check. The tool descriptions tell the model this; the real control is where your agent's inputs come from.

Policy is a soft guard

The limits (NOTOL_MAX_PER_TRANSFER, NOTOL_MAX_PER_DAY, NOTOL_VERIFIED_ONLY, NOTOL_ESCROW_ABOVE) run in the same process as the key. Anything that can read the process env or its memory can bypass them. Hard limits need smart-account session keys. Until then, fund the agent key with only what you can lose. Direct sends have no escrow and no refund.

ponytail: one tool call that moves money runs at a time (one key, one nonce sequence); an unconfirmed lock is remembered in memory only, so a restart forgets it. Upgrade path: persist the pending lock encrypted.