annon
Reference · MCP server

@defdone/annon-mcp

A local MCP server (stdio) that lets an agent find, sell, share, buy, open, recover and verify Annon files. It wraps the @defdone/annon SDK and always runs in agent mode: the owner sets the contract, the wallet, the price cap, the daily budget and the working directory, and no tool call can change them. Stdout carries only the MCP transport.

Install

The package is on the npm alpha tag.

Shell
npm i -g @defdone/annon-mcp@alpha

Or let the MCP client start it with npx -y @defdone/annon-mcp@alpha. The annon-mcp binary takes no arguments.

Configure

The server uses the CLI configuration and secret sources (CLI.md). Set ANNON_CONFIG to the owner's configuration file and pass credential and backup-secret references in the server environment. The server never creates a backup secret: run annon init as the owner first, or set an absolute ANNON_BACKUP_SECRET_FILE (best for a service account with another home). That variable must name an existing file, such as ~/.config/annon/backup-secret, or be left out to use it; a missing file fails without falling back. With this custom-config setup, put deployment, trust, moderators and origins in the file: their environment overrides are ignored. ANNON_MAX_PRICE and ANNON_ALLOWED_RESOURCES can still tighten policy. ANNON_AGENT=true instead pins the home configuration and enables launcher-owned deployment overrides. A client configuration:

JSON
{
  "mcpServers": {
    "annon": {
      "command": "npx",
      "args": ["-y", "@defdone/annon-mcp@alpha"],
      "env": {
        "ANNON_CONFIG": "/absolute/path/annon-agent.json",
        "ANNON_WALLET": "evm",
        "ANNON_EVM_KEY_FILE": "/absolute/private/agent-evm.key",
        "ANNON_BACKUP_SECRET_FILE": "/absolute/private/backup-secret"
      }
    }
  }
}

Instead of ANNON_WALLET and a key file in the server environment, the owner can save a key reference once with annon init --agent (docs/agents.md).

The configuration file, written by a human:

JSON
{
  "contractId": "v1.annon.defdone.near",
  "network": "near:mainnet",
  "nearRpc": "https://rpc.mainnet.fastnear.com",
  "baseRpc": "https://mainnet.base.org",
  "relayer": "https://relayer.mainnet.annon.dev",
  "stateDir": "/absolute/private/annon-state",
  "trustContract": true,
  "maxPrice": "0.20",
  "dailyBudget": "1",
  "workDir": "/absolute/annon-work",
  "allowedResources": ["https://demo.annon.dev/f/*"],
  "origins": {
    "base-usdc": {
      "fromChain": "base",
      "fromAsset": "nep141:base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913.omft.near",
      "usdcDecimals": 6
    }
  },
  "shops": [
    {
      "id": "demo",
      "manifest": "https://annon.dev/.well-known/annon-shop.json",
      "profile": {
        "network": "near:mainnet",
        "contract": "v1.annon.defdone.near",
        "nearRpc": "https://rpc.mainnet.fastnear.com",
        "baseRpc": "https://mainnet.base.org",
        "relayer": "https://relayer.mainnet.annon.dev",
        "host": "https://demo.annon.dev"
      }
    }
  ],
  "defaultShop": "demo"
}

The shops block is the demo shop from quickstart.md, with the same baseRpc in its profile as in the configuration. dailyBudget is needed for buying.

