Skip to main content
Glama

@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:

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.

Related MCP server: x402-receipt-verifier

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.

Available Tools

7 tools
check_registrationCheck a registrationA
Idempotent

One status check for a registration, by its content hash: pending (not yet sequenced; retry after the given seconds), awaiting_seal (sequenced, entry id known, receipt not yet sealed — sealing takes minutes, and never happens until delegate_sealing has run for the log), or sealed (the receipt is saved and its path returned). Any other answer from canopy is reported as a problem with its reason. canopy answers a statement it never received exactly like a pending one, so after ten minutes of pending this says so. Does not sleep; pace the retries yourself.

Inputs: contentHash (required).

delegate_sealingDelegate sealing for your logA

Authorise the operator's sealer to publish checkpoints for your data log, signed with the log key. Without it entries sequence but are never sealed. If the coordinator has not learned the log's public root, this calls canopy's prepare with the same grant first. Run once per log; the delegation lasts until the returned expiresAt. With as: "authority" it does the same for your authority log, signed with the authority key, so the child grants you register there get sealed.

Inputs: as, grant, baseUrl, ttlSeconds, +2 more.

get_log_keyGet the log keyA
Idempotent

Return the public half of one of this server's keys (ES256, 64 bytes x‖y, as hex, base64 and an SPKI PEM) and where it lives, creating it on first use. which: "log" (the default) is the key that owns your data log: a grant issuer names it in the grant's grantData, and a grant naming any other key cannot carry statements this server signs. which: "authority" is the requester's key that owns your authority log and signs the grants issue_grant makes. Never returns private key material.

Inputs: which.

issue_grantIssue a child grant as the requesterA

As the requester, sign a child grant with this server's authority key: a data-log creation grant under your authority log (named by your authority grant, FORESTRIE_AUTHORITY_GRANT), naming the performer's log key (by default this server's own) and sized with maxHeight, the batch ceiling canopy prices it by. Saves the grant under a fresh child log id; nothing is sent. Call register_grant next.

Inputs: maxHeight (required), logId, grantee, parentGrant.

register_grantRegister a child grant, paying if canopy asksA

Register a child grant with canopy (POST /register/{R}/grants, your authority grant as the parent) and follow it to its receipt; call it again with the same logId to resume until it reports complete. If canopy answers 402 and a payer is configured, it pays within the server's hard caps (per call, per UTC day, one network and asset, testnet only by default) and reports any cap that refuses. With no payer it returns the payment requirements: pay them from your own x402 wallet and call again with payment set to the X-PAYMENT value. Every payment for a grant carries a nonce derived from that grant, so retries and overlapping calls can never pay for it twice. When complete it returns the completed grant for delegate_sealing and register_statement.

Inputs: grant, logId, baseUrl, payment, +2 more.

register_statementSign and register a statementA

Sign a payload with the log key and register it under your Forestrie-Grant. Takes the payload bytes (inline base64 or a file path, up to canopy's 4 MiB statement limit) and its content type. The signed statement is saved before it is sent, so the returned content hash always names it, even if the request fails. A payload path may not point at the log key or inside this server's home. Registration is accepted, not yet sequenced: call check_registration next.

Inputs: payload (required), contentType (required), grant, issuer, +3 more.

verify_registrationVerify a registration's receiptA
Read-onlyIdempotent

Verify a sealed registration's receipt over the statement you registered, with @forestrie/mcp-verify's verifier, and return its four-question answers unaltered. By default the trust root is this server's own log key, the root of your data log; verifying never creates a key. Pass a known accumulator (from @forestrie/mcp-resolve's fetch_accumulator) to use a root that can also answer split-view.

Inputs: contentHash (required), knownAccumulator.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (key retrieval, signing, delegation, grant issuance). However, check_registration and verify_registration both operate on a registration's validity/status, and register_statement vs register_grant both 'register' an object, so a few pairs require careful reading of the descriptions to distinguish.

    Naming Consistency5/5

    All seven tools follow a consistent verb_noun snake_case convention (check_registration, register_statement, issue_grant, register_grant, etc.). No camelCase or stylistic mixing.

    Tool Count5/5

    Seven tools is well-scoped for a registration/grant lifecycle server, with each tool earning its place across key, statement, grant, and sealing operations. No padding or redundancy.

    Completeness4/5

    The core lifecycle (sign/register -> check -> verify, plus grant issue/register and sealing delegation) is well covered with no obvious dead ends. Minor gaps exist: no listing of pending registrations or grants, and no delete/revoke operations.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers