API Reference

Connect Claude to your billing data.

Revvly speaks the Model Context Protocol. Claude — or any MCP client — can ask the same live questions as the in-dashboard Assistant: clients, subscriptions, invoices, MRR, and catalog. Write-scoped connections can propose changes, but only a signed-in human can approve them in Revvly. Tenant comes from the credential, never from the question.

What MCP is here

The Assistant already answers billing questions inside Revvly. MCP is the same tool catalog on a second transport, so those answers work from Claude Desktop, Claude Code, claude.ai, MCP Inspector, or your own agent stack. There is no second authorization system and no GraphQL hop — the tools call the same tenant-scoped services the dashboard does.

iWrites use the same human-review boundary as the Assistant. A mutating tool stores a proposal and returns an approval link; nothing is written until the credential owner approves it while signed in to Revvly. Approval is not an MCP tool. Request mcp:write on OAuth, or issue an API key with coarse WRITE.

Endpoint

POST/mcpMCP · Streamable HTTP

Full URL: https://api.revvly.ai/mcp. The transport is Streamable HTTP and stateless. GET and DELETE are accepted for protocol probes. Authenticate with either an OAuth access token (interactive connect) or an API key (machine clients). A dashboard sign-in token is not accepted here.

Connect with OAuth

You do not paste a key. Sign in with your dashboard account and pick the workspace the client may read. How you add the connector differs between claude.ai and Claude Desktop.

claude.ai

Add Revvly as a custom connector and set the URL to https://api.revvly.ai/mcp. Leave headers empty. On Team and Enterprise plans only organization Owners can add custom connectors; members may only connect to connectors previously added by an Owner.

Claude Desktop

Add a remote MCP server and set the URL to https://api.revvly.ai/mcp. Leave headers empty.

1. Remote URL

Use the product-specific step above. The URL is the same: https://api.revvly.ai/mcp.

2. Sign in

Claude opens Revvly. Sign in with your usual dashboard account. The first request is unauthenticated; Revvly answers with a discovery header so Claude can register itself and complete the authorization.

3. Pick a workspace

The consent page lists the workspaces you belong to. Choose one. Every connection receives mcp:read. If the OAuth client requested mcp:write, the token can also propose changes; approval still happens only in the signed-in Revvly dashboard. Confirm, and Claude receives an access token bound to that workspace.

4. Ask

Claude can now ask about that workspace: overdue invoices, current MRR, who is renewing, what plans you sell. The workspace is never a tool argument.

Connect with an API key

Claude Code, MCP Inspector, and other machine clients send a Bearer API key. Issue one from Settings → API Keys. The key needs the coarse READ capability. Add WRITE to propose actions. The key cannot approve its proposals; its credential owner opens the returned approval link while signed in to the Revvly dashboard. An empty endpoint scope, or a scope that includes /mcp or *, is enough. A key scoped only to /usage is rejected.

claude_desktop_config.json / MCP server entry

{
  "mcpServers": {
    "revvly": {
      "type": "http",
      "url": "https://api.revvly.ai/mcp",
      "headers": {
        "Authorization": "Bearer rvly_sk_live_<your-key>"
      }
    }
  }
}

Capture the plaintext when the key is issued — it is shown once. The tenant is the key’s tenant. Rate limits are the same per-key limits as the rest of the platform.

What you can ask

The same read tools as the Assistant. Typical questions: current MRR and how it moved, overdue invoices for a client, usage against a meter, what bundles you sell. Mutating tools return a proposal with an approval link. The credential owner opens that link and approves or declines while signed in to Revvly; the MCP client cannot approve its own request. OAuth clients must request mcp:write; API keys need coarse WRITE. There are 20 read tools and 19 proposal tools; the full list with access levels is in the MCP tool catalogue.

search_docs

How Revvly works — pricing models, billing, catalog, analytics.

query_clients

Customer organizations: name, region, trial, dashboard link.

