@stipend-mcp/cli
v1.0.0
Published
Stipend CLI — `stipend-mcp dev` boots the full local stack; `stipend-mcp keygen` generates Ed25519 signing keys; `stipend-mcp repair` runs the one-off data repairs for an upgrade from 0.1.0-alpha.2.
Maintainers
Readme
@stipend-mcp/cli
Command-line interface for Stipend. Ships three commands:
stipend-mcp dev— boot the full local stack (proxy + API + mock Stripe + dev resolver) in one command.stipend-mcp keygen— generate an Ed25519 receipt-signing keypair.stipend-mcp repair— the two one-off Firestore data repairs for an upgrade from0.1.0-alpha.2.
The dev command is Stipend's hero "see it work in under 60 seconds" path. Not for production — it uses a mock payment provider and a permissive identity resolver.
Install
pnpm add -g @stipend-mcp/cli
# or run without installing:
pnpm dlx @stipend-mcp/cli dev --upstream npx @upstream/serverThe bin is stipend-mcp.
stipend-mcp dev
stipend-mcp dev --upstream <command...>Boots:
- An in-memory EntitlementStore + DeliveryStore (or Firestore on the local emulator with
--emulator, which needsFIRESTORE_EMULATOR_HOST). - A fresh Ed25519 signer keypair per boot (receipts are always signed; the API refuses to boot without a signer).
- A MockStripeProvider that auto-approves every intent.
- A DevAgentTokenResolver that accepts any non-empty bearer token and lazily upserts an account for it.
- An MCP proxy on
--proxy-port(default7071), reachable athttp://127.0.0.1:7071/mcp. - The Stipend HTTP API on
--api-port(default7070), reachable athttp://127.0.0.1:7070/v1/..., with one all-scopes host key,dev-api-key.
The upstream's tools are exposed as upstream.<toolname> (e.g. upstream.get_secret_message); the namespace upstream is also the service its entitlements are scoped to.
Agents connect to the proxy port; hosts (and the test harness in front of you) talk to the API port.
Options
| Flag | Default | Purpose |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --upstream <cmd...> | required | The upstream MCP server. Spawns a child process and pipes stdio. Everything after --upstream is treated as the command + args (verbatim). |
| --proxy-port <port> | 7071 | Agent-facing port. |
| --api-port <port> | 7070 | Host-facing API port. |
| --emulator | unset | Use FirestoreStore + FirestoreDeliveryStore on the local Firestore emulator instead of the in-memory adapters. Needs FIRESTORE_EMULATOR_HOST: without it the command refuses to start (it never reaches a real project). Auto-detected when FIRESTORE_EMULATOR_HOST is set. |
| --quiet | unset | Suppress info/warn lines; errors still print. |
Example
# Stand up a sample upstream + the proxy:
stipend-mcp dev --upstream npx -y @modelcontextprotocol/server-everything
# In another shell, talk to it:
curl -sS http://127.0.0.1:7071/healthz
# {"status":"ok"}
# Initialize an MCP session against the proxy. The auto-generated dev
# token is printed in the boot banner.
curl -sS http://127.0.0.1:7071/mcp \
-H 'Authorization: Bearer dev-token-1' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc":"2.0",
"id":1,
"method":"initialize",
"params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}
}'The first time a token is seen, the dev resolver lazily upserts an account and the logger emits a registration line. Subsequent requests reuse the same identity.
Pretty-printed output
stipend-mcp dev formats key events on stderr:
AGENT dev-0c4f7aa2e2cc6e49 (account 1952…)
ALLOW dev-0c4f7aa2e2cc6e49 → upstream/upstream.say_hello
402 dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (payment_required: per_call)
ALLOW dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (one_time ent-12345678)
DUP dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (call key already used; not run again)
UNDO dev-0c4f7aa2e2cc6e49 → upstream/upstream.get_secret_message (upstream timeout; charge given back)
PAY+ pmt-abc 1.00 USD
PAY$ pmt-abc 1.00 USD
RCPT pmt-abc (receipt rcp-xyz)
REFND pmt-abcAmounts carry their own currency code (10.00 EUR). Use --quiet to suppress everything except error lines (the boot banner included); a boot failure always prints.
What stipend-mcp dev is NOT
- Not for production. The
MockStripeProviderreturns synthetic IDs and "succeeds" on every charge; no real money moves. TheDevAgentTokenResolveraccepts any token. Replace both withStripeProvider(@stipend-mcp/stripe) andHttpAgentTokenResolver(@stipend-mcp/proxy) when you wire your own deployment. - Not a deployment / production launcher. Use
createApiServer(@stipend-mcp/api) +createProxyServer(@stipend-mcp/proxy) programmatically in your own service. The dev command is single-process glue meant for local iteration. - Not a multi-upstream demo. The CLI spawns a single upstream from the
--upstreamflag and exposes its tools under the namespaceupstream. For production catalogs with multiple upstream MCP services, wirecreateProxyServer({upstreams: {…}})directly — see@stipend-mcp/proxy.
Production path
// your-server.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { configFromEnv, createApiServer } from '@stipend-mcp/api';
import { createProxyServer, HttpAgentTokenResolver } from '@stipend-mcp/proxy';
import { FirestoreStore, FirestoreDeliveryStore } from '@stipend-mcp/store-firestore';
import { StripeProvider } from '@stipend-mcp/stripe';
import { Ed25519Signer, Stipend } from 'stipend-mcp';
// — store + delivery store
const firestore = /* your Firestore client */;
const store = new FirestoreStore({ firestore });
const deliveryStore = new FirestoreDeliveryStore({ firestore });
// — real Stripe + signer
const provider = new StripeProvider({ apiKey: process.env.STRIPE_SECRET_KEY! });
const signer = new Ed25519Signer({
keyId: process.env.STIPEND_SIGNING_KEY_ID!,
privateKey: process.env.STIPEND_SIGNING_PRIVATE_KEY!,
});
const stipend = new Stipend({ store, signer });
// — real resolver
const resolver = new HttpAgentTokenResolver({
url: process.env.STIPEND_RESOLVER_URL!,
sharedSecret: process.env.STIPEND_RESOLVER_SECRET,
});
// — API (a signer is required; host keys are named and scoped)
const api = createApiServer({
store, deliveryStore, provider, signer,
config: configFromEnv(), // STIPEND_API_KEYS, STRIPE_WEBHOOK_SECRET, … — see @stipend-mcp/api
});
await api.start();
// — proxy (wire to your own HTTP transport)
const upstream = new Client({ name: 'prod-upstream', version: '1.0.0' }, {});
await upstream.connect(/* your upstream transport */);
const { server: proxyServer } = createProxyServer({ stipend, upstreams: { main: upstream }, resolver });
await proxyServer.connect(/* your agent-facing transport */);stipend-mcp keygen
stipend-mcp keygen [--key-id <id>] [--out <path>]Prints (or writes to file) an Ed25519 keypair in PEM format. The key id is embedded in every receipt signed with the private key so verification can find the right public key for an older receipt during rotation.
# To stdout (the default):
stipend-mcp keygen --key-id stipend-prod-2026
# # keyId: stipend-prod-2026
# # Set the private key on your deployment, e.g.:
# # export STIPEND_SIGNING_PRIVATE_KEY="$(cat private.pem)"
# # ...
# To a file (mode 600):
stipend-mcp keygen --key-id stipend-prod-2026 --out ./signing.pem
# wrote keypair to ./signing.pem (mode 600)--key-id defaults to stipend-<YYYY-MM-DD>. In the monorepo, pnpm generate-key builds and runs this same command (pnpm generate-key --key-id <id>), so there is one output format.
stipend-mcp repair
Two one-off data repairs for an upgrade from 0.1.0-alpha.2 on Firestore. Run each once dry, then once with --apply, straight after the coordinated deploy (see the CHANGELOG migration section). stipend-mcp is this package's bin, so without installing it name the package with -p (the npm package called stipend-mcp is the core library and has no bin):
npx -p @stipend-mcp/[email protected] stipend-mcp repair payment-index --project <id> [--collection-prefix <p>] [--apply]
npx -p @stipend-mcp/[email protected] stipend-mcp repair periodic-quotas --project <id> [--collection-prefix <p>] [--apply]payment-indexrebuilds the per-account payment idempotency index, so a retry made across the deploy with a pre-deployIdempotency-Keyreturns the original payment instead of charging twice. A slot already pointing at another payment is reported as a conflict and never overwritten; a key alpha.2 accepted but 1.0.0 refuses (e.g. one containing/) is reported as invalid; an index document whosepaymentIdis not a string is reported ininvalid_index_docs, and its slot is never overwritten (fix or delete it by hand).periodic-quotasrevives periodic quotas that alpha.2 leftconsumedat zero:active, 0 remaining, the next reset in the future. Non-periodic quotas stay consumed, and so does a quota coregrantWithdrawalwithholds (its granting payment was fully refunded or disputed, or it remembers a host revoke made while it was consumed): it is listed underskipped_withdrawn({entitlementId, paymentId?, reason}; reasonhost, without a payment for a direct grant, when the host revoked the quota while it was consumed), a correct skip that does not setneeds_attention. Each apply transaction re-reads the payment, so a refund or dispute that lands between the scan and the write still withholds the revive. An entitlement document, or a stranded quota's payment, that does not decode is listed underinvalid({entitlementId, reason}), and a repair whose transaction fails underfailed({entitlementId, error}; nothing written for it, a re-run plans it again); the run goes on and repairs the rest. An active periodic quota stored without a reset boundary (alpha.2 stored none on any quota, so one with calls left at the upgrade has none) is listed underactive_without_reset_at({entitlementId, resetPeriod, grantedAt}), dry run and apply alike, and never written: it needs no repair, as it resets on the schedule from its grant and its first reset stores the boundary; not an error.
Both are dry runs unless --apply, scan the whole set (paged) before the first write, re-check each write in its own transaction (safe next to live traffic), and print one JSON summary that starts with its target: project, collection_prefix, emulator_host. A second run changes nothing (present counts slots another run created first). Exit code 1 means the operator must look: needs_attention (a conflicts, invalid, invalid_index_docs, raced or failed row; a payment missing its account or creation time is invalid, and so is a periodic-quotas row that does not decode), or the target collection is empty (collection_size: 0; pass --allow-empty if the store really is empty). Exit code 2 is a usage error, including a project that does not match the emulator setting: a demo-* project needs FIRESTORE_EMULATOR_HOST, and any other project refuses to run with it set. Credentials: Application Default Credentials, or the emulator when FIRESTORE_EMULATOR_HOST is set.
Programmatic API
The CLI composition is exported for reuse by other dev tooling:
import { startDevStack, MockStripeProvider, DevAgentTokenResolver } from '@stipend-mcp/cli';
// Boot the full stack (without the SIGINT handler the bin installs):
const stack = await startDevStack({
upstream: ['npx', '-y', '@upstream/server'],
});
console.log('proxy:', stack.proxyUrl);
console.log('api: ', stack.apiUrl);
await stack.stop();The dev primitives also have subpath exports so consumers can pull them without the full CLI:
import { MockStripeProvider } from '@stipend-mcp/cli/mock-stripe';
import { DevAgentTokenResolver } from '@stipend-mcp/cli/dev-resolver';Tests
pnpm test packages/cli # from the repo root: this package's unit (src/) and integration (test/) testsCovers:
mock-stripe.test.ts— synthetic-id shape, override hooks, refund.dev-resolver.test.ts— deterministic identity, lazy upsert, first-resolve callback.logger.test.ts— formatting per event type,--quietsemantics.keygen.test.ts— round-trip a sign-then-verify with a generated keypair;--outwrites mode-600.repair.test.ts— argument parsing, dry-run default, JSON summary and exit codes ofstipend-mcp repair.dev.test.ts— end-to-end: boot the dev stack against an in-memory upstream, exercise health / 404 / 405 / unauthorized / tools-list discovery / free tool forwarding / payment_required /stipend/whoamiover real HTTP.
