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.
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:
{
"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:
{
"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
baseonly when the file's final on-chain terms include a Base payee. For any other file,annon_buystops withroute_unavailablebefore any wallet or payment step; usenear, or1clickwith a human-configured Baseorigin. An EVM agent that names no route getsorigin_requiredfor 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.
targetmust be a secure resource URL within any configured allowlist. Local offer files are refused, and an optionalurlcannot 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.1or[::1](for examplehttp://localhost:8790/file). The same rule applies toannon_verify. - Encoded path separators
%2fand%5care refused in every case. originnames an entry in the human configurationoriginsor inANNON_ORIGINS. ItsfromChain,fromAssetand optionalrefundTocannot 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
annon_buycreates the purchase. For 1Click it returns deposit instructions; someone funds the deposit from their own wallet before the cutoff. Annon never sends it.- After
submitted, callannon_statusabout every 30 seconds untilaccepted. Apendingstate and asettlement_pendingerror mean wait, never failure. Resumable pending results andsettlement_pendingerrors carryretryAfterSeconds(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. - Open with
annon_openonce the status isaccepted.
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.