Skip to main content
Glama
PayStage MCP Server

PayStage MCP Server

PayStage

npm CI licence

Your agent's wallet should not sign because a server asked it to.

PayStage sits between an agent and the x402 payment it is about to make, and answers one question before the signature exists: should this payment happen? Every tool returns pay, review, or do_not_pay, with the rule that fired and a receipt you can keep.

The gap it fills is narrow and load-bearing. x402 makes paying trivial and leaves deciding to the caller: a wallet enforces signatures, not intent. @paystage/x402-guard evaluates the challenge before the wallet signs, so a wrong payee, an over-cap amount or an unknown asset never reaches the signing step at all.

Where the money does not move

The design point is the arrow that is missing. The wallet signs only after the challenge has been judged; a refusal returns the seller's own 402 with a verdict header attached, so there is nothing to revoke afterwards.

sequenceDiagram
    autonumber
    participant A as Agent
    participant S as Seller
    participant G as PayStage guardFetch
    participant W as Wallet

    A->>S: request the paid resource
    S-->>A: 402 + payment-required challenge
    A->>G: the same request, wrapped
    G->>G: decode challenge, evaluatePayment(challenge, policy)
    alt do_not_pay, or review with onReview refuse
        G-->>A: original 402 + x-paystage-verdict
        Note over G,W: nothing is signed
    else pay, or review with onReview pay
        G->>W: x402-fetch stages the payment
        W-->>S: signed payment
        S-->>G: 200 + resource
        G-->>A: 200 + x-paystage-verdict
    end

review is reported as review either way. When onReview: "pay" lets an ambiguous payment through, the header still says review, because the evaluator's finding and the caller's instruction to tolerate it are different facts — a caller that cannot tell "clean" from "warned but paid" cannot audit itself. The rule that fires travels in x-paystage-reason-codes.

What decides

%% tight ranks: this is read at a glance, not studied
%%{init: {"flowchart": {"nodeSpacing": 26, "rankSpacing": 30}}}%%
flowchart TD
    C[402 challenge] --> E["evaluatePayment<br/>guards: agent budget, time window,<br/>x402Version 2, accepts present"]
    E --> P{any accept judged pay?}
    P -- yes --> PAY[pay, cheapest accept]
    P -- no --> R{any accept judged review?}
    R -- yes --> REV[review]
    R -- no --> DN[do_not_pay]
    REV --> O{onReview}
    O -- pay --> SIGN[x402-fetch signs, request retries]
    O -- refuse --> X[refused, 402 returned unsigned]
    PAY --> SIGN
    DN --> X

do_not_pay is a real refusal, not a warning: a payee on the known-drainer or OFAC list, an over-cap amount, a wrong network or asset, a policy that denies the payee, or a challenge that cannot be parsed. review is the narrow middle — a payee the policy has no opinion about, under a policy that chose unknown_payee: "review" over the stricter default. Both verdicts and the branch logic are in packages/preflight/src/evaluate.ts; the hook that uses them is packages/x402-guard/src/index.ts.

Try it without installing anything:

curl -s -X POST https://api.paystage.xyz/v1/evaluate_mcp_payment \
  -H 'content-type: application/json' \
  -d '{"payment_required":{…},"policy":{…}}'

The hosted endpoint serves a real verdict with no payment and no account for the first 1,000 calls per IP per day — an agent cannot fill in a signup form, so requiring one would exclude exactly the callers this is built for.

The ten tools

Nine are read-only. None of them signs, holds a key, or moves money — the agent stays the only signer, which is the entire product.

The tenth, request_testnet_funds, is the one deliberate exception and it is worth naming rather than hiding: it asks our Base Sepolia faucet for 0.5 test USDC so you can exercise the paid path before spending anything. It moves testnet funds from a wallet we hold, touches nothing you own, and cannot reach mainnet.

All ten are listed with what each answers in Tools. 语言 / Language: English · 简体中文

Related MCP server: x402-triage-mcp

