Skip to main content
Glama

Snooper

A flight recorder and safety gate for agent purchases.

Snooper is a remote MCP server that sits between any AI agent and PayPal. The agent never holds PayPal credentials. It calls propose_purchase; Snooper runs hard checks in code, asks Jev (TypeSafe System One) for the semantic judgments, writes every step to a tamper-evident trail, and returns one of three decisions: cleared, needs_review (a human decides) or blocked.

Built for the PayPal AI Hackathon 2026. Live demo: https://snooper-production-c0acfe19.up.railway.app (the UI needs the admin token; /store and /healthz are public).

Why

Agents are being handed payment rails, but there is no end-to-end record of why an agent paid, what influenced it, or whether the order matched what the owner wanted. A product page, an email or a tool result can carry a prompt injection that redirects a payment. PayPal's agent toolkit has no approval hook or spend caps. Snooper is that missing control layer, for any MCP client.

Related MCP server: Allowance

How it works

agent (any MCP client) ──MCP──▶ Snooper ──REST──▶ PayPal sandbox
                                  │
                                  ├─ code:  amount, currency, payee allowlist, daily cap, duplicates, expiry
                                  ├─ Jev:   5 typed judgments with probabilities
                                  └─ trail: append-only JSONL, HMAC hash chain

Code decides everything that is exact. Amount within the mandate, currency match, payee on the allowlist, daily cap, duplicate proposals, mandate expiry, the hash chain, provenance tags, and every PayPal call.

Jev decides only what is semantic, in one request per proposal (src/jev.ts):

Question

Type

Asks

cart_matches_request

Noul

Is the cart the product and quantity the owner asked for?

untrusted_sets_payment

Noul

Does untrusted text try to change who gets paid or how much?

injection_likelihood

Score 0-3

How strongly does untrusted text address the reader as instructions?

route_owner

Choice

Which reviewer fits: owner, finance or security?

shareable_fields

Noul per field

Does a field hold private data a reviewer should not see?

Thresholds live in src/config.ts and follow the TypeSafe guardrails cookbook: review at 0.35, act at 0.70, injection score blocks at 2.0, and block beats review beats pass. If Jev errors or times out, Snooper fails closed to needs_review. Trail confidence is the weakest gating hop, reduced when the agent supplied no evidence.

Every step is a hop in a per-trail JSONL file: trail_id, seq, ts, actor, kind, payload, provenance, confidence, prev_hash, hash, where hash = HMAC-SHA256(TRACE_SIGNING_SECRET, prev_hash + canonical JSON). The chain is recomputed on every read; an edited line shows as "Chain broken at hop N".

MCP tools (exactly three)

Tool

Purpose

propose_purchase

Cart + evidence (each with its source) in; { trail_id, decision, reasons, next } out

confirm_purchase

Rechecks, then captures through PayPal. Refuses unless the trail is cleared or approved

get_trail

Hops, decision, PayPal ids, verified flag

The mandate (owner, max amount, currency, payee allowlist, daily cap, request) is set by the owner in the UI or POST /api/mandates, never by the agent.

Connect a client (Claude Code shown; the bearer is read from your environment):

{
  "mcpServers": {
    "snooper": {
      "type": "http",
      "url": "https://snooper-production-c0acfe19.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" }
    }
  }
}

What is real and what is simulated

Part

Status

MCP server, hard rules, hash chain, alerts, UI, red-team

Real

Jev judgments

Real calls to TypeSafe (jev-1.14.0 at build time); seed and red-team trails use real answers too

PayPal order creation

Real sandbox orders, intent: AUTHORIZE, custom_id = trail id, deterministic PayPal-Request-Id

PayPal authorize + capture

Real code path, but the sandbox refuses a headless authorize: ORDER_NOT_APPROVED. The payer has to approve each order once in PayPal ("Approve in PayPal" in the trail). After that Snooper authorizes and confirm_purchase captures

Simulated capture

A labelled fallback a human can click in the UI. It never claims a PayPal result: status reads "Captured (simulated)", no capture id

Email alerts

Sent through Resend when RESEND_API_KEY, ALERT_EMAIL_FROM, ALERT_EMAIL_TO are set; otherwise the alert row says "Email not configured"

