@paystage/mcp
PayStage umbrella MCP server: payment preflight, auth watch, HIP-3 trade preflight, and velocity checks.
Not financial advice. The trade preflight tool is a local policy gate only — it does not
place orders or recommend trades.
Published on npm as @paystage/mcp — see the npm page for the current version rather than a number here that can go stale.
What a valid receipt means
paystage-verify returning exit 0 means the key it verified against signed this receipt
and it has not been altered. That is all it means — and which key that was matters:
key_source: "published" → PayStage's published key: the issuer signed it.
key_source: "supplied" (you passed --key or --key-url) → the key you named signed
it, which is a weaker claim and not evidence about PayStage at all. Exit 0 on that path
says nothing more than that the holder of that key produced the receipt.
It does not mean the payment happened — settlement is a separate on-chain event. It does
not mean the verdict was correct — a receipt records a decision, not the soundness of the
policy behind it. And it does not identify the caller; no caller identity is bound into the
payload, by design.
Two narrower points a careful reader should know:
key_source tells you where the verifying key came from: published (PayStage's
endpoint) or supplied (someone passed --key). A receipt verified against a supplied key
proves only that the holder of that key signed it.
- A receipt with
signed: false is still useful: the request and policy digests are
checkable, so "over these inputs" survives even when provenance does not.
--max-age is your policy, not the issuer's. Nothing in the signed payload says how
long a verdict is meant to hold, so a freshness bound is set by the verifier. If "this
verdict is good for 24 hours" ever becomes the issuer's promise it has to be signed, and
that is a format change.
Install
npx -y -p @paystage/mcp paystage-mcp
The server waits silently for an agent app to connect. That's normal; press Ctrl+C to exit. To try the tools without an app, run npx @modelcontextprotocol/inspector npx -y -p @paystage/mcp paystage-mcp.
Or:
npm install @paystage/mcp
The package exposes a stdio MCP server (bin: paystage-mcp).
MCP configuration
{
"mcpServers": {
"paystage": {
"command": "npx",
"args": ["-y", "-p", "@paystage/mcp", "paystage-mcp"],
"env": {
"PAYSTAGE_POLICY_PATH": "./policy.json"
}
}
}
}
Environment variables (all optional):
PAYSTAGE_POLICY_PATH — path to policy.json spending rules
PAYSTAGE_RPC_URL — Base RPC URL override
evaluate_mcp_payment — Available now
Evaluates a proposed x402 payment against a local policy file and returns a verdict before
the agent signs anything.
list_outstanding_auths — Available now
Lists outstanding ERC-20, Permit2, and EIP-3009 authorizations.
evaluate_outstanding_auths — Available now
Flags outstanding authorizations that need attention (e.g. authorized but never settled).
evaluate_hip3_trade — Available now
Evaluates a proposed HIP-3 / trade.xyz order against a local TradePolicy and returns a
decision: allow | review | do_not_trade.
Backed by @paystage/trade-preflight
(published separately), which can also be run standalone:
npx -y @paystage/trade-preflight
The policy is passed as a tool argument; no extra environment variables are required for
this tool.
Packages
| Package | Version | Purpose |
|---|
@paystage/mcp | Umbrella server (5 tools) | |
@paystage/preflight | x402 payment preflight | |
@paystage/auth-watch | Outstanding-auth tools | |
@paystage/trade-preflight | HIP-3 / trade.xyz trade preflight | |
@paystage/velocity | Rate / spend-pattern checks | |
@paystage/policy | Shared policy schema + loader | |
Verify a receipt
Every verdict can carry a signed receipt. paystage-verify checks one without trusting
us — it fetches the published key and verifies the signature over the canonical payload.
npx -y -p @paystage/mcp paystage-verify receipt.json
cat receipt.json | npx -y -p @paystage/mcp paystage-verify -
Exit codes are distinct on purpose:
| Code | Meaning |
|---|
| 0 | signature matches the payload |
| 1 | invalid — altered, or signed by a different key |
| 2 | unsigned — a record of the decision, with no proof of who made it |
| 3 | unverifiable — the key could not be fetched, or an input file could not be read, so nothing can be checked |
| 4 | inputs-mismatch — the receipt is genuine but does not cover the --request/--policy you supplied |
| 5 | stale — the receipt is genuine but older than --max-age allows |
"Invalid" and "could not check" are different facts and must not collapse into one
failure. --key <file> verifies against a local JWK for point-in-time checks.
Supply chain and access
This is the umbrella, so its install tree is wider than any single tool and Socket
flags it accordingly. What it actually contains:
| Flag | Where it comes from |
|---|
| Network access, URL strings | @paystage/auth-watch (Base RPC reads) and @paystage/trade-preflight (one Hyperliquid info query). |
| Filesystem access | @paystage/policy reading your policy file. |
| Environment variable access | PAYSTAGE_POLICY_PATH, PAYSTAGE_RPC_URL. |
| "AI-detected code anomaly" | The official @modelcontextprotocol/server SDK's bundled JSON-schema validator, not PayStage code. |
The umbrella itself is ~16 KB with no network, no filesystem and no eval — the
capability lives in the dependencies, because that is what the tools are for.
Install a narrower surface if you only need part of it: @paystage/preflight and
@paystage/policy make no network calls at all.
Full table: SECURITY.md.
Links
License
MIT