See it work

npm run build -w @paystage/preflight && node examples/run.mjs

Four challenges against one policy, four verdicts with reasons — no network, no keys. See examples/.

Quick start

# Option 1: run instantly
npx -y -p @paystage/mcp paystage-mcp

# Option 2: install locally, then use the package bin
npm install @paystage/mcp
npx 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.

@paystage/mcp is the umbrella MCP server (10 tools, including evaluate_hip3_trade and evaluate_velocity). It exposes the PayStage tools over stdio and reads a local policy file. See SECURITY.md for exactly what it accesses and why.

Connect in one command

Copy the line for your client. The remote is Streamable HTTP, so nothing needs installing.

# Claude Code
claude mcp add --transport http paystage https://api.paystage.xyz/mcp

# Cursor — append to .cursor/mcp.json
{"mcpServers":{"paystage":{"url":"https://api.paystage.xyz/mcp"}}}

# Any MCP client, or just to read the tool schemas without an account
npx -y mcporter list https://api.paystage.xyz/mcp

Prefer it local? npx -y -p @paystage/mcp paystage-mcp runs the same ten tools over stdio and reads a policy file from disk.

What it does not catch

A gate that claims to stop every bad payment is the thing this project argues against. LIMITS.md is the honest boundary — settlements that already happened, payees that look legitimate and do not deliver, payments made outside the wrapper, and eight more. Read it before you trust the gate with money.

Every term this project uses — x402, facilitator, settlement, EIP-3009, HIP-3, CAIP-2 and the rest — is defined in one page.

State of x402 — issue 1: the registry counted, with its method.

Verdict vocabulary

Three states, and every project in this space picked its own three words. If you run more than one of these gates, here is the mapping — the semantics line up more closely than the names suggest.

PayStage

Meaning

Same intent elsewhere

pay

within policy — sign and send

DingDawg ELIGIBLE · Black_Wall GO · MandatePay authorize

review

a human should look before paying

DingDawg STEP_UP · Black_Wall HOLD · MandatePay challenge

do_not_pay

refuse — a rule fired, and it is named

DingDawg DENY · Black_Wall STOP · MandatePay deny

One difference worth knowing: review is a policy instruction, not an oversight. onReview: "pay" treats it as permission, "refuse" treats it as a block — the gate never decides that for you.

How this compares with the four closest things in this lane — including what each has that we do not.

Start here if you are paying a seller

Burn five minutes before your agent pays anything — get the seller's challenge, write one policy file, ask for a verdict, and keep the receipt. curl and node, nothing to install.

Four ways in

You want

Use

the gate inside an agent's payment loop

@paystage/x402-guard

the tools in Claude Desktop or Cursor

@paystage/mcp

nothing installed at all — connect to a URL

https://api.paystage.xyz/mcp (Streamable HTTP, listed in the MCP Registry as a remote server)

a verdict from your own service, hosting included

POST https://api.paystage.xyz/v1/evaluate_mcp_payment

the evaluator as a library

@paystage/preflight

the Vercel AI SDK

@paystage/ai-sdk — two read-only tools, docs

Listed on

Pairings

  • PayMCP — it prices the seller's tool, this gates the buyer's payment; documented as two examples, no dependency either way

Configure

The same MCP config works for Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json).

Using npx

{
  "mcpServers": {
    "paystage": {
      "command": "npx",
      "args": ["-y", "@paystage/mcp"],
      "env": {
        "PAYSTAGE_POLICY_PATH": "/absolute/path/to/policy.json",
        "PAYSTAGE_RPC_URL": "https://mainnet.base.org"
      }
    }
  }
}

Using a local npm install

{
  "mcpServers": {
    "paystage": {
      "command": "node",
      "args": ["./node_modules/@paystage/mcp/dist/cli.js"],
      "env": {
        "PAYSTAGE_POLICY_PATH": "/absolute/path/to/policy.json",
        "PAYSTAGE_RPC_URL": "https://mainnet.base.org"
      }
    }
  }
}

