mcp-register

@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

Tool	What it does
get_log_key	Returns the log key's public half (x‖y). Your grant must name this key. The key is created on first use.
delegate_sealing	Authorises the operator's sealer for your data log. Runs canopy's prepare with the same grant first if the coordinator does not know the log's public root yet. Once per log.
register_statement	Signs a payload (inline base64 or a file path, up to 4 MiB, with an explicit content type) and registers it.
check_registration	Does one status check: pending, awaiting_seal or sealed. Once sealed, it saves the receipt.
verify_registration	Verifies the receipt over the statement with mcp-verify's verifier and returns its four answers unaltered.
issue_grant	As the requester, signs a child data-log grant with the authority key, naming a log key (by default this server's), sized with maxHeight. Sends nothing.
register_grant	Registers the child grant with canopy, pays its 402 within the caps or relays the requirements, and follows it to its receipt. Resumable by child log id; never pays twice.

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.

Variable	Meaning
FORESTRIE_BASE_URL	the canopy SCRAPI base URL
FORESTRIE_ROOT_LOG_ID	the forest's root log id (R in /register/{R}/entries)
FORESTRIE_GRANT	your Forestrie-Grant, as base64 or a file path
FORESTRIE_COORDINATOR_URL	the delegation coordinator, for delegate_sealing
FORESTRIE_KNOWN_SEALER_KEY	the registrar's voucher key, base64 x‖y, for delegate_sealing
FORESTRIE_AUTHORITY_GRANT	your authority log's grant, for issue_grant and register_grant
MCP_REGISTER_HOME	key files, grants, registrations and the spend ledger, default ~/.config/forestrie/mcp-register
MCP_REGISTER_KEY_FILE	the log key file, default $MCP_REGISTER_HOME/log-key.jwk
MCP_REGISTER_AUTHORITY_KEY_FILE	the authority key file, default $MCP_REGISTER_HOME/authority-key.jwk

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.

Setup	What you configure	Who holds the key
Relay	nothing	your own x402 wallet: register_grant returns canopy's payment requirements and resumes on a call that carries your X-PAYMENT
Key file	MCP_REGISTER_PAYER_KEY_FILE and the caps below	a file on the machine that runs the server
Your own backend	createServer({ payer }) from @forestrie/mcp-register/server, when you embed the server	whatever your PayerBackend uses: a hosted wallet, a KMS, a remote signer

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.

Variable	Meaning
MCP_REGISTER_PAYER_KEY_FILE	an EVM private key (0x + 64 hex, mode 600) that pays; unset means relay mode
MCP_REGISTER_PAY_MAX_PER_CALL	the most one payment may be, in the asset's atomic units (required with a payer)
MCP_REGISTER_PAY_MAX_PER_DAY	the most all payments in one UTC day may total (required with a payer)
MCP_REGISTER_PAY_NETWORK	the one network it pays on, default eip155:84532 (Base Sepolia)
MCP_REGISTER_PAY_ASSET	the one asset it pays in, default USDC on Base Sepolia
MCP_REGISTER_PAY_TO	optional: the only payee
MCP_REGISTER_PAY_ALLOW_MAINNET	1 to pay on a network that is not a testnet; off by default

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.