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`](https://github.com/forestrie/mcp-verify) verifies
  receipts offline.
- [`@forestrie/mcp-resolve`](https://github.com/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](#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](#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](https://faucet.circle.com). 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