Sign and register statements on a Forestrie log

@forestrie/mcp-register

An MCP server that signs a statement and registers it on a Forestrie transparency log under a Forestrie-Grant, then waits for the seal and verifies the receipt. It can also buy the grant: as the requester, it signs a child grant under your own authority log and registers it with canopy, paying canopy's x402 charge within hard caps. It is the write path of the Forestrie MCP trio:

• @forestrie/mcp-verify verifies receipts offline.
• @forestrie/mcp-resolve fetches receipts and the material to verify them.
• This package writes. It uses the other two as libraries.

The statement is signed with a log key the server holds. The default backend for that key is an ES256 key file the server creates. Child grants are signed with a separate authority key, held the same way. The model never handles signature bytes: you pass the payload and the server signs it. No tool takes a signature or a key as input.

Paying is optional, and the payer is yours. The server never creates a payer key and holds no funds of its own: you choose how payment happens (see Choosing a payer). Whichever you choose, a payer key never crosses the MCP boundary, and the spending caps are configuration, not tool arguments. With no payer configured, the server spends nothing: it returns canopy's payment requirements, and you pay from your own x402 wallet (relay mode).

Status

Version 0.1.1 on npm, published with provenance from publish.yml. 0.1.0 was published by hand and has no provenance attestation; use 0.1.1 or later.

Tools

The prompts walk an agent through the work:

• register covers the key and the grant, sealing, registering, waiting, verifying and keeping the receipt.
• audit explains which trust questions a receipt answers under which trust root.
• issue-and-pay covers buying a grant as the requester: sizing it, issuing it, paying within the caps or relaying the payment, and handing the completed grant to the performer.

Configuration

Every value can be overridden per call.

Choosing a payer

Whoever wants the work done pays for it: the requester, paying canopy directly. The server supports three ways to do that and prefers none of them.

A backend of your own must sign an EIP-3009 authorisation with the nonce it is given. That nonce is what stops one grant being paid for twice (see Payment settings).

Example: a dedicated key file

This is one way to set up the key-file payer, not the way. Any EVM account works; what matters is that it pays for this and nothing else.

1. Create a private key in a file only you can read. Any wallet tool that exports a raw private key will do. With no extra tools:

    ( umask 077; printf '0x%s\n' "$(openssl rand -hex 32)" > payer.key )

   The server accepts one line, 0x and 64 hex digits, in a regular file (not a symlink) that no other user can read.

2. Find the account's address with a tool you already trust to derive one from a private key, or by importing the key into a wallet you use.
3. Fund the address with the asset canopy charges in. On the default network, Base Sepolia, that is testnet USDC, from Circle's faucet. The account needs no ETH: it only signs an authorisation, and the x402 facilitator submits the transfer and pays its gas.
4. Point the server at the file and set the caps:

    MCP_REGISTER_PAYER_KEY_FILE=/path/to/payer.key
    MCP_REGISTER_PAY_MAX_PER_CALL=100000   # $0.10
    MCP_REGISTER_PAY_MAX_PER_DAY=1000000   # $1.00

Keep one account per requester. Payments settle on chain, so anyone can link a payer address to the grants it paid for. To rotate the key, create a new one, move what is left to it, and point MCP_REGISTER_PAYER_KEY_FILE at the new file.

Payment settings

These are read from the environment only. No tool argument can set or raise them.

The server pays only the canopy named in FORESTRIE_BASE_URL, and only for the request it made. Every payment it signs for a grant uses a nonce derived from that grant, so the token contract can settle at most one of them: a retry or two overlapping calls never pay for one grant twice. Each signed payment is written to the spend ledger before it is sent and counts toward the daily cap whether or not it settles. The daily cap is approximate when calls overlap. USDC has 6 decimals, so 10000 is $0.01.

Where grants come from

Forestrie runs no grant issuer. Whoever owns the authority log above yours issues your grant, naming the key that get_log_key returns. Canopy sequences grants; it does not issue them.

That owner can be you. If the owner of the root above you creates an authority log for your authority key (get_log_key with which: "authority" returns it as a PEM for forestrie-cli's create-log --auth-log --signer-pem), issue_grant and register_grant let you issue and register your own child grants. If that authority log carries the child-payment-required flag, each registration is paid for over x402, straight to the transparency operator.

Install

npx -y @forestrie/mcp-register

Layers

• src/core is browser-safe and works on bytes only.
• src/net is the only place fetch is called, always through an injected fetchImpl.
• src/node holds the MCP SDK, stdio, the filesystem, the key files and the payer.

See AGENTS.md.

Licence

MIT.