RevClamp MCP Server

Evaluate Single-Customer Stripe Basil Ghost Usage

revclamp_evaluate_ghost_usage

Read-onlyIdempotent

Evaluate whether a specific customer's AI or API usage event constitutes unpaid ghost usage across multi-subscription Stripe 2025-03-31.basil state, enforcing fail-closed pagination (has_more must be explicitly false) and configurable 0-14 day dunning grace windows. Executes as a stateless, read-only entitlement evaluator with zero side effects. Returns structuredContent containing ok, mode, statelessEphemeralAudit, tenantId, and evaluation (isGhostLeak, isGhostUsage, reason). Use this tool for real-time per-customer entitlement gating; use revclamp_audit_revenue_leakage for batch multi-customer portfolio audits.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "revclamp_evaluate_ghost_usage"
  }
}

Input Schema

Name	Required	Description
`demo`	No	Optional simulation flag (boolean) for deterministic ghost-usage preview.
`timestamp`	No	Optional alias for occurredAt (ISO-8601 string, Unix epoch seconds, or Unix epoch milliseconds).
`customerId`	No	Stripe customer identifier to evaluate (format example: 'cus_9s6XKzkNRiz8i3', max 64 chars).
`occurredAt`	No	Optional usage event timestamp as ISO-8601 string, Unix epoch seconds, or Unix epoch milliseconds.
`usageEvent`	No	Optional metered usage event object containing customer_id (or stripe_customer_id), event_name, and occurred_at (or occurred_at_sec).
`occurred_at`	No	Optional snake_case alias for occurredAt (ISO-8601 string, Unix epoch seconds, or Unix epoch milliseconds).
`occurredAtSec`	No	Optional alias for usageTimestampSec: event timestamp as Unix epoch seconds, Unix epoch milliseconds, numeric string, or ISO-8601 string when the usage event occurred (used when usageTimestampSec is omitted).
`subscriptions`	No	Optional Stripe customer subscriptions payload: either a Stripe list object ({ data: [...], has_more: false }) or a raw array of up to 50 subscription objects containing id, status ('active', 'trialing', 'past_due', 'canceled', 'unpaid'), current_period_end, or items.data[].current_period_end in Unix seconds.
`currentPeriodEnd`	No	Optional camelCase alias for current_period_end (Unix epoch seconds, epoch milliseconds, or ISO-8601 string).
`usageTimestampSec`	No	Optional event timestamp as Unix epoch seconds, Unix epoch milliseconds, numeric string, or ISO-8601 string when the AI/API usage event occurred (defaults to current server Unix timestamp if omitted).
`current_period_end`	No	Optional flat subscription current_period_end (Unix epoch seconds, epoch milliseconds, or ISO-8601 string).
`subscriptionStatus`	No	Optional flat Stripe subscription status shorthand ('active', 'trialing', 'past_due', 'canceled', 'unpaid', 'incomplete', 'incomplete_expired', 'paused') when subscriptions is omitted.
`currentPeriodEndSec`	No	Optional flat subscription current_period_end in Unix epoch integer seconds.
`subscription_status`	No	Optional snake_case alias for subscriptionStatus.
`subscriptionsHasMore`	No	Pagination completeness flag (boolean). Must be explicitly set to false when passing a raw subscriptions array so RevClamp can verify no active subscription was truncated on a later page.
`dunningGracePeriodDays`	No	Dunning grace window in integer days (valid range: 0 to 14, default: 3) after latest_invoice_failed_at during which past_due subscriptions remain entitled.
`latestInvoiceFailedAtSec`	No	Optional flat latest_invoice_failed_at timestamp in Unix epoch integer seconds for past_due grace evaluation.
`latest_invoice_failed_at`	No	Optional flat latest_invoice_failed_at timestamp (Unix epoch seconds, epoch milliseconds, or ISO-8601 string).

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 14, 2026

addedInput schema / properties / occurredAtSec / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  }
+]

changedInput schema / properties / occurredAtSec / description

Previous value: -"Optional alias for usageTimestampSec: Unix epoch timestamp in integer seconds (e.g. 1761264000) when the usage event occurred (used when usageTimestampSec is omitted)."New value: +"Optional alias for usageTimestampSec: event timestamp as Unix epoch seconds, Unix epoch milliseconds, numeric string, or ISO-8601 string when the usage event occurred (used when usageTimestampSec is omitted)."

removedInput schema / properties / occurredAtSec / type
```
Removed value: -"integer"
```

addedInput schema / properties / usageTimestampSec / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  }
+]

changedInput schema / properties / usageTimestampSec / description

Previous value: -"Optional Unix epoch timestamp in integer seconds (e.g. 1761264000) when the AI/API usage event occurred (defaults to current server Unix timestamp if omitted)."New value: +"Optional event timestamp as Unix epoch seconds, Unix epoch milliseconds, numeric string, or ISO-8601 string when the AI/API usage event occurred (defaults to current server Unix timestamp if omitted)."

removedInput schema / properties / usageTimestampSec / type
```
Removed value: -"integer"
```

Changed12 schema fields changedNov 9, 2026

addedInput schema / properties / currentPeriodEnd

