Source: https://www.revvly.ai/docs/api/mcp

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](https://www.revvly.ai/docs/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.

i

Writes 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

/mcp

MCP · 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](https://www.revvly.ai/docs/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](https://www.revvly.ai/docs/reference/mcp-tools).

- **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

1. Client calls a toolA mutating tool, with mcp:write or a WRITE key.
2. Proposal storedValid for 15 minutes. Returns an actionId and an approval link.
3. Owner opens the linkSigned in to Revvly. The client cannot approve.
4. ApprovedThe write is applied once, even if retried.orDeclinedNothing is written.

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

## Related

- [The Revvly Assistant ›](https://www.revvly.ai/docs/assistant)
- [API Key ›](https://www.revvly.ai/docs/concepts/apiKey)
- [Public GraphQL API ›](https://www.revvly.ai/docs/api/graphql-public)