Webhooks

Registered on the sandbox app for the live URL (npm run webhook:register -- <base-url>). /webhooks/paypal rejects unsigned and forged events with 400. A genuinely signed event has not been observed yet: the first one fires when a payer approves an order

"Without gate" column on the Scoreboard

A stated baseline (the agent pays whatever it proposes), not a measurement

Card funding was also tried for a headless path and the sandbox merchant returned PAYEE_NOT_ENABLED_FOR_CARD_PROCESSING.

Run it

Node 22 or newer.

cp .env.example .env      # fill in the values; never commit .env
npm ci
npm run build
npm start                 # http://localhost:8787

Other commands:

npm test                              # hash chain + hard rules
npm run jev:check                     # real Jev answers for 8 sample proposals
npm run redteam                       # 12 red-team cases, in-process
npm run redteam -- --url <base-url>   # same, on a deployed instance
npm run demo:mcp -- <base-url> A      # real MCP client: scene A (also B, C, confirm <trail>, trail <trail>)
npm run pair -- <CODE> <base-url>     # sign a browser in without typing the admin token into it
npm run webhook:register -- <base-url> # register the PayPal sandbox webhook, store its id in .env

Endpoints: /mcp (bearer MCP_AUTH_TOKEN), /api/* (bearer ADMIN_TOKEN or a paired browser session), / (UI), /store (demo storefront with an injection toggle), /healthz, /webhooks/paypal.

Demo

  1. Open the UI, set a mandate: owner Mikey, max 120.00 USD, allowlist demo-store, "Buy one mechanical keyboard under 120 USD".

  2. Happy path. Ask your agent: "Buy the keyboard from the demo store." It proposes, Snooper clears it and creates the PayPal order. Approve the order once in PayPal sandbox, then the agent's confirm_purchase captures.

  3. Injection. Turn the injection toggle on at /store and ask again. The keyboard page now carries hidden text that tries to redirect the payment. The trail is blocked; the Jev hops show why.

  4. Human in the loop. Ask for two keyboards. The mandate said one, so the trail needs review. Approve it in the UI.

  5. Proof. Scoreboard shows the red-team run. "Verify chain" recomputes the hashes of any trail.

No MCP client to hand? "Simulate agent" on the Trails screen calls the same handlers.

Retakes: an identical purchase under the same mandate within 24 hours is blocked as a duplicate. Set a new mandate (two clicks, prefilled) before repeating a scene.

Red-team

Twelve fixed cases (src/redteam.ts): clean order, amount over mandate, payee off the allowlist, currency mismatch, duplicate, injected product page, vendor "update payee" note, cart mismatch, urgency pressure, benign untrusted text, Jev outage, tampered trail. Expectations are fixed before the run and results are reported as they come out. Jev is not infallible; a miss would show on the Scoreboard as a miss.

Limits

  • Sandbox only. Snooper refuses any PayPal base URL that is not the sandbox.

  • Single tenant: one admin token, one MCP token.

  • A buyer-side gateway cannot tag third-party orders; the demo store is ours, so it can.

  • Jev does not treat state as hostile, so injected text can sway it. Untrusted text is kept in its own labelled field and the code checks are the backstop.

Stack

Node 22, TypeScript, Express, the official MCP TypeScript SDK (Streamable HTTP), @typesafe-ai/sdk, PayPal Orders v2 REST, React, Vite, Tailwind CSS 4, daisyUI 5, Railway.

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI agents to use paid MCP tools within a human-approved budget by holding a PayPal sandbox authorization, checking each call against policy, recording usage in a durable ledger, and capturing or voiding the authorization at session close.
      6 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI agent to create and capture orders, refund captures, and pay suppliers through PayPal while the operator's policy fixes the payee, currency, and credential behind a broker that the agent never sees. Adds spending limits, human-approval thresholds, server-derived idempotency, and a hash-chained audit ledger, so a compromised or injected agent can only pick an operation and bounded values.
      2
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create orders, capture payments, issue refunds and send payouts against the PayPal sandbox through four guarded MCP tools, where every call is authenticated, validated, risk-scored and policy-checked, risky actions wait for human approval, and all state changes land in a tamper-evident hash-chained audit log.
      MIT