query_subscriptions

Subscriptions for a client or across the workspace.

get_billing_schedule

Why one subscription bills when it does — a prepaid span, an awaited go-live.

query_invoices

Invoices by client, status, or date. Credit notes are flagged.

get_analytics

Live MRR, ARR, churn, and NRR.

query_email_engagement

Sent emails with open counts and open rate (opens only).

query_usage

Live meter counters, usage audit, and the next-bill projection.

list_open_usage_readings

Closed-period readings missing an in-arrears quantity.

get_receivables

AR summary, past-due accounts, and per-client outstanding.

query_lifecycle_events

Subscription lifecycle log with MRR movement and when it happened.

list_regions

Regions and currencies you sell in.

list_catalog

Plans, capability groups, usage components and metered units — one or several per call.

get_catalog_prices

Base prices for a bundle or module.

create_client

Propose a new client. Nothing is written until a human approves in Revvly.

update_client

Propose an edit to an existing client — only the fields you set are changed.

create_subscription

Propose a new subscription.

query_discounts

The discount library, and a subscription's components and applied discounts.

apply_discount

Propose a discount on a subscription.

get_component_prices

Included units, tier or step boundaries and band prices of a plan.

list_forms

Forms with status, submission counts and hosted link.

get_form

One form: questions, settings, follow-up steps and unpublished changes.

query_form_submissions

Submissions to one form with every answer and step outcome.

summarize_form_submissions

Counts per day and source, follow-up health, winning options.

export_form_submissions

A CSV preview of submissions with a dashboard link to the file.

create_bundle

Propose a catalog bundle (draft).

create_module

Propose a module (draft).

create_metric

Propose a Meter.

create_variable_component

Propose a usage component around a Meter (draft).

set_catalog_prices

Propose base prices for a bundle or module.

set_available_periods

Propose the billing periods a draft bundle or module offers.

attach_variable_component

Propose attaching a published usage component to a draft.

publish_catalog_entity

Propose publishing a bundle, module or usage component.

enter_usage_reading

Propose sealing a missing in-arrears usage quantity.

waive_usage_reading

Propose waiving a closed period so it bills nothing.

create_form

Propose a new form as an unpublished draft.

update_form

Propose edits to a form draft.

publish_form

Propose publishing a form draft.

unpublish_form

Propose taking a published form offline.

archive_form

Propose archiving a form.

retry_form_submission

Propose re-running the failed follow-up steps of a submission.

Try it locally

MCP Inspector is useful when you are standing up a key or checking that OAuth reaches your login page.

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL:     https://api.revvly.ai/mcp
# Header:  Authorization: Bearer rvly_sk_live_<your-key>
# Or leave the header empty and complete the sign-in flow.

Errors & limits

401

Missing or invalid credential. The response includes a WWW-Authenticate header so OAuth clients can discover how to sign in.

403

An OAuth token without mcp:read, an API key without READ, or a write tool called without mcp:write.

429

Rate limit exceeded. See Retry-After.

Tool error

A failed tool returns a plain message on the MCP response. Stack traces are never sent to the client. Every call is recorded (tool name and argument names, not values).

Take actions

Writes use the same human-review boundary as the in-dashboard Assistant. A mutating tool stores a 15-minute proposal and returns an actionId plus an approval link. The credential owner must approve in Revvly; no approval operation is model-callable. The server atomically claims the action id so retries cannot run the write twice. Request mcp:write on OAuth (it is never added for you), or issue an API key with coarse WRITE.

A write through MCP

Client calls a tool
A mutating tool, with mcp:write or a WRITE key.
Proposal stored
Valid for 15 minutes. Returns an actionId and an approval link.
Owner opens the link
Signed in to Revvly. The client cannot approve.
Approved
The write is applied once, even if retried.
or
Declined
Nothing is written.

The client can only propose; the credential owner approves in Revvly, and the write runs once.