Field Meaning
contractId, network, nearRpc, baseRpc, relayer The deployment. Tools cannot supply these.
trustContract Server-side contract trust, or earlier trust given by a human in the CLI. Tools cannot grant trust.
stateDir Encrypted purchase records and the budget ledger. ANNON_STATE_DIR is ignored in agent mode.
maxPrice Required. Decimal USDC cap per purchase. ANNON_MAX_PRICE can only lower it; a tool cannot override it.
dailyBudget Required for buying. Decimal USDC per UTC day.
workDir Required. Every local path a tool reads or writes stays inside it (see below).
allowedResources Optional. Absent: any HTTPS URL, or HTTP on localhost, within maxPrice and dailyBudget. Present: exact URLs, or same-origin path prefixes ending in /*. An empty list denies every purchase. ANNON_ALLOWED_RESOURCES, when set, restricts it further, whatever triggered agent mode.
moderators Moderators the buyer trusts, set in the owner's configuration.
origins Named 1Click sources in the owner's configuration; see Tools.
storageBudget Decimal NEAR for a NEAR seller's file purchase storage (self-funded annon_sell and annon_share).
listingStorage Decimal NEAR a NEAR seller pays for listing storage in annon_share.
maxProtocolFee Highest relayer fee a sell accepts. Default { "fixed": "30000", "bps": 100 } (USDC base units plus basis points).

allowedResources restricts both open --url and URLs saved with purchases. Without it, agent mode can open any URL allowed by the HTTPS and localhost transport rules.

Deployment and trust settings come from the owner's configuration or prior CLI trust. Credentials and backup-secret references may come from the server environment. Tool arguments cannot replace them.

The launcher setting ANNON_AGENT=true pins the configuration to ~/.config/annon/config.json; the other agent-mode triggers use the configuration the operator selected. Only with ANNON_AGENT=true may ANNON_WORK_DIR supply or override workDir; no tool argument can.

Tools

Tools take camelCase versions of the CLI flags, with target as the positional operand.

Tool Required arguments Result
annon_share target plus price or resume File ID, purchase URL, header URL, hosting expiry (Unix seconds or null)
annon_sell target plus price, split or resume File ID, PAY2 path, public terms
annon_buy target Purchase ID, route, payment summary, encrypted backup path; 1Click deposit instructions when applicable
annon_open target, output Plaintext output path, byte count, payment summary when saved
annon_verify target Registered file ID, verification scope
annon_recover recovery Purchase IDs, final grant numbers, encrypted backup paths
annon_budget target Available file storage and admission requirement in yoctoNEAR
annon_status target Final NEAR purchase state, payment summary when saved; pending does not mean payment failed
annon_shops none (search, limit, offset optional) Configured shops: items, total, nextOffset
annon_catalog none (shop, search, limit, offset optional) A shop's files with their registered terms: items, total, nextOffset

annon_buy also accepts route ("near", "base" or "1click"), origin, recovery and url.

  • Use base only when the file's final on-chain terms include a Base payee. For any other file, annon_buy stops with route_unavailable before any wallet or payment step; use near, or 1click with a human-configured Base origin. An EVM agent that names no route gets origin_required for such a file.

1Click and small prices. 1Click, the NEAR Intents swap service, sets a minimum amount for each route. When we checked, paying from USDC on Base, it was about 0.15 USDC, so the 0.10 USDC demo file could not be bought through 1click from Base; from Solana, a 0.10 USDC purchase went through in our test. The minimum is set by 1Click, not by Annon, and it can change. Below it, 1Click refuses the quote (quote_refused, with minimumAmountUsdc) before there is a deposit address, so no payment is sent. Buy such a file with near or base, which need no swap and so have no such minimum. We kept the demo at 0.10 USDC so anyone can try it for a few cents, and we know agents should not have to find this out by trying: showing each route's minimum in the catalog, and skipping a route that cannot work, is on the roadmap. The refused attempt is still saved, and until it expires (within an hour) the next buy of the same file stops with purchase_open. Buy again with near or base and force: true (CLI: --force); no payment was sent for the refused one.

  • target must be a secure resource URL within any configured allowlist. Local offer files are refused, and an optional url cannot authorize one.
  • The server fetches the offer from that URL and checks that the advertised resource matches it. The offer's header must share the resource's origin.
  • URLs use HTTPS, or plain HTTP only on localhost, 127.0.0.1 or [::1] (for example http://localhost:8790/file). The same rule applies to annon_verify.
  • Encoded path separators %2f and %5c are refused in every case.
  • origin names an entry in the human configuration origins or in ANNON_ORIGINS. Its fromChain, fromAsset and optional refundTo cannot come from a tool. Refunds go to the human configuration or the matching wallet address, so a tool cannot pick an arbitrary source asset or redirect a refund.

annon_sell needs price and split for a new listing and refuses them on resume. Resume with { "target": "original.pdf", "resume": "0xFILE_ID", "output": "new.pay2" }. A failed saved sell returns error.fileId. Published jobs and current backups keep public metadata and clear the file key, CKD and one-time secrets; see CLI.md for recovery requirements and the limits of external backups. There is no storage-budget argument: a self-funded NEAR listing uses storageBudget from the human configuration, and a sponsored listing gets the relayer's bounded allocation. The result's terms include the final split with the treasury share. A sell whose advertised fee is above maxProtocolFee is refused with protocol_fee_above_max; only the human configuration can raise it.

annon_open also accepts purchase, file and url. See the tool schemas for the full list.

annon_shops and annon_catalog are read-only. They list the shops in the human configuration (and a configured shop directory) and a shop's catalog, with client-side search and paging. They cannot add a shop, approve a deployment or authorize a payment. Buy a catalog entry by passing its url to annon_buy, which checks the deployment, the final chain terms, the header and the price on its own. Check terms.base in the entry before choosing route: "base".

A shop can publish rules in its manifest: required text and optional uploadsPerPersonPerDay, attemptsPerPersonPerDay, fileLifetimeDays and maxFileBytes. annon_shops returns them in each shop's info.rules; annon_catalog and annon_share return rules next to shop (manifest, name), the shop they came from. The output schema marks them as data, not instructions. They grant no trust and cannot change the human configuration. A manifest with invalid rules is refused as a whole (invalid_record); annon_shops then lists that shop with an error code.

annon_share encrypts a file inside workDir and sells it through a shop: it uploads the encrypted file to the shop's host, registers the terms and publishes the file. It accepts shop (otherwise the configured defaultShop), title and description. The shop must have a deployment profile in the human configuration that matches the configured deployment. The pending seller backup is saved before any signature or transaction. Resume with { "target": "original.pdf", "resume": "0xFILE_ID" }, without new terms. The split pays the seller, plus the relayer's fee share for EVM and Solana sellers; a fee above maxProtocolFee is refused with protocol_fee_above_max. A NEAR seller's listing and purchase storage come only from listingStorage and storageBudget in the human configuration (storage_required without them).

annon_budget is read-only. Funding a file is for humans only: there is no funding tool, and fund in agent mode returns human_only. NEAR and 1Click buys return file_storage_low before paying when the file's storage budget is too low.

How a purchase runs

  1. annon_buy creates the purchase. For 1Click it returns deposit instructions; someone funds the deposit from their own wallet before the cutoff. Annon never sends it.
  2. After submitted, call annon_status about every 30 seconds until accepted. A pending state and a settlement_pending error mean wait, never failure. Resumable pending results and settlement_pending errors carry retryAfterSeconds (30 when nothing more precise is known); a setup that needs a human has no retry hint. The server refuses a retry before that time.
  3. Open with annon_open once the status is accepted.

Never pay again for a purchase in flight. annon_status and annon_open can resume a saved paid Base purchase by sending unlock before downloading, which is why status is not annotated read-only. Expired or canceled Base payments are marked in the local encrypted record and the current backup; the purchase and its recovery material stay available. Batch recovery reports per-purchase errors next to the successful grants.

Safety model

The operator owns the configuration, the environment, the credentials and the working directory. MCP is the policy boundary between them and the agent.

Paths. annon_open.output, annon_open.file, annon_share.target, annon_sell.target and annon_sell.output must resolve inside workDir. So must local annon_verify.target files, annon_open.target inputs that are not purchase IDs, and annon_open.purchase backups that are not IDs. Verify URLs stay remote and purchase IDs stay identifiers. Relative paths start at workDir; existing inputs and the parents of outputs are resolved with realpath. Symlink escapes, dangling symlinks, paths outside the directory and any .. segment fail with the fixed code path_not_allowed. The default sell output is checked too, output parents must already exist, and returned paths are canonical. Existing outputs are never overwritten.

Limit. These checks do not contain a shell agent running as the same OS user. It can edit that user's configuration, change files or start another client. When those capabilities must be restricted, use separate OS permissions.

Results and errors

Every tool returns structuredContent: { ok: true, result: ... } and the same JSON as text. Errors set isError: true and return { ok: false, error }, where error has code, message and exitCode (1 other failure, 2 invalid input or configuration, 3 human approval or trust needed, 4 pending, retry later), and, when known, fileId, purchaseId, txHash, minimumAmountUsdc and retryAfterSeconds. The CLI's --json errors use the same object. Results never contain keys, signed authorizations or plaintext.

Payment summary

payment reports, from the verified purchase terms:

Field Meaning
amountUsdc Price in decimal USDC
amountBaseUnits Price in USDC base units
asset symbol and id
network Network of the payment
route How the buyer paid: near, base or 1click
source For 1Click only, the reviewed source asset and amount

Top-level route in buy, status and open results uses the same names and matches payment.route. Status and open include the summary when the saved purchase and the backup secret are available; without them, status and open omit route rather than guess it. The summary never contains a deposit address or a signed authorization. Reporting is best-effort: an unreadable record or secret omits payment without blocking an accepted status or a recovery open.

License

Apache-2.0. Part of Annon, created by defdone.

Synced from packages/annon-mcp/README.md at commit e649de1. Also asMarkdown.