Metered paywall

The meter governs PAYWALL-policy articles only. Observe and Advertise
articles always serve; Block always 403s.

Configuration

On the MCP page → Paywall & Identity section:

Knob	What	Default
Free articles per window	How many PAYWALL articles an install can read before the upsell	`5`
Window	`day` / `week` / `month` — how often the quota resets	`month`
Checkout URL	Where the upsell payload sends unsubscribed readers	unset
Require OAuth	When on, MCP route 401s without a token, forcing DCR + PKCE	off

How the meter counts

The meter is a counter keyed by (installId, articleId, windowKey):

installId is the OAuth client_id when the request carries a verified
bearer token, or the MCP session id otherwise.
articleId is the article being fetched.
windowKey is the bucket — e.g. "2026-06" for monthly.

Re-fetching the same article within the same window doesn't burn a credit
— the row already exists, the meter no-ops. This is what lets agents
follow up on an article they already read without penalizing the reader.

When the meter trips

get_article returns a structured upsell payload instead of the body:

{
  "status": "paywalled",
  "article": { "title": "...", "summary": "...", "url": "..." },
  "meter": { "remaining": 0, "limit": 5, "window": "month" },
  "upsell": {
    "headline": "You've used your 5 free articles this month.",
    "cta": "Subscribe to continue reading.",
    "checkoutUrl": "https://..."
  }
}

The agent renders this inline — Claude, ChatGPT, etc. all show the headline

CTA to the user.

Subscriber bypass

If a reader links their subscription via Flip-Pay or the
HMAC webhook, their OAuth tokens get tier=subscriber
and the meter early-returns. Their PAYWALL articles serve normally with no
MeterEvent row written.

Recommended starting values

5 articles / month for general-interest publications.
3 articles / month for serious trade or investigative titles where the
per-article value is high.
Checkout URL → wherever your existing reader subscription flow lives.

You can tune these any time without affecting in-flight meter rows.