The MCP server itself needs no environment variables and starts with an empty environment. It answers an MCP handshake and lists its tools with nothing configured — the policy arrives as an argument on each call, not as a file path. Verified:

env -i npx -y -p @paystage/mcp paystage-mcp   # completes `initialize`, lists ten tools

The two variables below are for the stdio CLI path, where a policy file is convenient. They are optional, and a directory that reads this section as "required configuration" will refuse to start a server that in fact needs nothing:

  • PAYSTAGE_POLICY_PATH (optional, CLI only): path to a policy.json the CLI reads at startup.

  • PAYSTAGE_RPC_URL (optional): RPC endpoint used by on-chain checks. Defaults to a public Base RPC.

Policies

Everything PayStage does is decided by one local policy file. Three complete, annotated examples are in registry/examples/ — copy one, change the addresses and amounts, and point PAYSTAGE_POLICY_PATH at it. Each is schema-exact for @paystage/policy and annotated field by field in registry/examples/README.md.

  • Reader bot — reads articles and search results; 0.05 USDC per call, unknown payees denied.

  • Trading bot — places HIP-3 orders; per-agent budgets, velocity windows and human review above 10 USDC.

  • Research agent — discovers data endpoints; unknown payees go to review, never an unattended pay.

Tools

tool

what it answers

evaluate_mcp_payment

should this x402 payment be signed? → pay · review · do_not_pay

list_outstanding_auths

which ERC-20 / Permit2 / EIP-3009 authorisations are still outstanding

evaluate_outstanding_auths

which of those need attention before the next payment

evaluate_hip3_trade

should this HIP-3 / trade.xyz order be placed? → allow · review · do_not_trade

evaluate_velocity

is this spend a burst, a spike, or a runaway cadence

verify_receipt

is this receipt really ours — and is it about this payment, still in date

decode_payment_required

what does this base64 402 header actually say

validate_policy

is this policy document valid, and if not which field

request_testnet_funds

0.5 Base Sepolia USDC for testing — one drip per address per 24h, with the reset time

evaluate_batch

the same question for several payments, one verdict each

Packages

Twelve packages. Only @paystage/mcp exposes ten MCP tools; the rest are the evaluator, guards for other frameworks, a policy schema and a skill — hence twelve packages and ten tools, which are different numbers.

Package

Role

Links

@paystage/mcp

umbrella MCP server — start here

npm

@paystage/x402-guard

policy gate for x402 clients, before the wallet signs

npm

@paystage/ai-sdk

the same gate as Vercel AI SDK tools

npm

@paystage/auth-watch

outstanding ERC-20 / Permit2 / EIP-3009 authorisations

npm

@paystage/eliza-plugin

the gate as an elizaOS action

in this repo — first publish pending

@paystage/n8n

the gate as an n8n community node

in this repo — first publish pending

@paystage/policy

policy schema and loader

npm

@paystage/preflight

x402 payment preflight (the evaluator)

npm

@paystage/skill

agent skill manifest

npm

@paystage/trade-preflight

HIP-3 / trade.xyz order preflight

npm

@paystage/velocity

rate and spend-pattern checks

npm

@paystage/x-evm

chain-agnostic EVM helpers

npm

Verify it yourself

Four claims are checked against production, not against the repo — run all of them with one command:

npm run check:live

check

what it asks the deployed system

check-deployed-sha

is the site serving the newest deployable commit?

check-mcp-live

does /mcp serve exactly the ten declared tools?

check-receipt-live

does a real receipt verify — and does an altered one fail?

check-sanctions-live

does the API refuse a sanctioned payee even when the policy allows it?

Each exits non-zero on failure, so they belong in a release, not in a badge.

The wider conformance kit checks the published surfaces against reality:

node apps/hosted/scripts/conformance.mjs