Added value: +{
+  "description": "Optional camelCase alias for current_period_end (Unix epoch seconds, epoch milliseconds, or ISO-8601 string)."
+}

addedInput schema / properties / currentPeriodEndSec

Added value: +{
+  "description": "Optional flat subscription current_period_end in Unix epoch integer seconds.",
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / current_period_end

Added value: +{
+  "description": "Optional flat subscription current_period_end (Unix epoch seconds, epoch milliseconds, or ISO-8601 string)."
+}

addedInput schema / properties / latestInvoiceFailedAtSec

Added value: +{
+  "description": "Optional flat latest_invoice_failed_at timestamp in Unix epoch integer seconds for past_due grace evaluation.",
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / latest_invoice_failed_at

Added value: +{
+  "description": "Optional flat latest_invoice_failed_at timestamp (Unix epoch seconds, epoch milliseconds, or ISO-8601 string)."
+}

addedInput schema / properties / occurredAt

Added value: +{
+  "description": "Optional usage event timestamp as ISO-8601 string, Unix epoch seconds, or Unix epoch milliseconds."
+}

addedInput schema / properties / occurred_at

Added value: +{
+  "description": "Optional snake_case alias for occurredAt (ISO-8601 string, Unix epoch seconds, or Unix epoch milliseconds)."
+}

addedInput schema / properties / subscriptionStatus

Added value: +{
+  "description": "Optional flat Stripe subscription status shorthand ('active', 'trialing', 'past_due', 'canceled', 'unpaid', 'incomplete', 'incomplete_expired', 'paused') when subscriptions is omitted.",
+  "type": "string"
+}

addedInput schema / properties / subscription_status

Added value: +{
+  "description": "Optional snake_case alias for subscriptionStatus.",
+  "type": "string"
+}

changedInput schema / properties / subscriptions / description

Previous value: -"Required Stripe customer subscriptions payload: either a Stripe list object ({ data: [...], has_more: false }) or a raw array of up to 50 subscription objects containing id, status ('active', 'trialing', 'past_due', 'canceled', 'unpaid'), current_period_end, or items.data[].current_period_end in Unix seconds."New value: +"Optional Stripe customer subscriptions payload: either a Stripe list object ({ data: [...], has_more: false }) or a raw array of up to 50 subscription objects containing id, status ('active', 'trialing', 'past_due', 'canceled', 'unpaid'), current_period_end, or items.data[].current_period_end in Unix seconds."

addedInput schema / properties / timestamp

Added value: +{
+  "description": "Optional alias for occurredAt (ISO-8601 string, Unix epoch seconds, or Unix epoch milliseconds)."
+}

removedInput schema / required
```
Removed value: -[
-  "subscriptions"
-]
```

Changed4 schema fields changedOct 26, 2026

changedInput schema / properties / customerId / description

Previous value: -"Required Stripe customer identifier to evaluate (format example: 'cus_9s6XKzkNRiz8i3', max 64 chars)."New value: +"Stripe customer identifier to evaluate (format example: 'cus_9s6XKzkNRiz8i3', max 64 chars)."

addedInput schema / properties / demo

Added value: +{
+  "description": "Optional simulation flag (boolean) for deterministic ghost-usage preview.",
+  "type": "boolean"
+}

addedInput schema / properties / usageEvent

Added value: +{
+  "description": "Optional metered usage event object containing customer_id (or stripe_customer_id), event_name, and occurred_at (or occurred_at_sec).",
+  "type": "object"
+}

changedInput schema / required

Previous value: -[
-  "customerId",
-  "subscriptions"
-]New value: +[
+  "subscriptions"
+]

First observedOct 25, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, non-destructive and closed-world, yet the description adds substantive behavior: fail-closed pagination requiring has_more to be explicitly false, a configurable 0-14 day dunning grace window with a default of 3, and a stateless evaluator with no persistence. It also enumerates the returned structuredContent keys, which matters because no output schema exists. Minor redundancy in restating 'zero side effects' already implied by destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then behavior, then return shape, then the sibling routing rule — a sensible order with no filler sentences. Density is high and some phrasing ('2025-03-31.basil state', 'statelessEphemeralAudit') is jargon-heavy, but each clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter tool with no output schema, the description does the important work: it discloses the response envelope and the fail-closed contract. The remaining gap is that all 18 parameters are optional, and the description never states the minimal viable invocation (e.g., that customerId plus some usage/subscription input is required in practice).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not by itself convey: the pagination flag exists to prove no active subscription was truncated, and the grace-window parameter governs entitlement for past_due subscriptions. It does not explain the alias/fallback relationships among the many timestamp and subscription parameters, which is where an agent would most likely err.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource — evaluate whether a customer's usage event is unpaid ghost usage within Stripe basil subscription state — and names the sibling it is not (revclamp_audit_revenue_leakage) so the agent can discriminate without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit routing rule: use this tool for real-time per-customer entitlement gating, and use revclamp_audit_revenue_leakage for batch multi-customer portfolio audits. That is a when-to-use plus a named alternative with the condition that selects it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All RevClamp MCP Server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.