It checks the published surfaces against reality — manifest shape, the ten tools being listed, machine surfaces being genuinely different from each other, health and timing headers on both networks, the receipt key endpoint, that an unpaid evaluation is challenge-only, and that malformed input fails closed. Read-only: no payment, no key, no account. Exit code 1 if anything is off.

It runs daily in CI (cadence.yml) and the result history is on the site.

Supply chain

Socket.dev scores packages on capability, so a payment-safety tool will always carry flags: it reads a policy file, reads two environment variables and talks to an RPC. Every package README states exactly what it touches and why, and SECURITY.md has the full table. The umbrella @paystage/mcp is ~16 KB with no network, no filesystem and no eval of its own — the capability lives in the tools it bundles.

Development

This is an npm-workspaces monorepo — package-lock.json is the lockfile and CI runs npm ci. There is no pnpm workspace and no lint script; npm run typecheck is the check that exists.

npm ci
npm run build
npm test
npm run typecheck

Contributing

PayStage is built in the open, outside contributions are welcome.

  • Add a drainer address. Open a PR adding it to KNOWN_DRAINERS.md with a public source link (incident report, explorer label, or security write-up). Unsourced addresses won't be merged.

  • Add an integration example. LangChain, AgentKit, ElizaOS and others are all welcome.

  • Report a bypass. If an unsafe payment gets past preflight, open an issue. That's the most valuable contribution there is.

Look for issues labelled good first issue to get started.

License

MIT

Available Tools

5 tools
evaluate_hip3_tradeBInspect

Evaluate a Hyperliquid HIP-3 (trade.xyz) order against a TradePolicy before an agent trades. Returns decision allow | review | do_not_trade.

Inputs: proposal (required), policy, snapshot, policy_path.

evaluate_mcp_paymentCInspect

Evaluate an x402 PaymentRequired payload against a PayStage spending policy before paying

Inputs: payment_required (required), policy, policy_path.

evaluate_outstanding_authsCInspect

List and evaluate outstanding token authorizations against a policy

Inputs: wallet (required), policy, tokens, network, +4 more.

evaluate_velocityCInspect

Rolling-window rate and spend-pattern check for a proposed payment against recent action history and a policy.velocity config

Inputs: proposed (required), now_ms, policy, history, +1 more.

list_outstanding_authsCInspect

List outstanding token authorizations for a wallet

Inputs: wallet (required), policy, tokens, network, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 5 tools

    Disambiguation3/5

    The four evaluate_* tools target distinct objects (authorizations, x402 payments, HIP-3 trades, velocity), but evaluate_outstanding_auths overlaps heavily with list_outstanding_auths, and evaluate_velocity is arguably a sub-check of evaluate_mcp_payment, so an agent may be unsure whether to call one or both. Descriptions mitigate but do not fully resolve these boundaries.

    Naming Consistency4/5

    All names use snake_case with a verb_noun structure (evaluate_*/list_*), which is predictable and readable. Minor deviation: evaluate_velocity has no target-object noun, but it is still interpretable.

    Tool Count5/5

    Five tools is well-scoped for a policy-evaluation server, with each tool covering a distinct decision surface (auths, payments, trades, velocity) plus the listing helper. Nothing feels padded or missing at the count level.

    Completeness3/5

    The server covers evaluation paths well, but there is no tool surface for managing or inspecting the policies themselves (create/update/read policy config), nor for retrieving past decisions or action history beyond velocity. Agents can evaluate but cannot administer or audit the policy layer, which is a notable gap.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables no-payment triage of x402 payment surfaces, 402 Index health checks, and paid review handoff for authorized inspection.
      3
      48 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Deterministically evaluates whether a proposed agent spend action matches a supplied policy, returning ELIGIBLE, DENY, or STEP_UP with stable reason codes. Provides local policy evidence only, not payment authorization.
      1
      49 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables agents to request payment authorization against signed human mandates, enforcing policy-as-code limits and returning a decision (authorize, challenge, or deny) without moving funds.
      1
      1
      Apache 2.0