RevKeen MCP

RevKeen MCP lets AI hosts like Claude, Cursor, and VS Code query your billing, customer, subscription, and usage data through the Model Context Protocol — an open standard for connecting AI assistants to external tools securely.

On this page you will learn how to connect your AI host to RevKeen, what tools are available, how the scope-based access model works, and when to choose MCP over SDKs or the REST API.

Quick start

The fastest path: one command in your terminal.

claude mcp add --transport http revkeen https://mcp.revkeen.com/mcp

RevKeen opens a browser-based OAuth flow. Grant the scopes you need and you are connected. Try asking:

"List all overdue invoices from the last 30 days"

Connect from other hosts

If you are not using Claude Code, pick your host below and add the configuration.

// .cursor/mcp.json in your project root
{
  "mcpServers": {
    "revkeen": {
      "url": "https://mcp.revkeen.com/mcp"
    }
  }
}

// .vscode/mcp.json in your project root
{
  "servers": {
    "revkeen": {
      "type": "http",
      "url": "https://mcp.revkeen.com/mcp"
    }
  }
}

// claude_desktop_config.json
{
  "mcpServers": {
    "revkeen": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.revkeen.com/mcp"]
    }
  }
}

Server URL:      https://mcp.revkeen.com/mcp
Transport:       Streamable HTTP
Authentication:  OAuth 2.1 (browser flow)

After your host connects, RevKeen opens a browser-based OAuth flow. The granted scopes become the tool permissions for that session.

Example prompts

Once connected, try these prompts in your AI host to see what RevKeen MCP can do:

Prompt	What it uses
"List all overdue invoices from the last 30 days"	`invoices_list` with status filter
"Show me the details for customer Jane Smith"	`customers_list` (search) then `customers_get`
"Which subscriptions are currently in dunning?"	`subscriptions_list_in_dunning`
"What is the total usage for meter X this billing period?"	`usage_events_aggregate`
"Show me all payments over $500 this month"	`payments_list` with amount filter
"Check the usage balance for subscription abc-123"	`usage_balance_get`
"List all active subscriptions for customer def-456"	`subscriptions_list` with customer filter
"Dry-run a usage event to validate my payload"	`usage_events_dry_run`

Your AI host translates these into the appropriate tool calls automatically.

Available tools

The default profile exposes 20 read-only tools across eight areas. Write operations are behind a separate rollout policy.

Customers

Tool	Description	Parameters
`customers_list`	List customers with optional search and pagination	`search` (string), `limit` (1-100), `offset`
`customers_get`	Retrieve a single customer by UUID	`id` (required)

Invoices

Tool	Description	Parameters
`invoices_list`	List invoices with optional status and customer filters	`status`, `customerId`, `limit` (1-100), `offset`
`invoices_get`	Retrieve a single invoice with line items, taxes, and terms	`id` (required)

Payments

Tool	Description	Parameters
`payments_list`	List payment transactions for the merchant	`limit`, `offset`
`payments_get`	Retrieve a single payment transaction by ID	`id` (required)

Orders

Tool	Description	Parameters
`orders_list`	List orders with line items and fulfillment status	`limit`, `offset`
`orders_get`	Retrieve a single order by ID	`id` (required)

Subscriptions

Tool	Description	Parameters
`subscriptions_list`	List subscriptions with status and customer filters	`status` (active, canceled, past_due, trialing, paused), `customerId`, `page`, `limit` (1-100)
`subscriptions_get`	Retrieve a single subscription with full billing terms	`id` (required)
`subscriptions_list_in_dunning`	List subscriptions currently in payment recovery with retry and attempt metadata	None

Meters and pricing

Tool	Description	Parameters
`meters_list`	List usage meters with event names, aggregation types, and filters	None
`meters_get`	Retrieve a single meter with full filter configuration	`id` (required)
`meters_list_prices`	List price tiers for a meter including unit price and aggregation granularity	`meterId` (required)

Usage billing

Tool	Description	Parameters
`usage_events_list`	List recorded usage events with optional meter and time range filters	`meter_id`, `subscription_id`, time range
`usage_events_aggregate`	Aggregate usage events by sum, count, or average across dimensions	Aggregation function, grouping dimensions
`usage_events_dry_run`	Validate a usage event payload without recording it — safe for testing	Usage event payload
`usage_balance_get`	Get current usage balance and allowance for a subscription or customer	`subscription_id`, `customer_id`, `external_customer_id`, `meter_id`

Integrations

Tool	Description	Parameters
`integrations_list_packages`	List available integration packages and their connection statuses	None
`integrations_list_mappings`	List product and field mappings between RevKeen and external systems	None

All 20 tools are read-only. Write and destructive operations (create, update, delete, send) are not exposed in the default profile. RevKeen is rolling these out behind a separate policy as the tool contract stabilizes.

Scope model

Access is controlled through eight read-focused OAuth scopes. Each scope unlocks specific tools. When you connect, the OAuth consent screen lets you choose which scopes to grant.

Scope	What it unlocks
`customers:read`	`customers_list`, `customers_get`
`invoices:read`	`invoices_list`, `invoices_get`
`payments:read`	`payments_list`, `payments_get`
`orders:read`	`orders_list`, `orders_get`
`subscriptions:read`	`subscriptions_list`, `subscriptions_get`, `subscriptions_list_in_dunning`
`prices:read`	`meters_list`, `meters_get`, `meters_list_prices`
`usage:read`	`usage_events_list`, `usage_events_aggregate`, `usage_events_dry_run`, `usage_balance_get`
`integrations:read`	`integrations_list_packages`, `integrations_list_mappings`

If your AI host connects but tools are missing, check that you granted the right scopes during OAuth.

How access works

Your host connects

Your MCP host sends a connection request to https://mcp.revkeen.com/mcp using Streamable HTTP transport.

RevKeen redirects you to a browser-based OAuth 2.1 consent screen. You sign in with your RevKeen account and select which scopes (customers, invoices, payments, etc.) to grant for this session.

Scoped session created

RevKeen issues a session token scoped to your merchant and the approved scopes. The token is bound to the MCP session and cannot be reused outside the host.

Tool calls enforced server-side

Every tool call is checked against your scopes, merchant isolation, and rate limits. The server enforces access policy, audit logs every call, scrubs PII from responses, and manages the session lifecycle for you.

This is the key difference between MCP and handing an AI tool a raw API key. The MCP server enforces access boundaries, tenant isolation, and tool contracts — the AI host cannot bypass them.

Tool stability

The 20 v1 tools are stable. RevKeen follows these guarantees:

No breaking changes to existing tool names, required parameters, or response shapes within a version.
New tools are added behind rollout policies and announced in the changelog →.
Deprecations are communicated with at least 90 days notice before removal.
Write tools will be introduced incrementally with explicit opt-in.

You can build automation on top of the v1 tool contract with confidence.

Rate limits

The MCP server enforces per-session rate limits to protect merchant resources:

Scope	Limit
Per session	60 requests per minute
Per merchant	300 requests per minute (across all sessions)

If you exceed a rate limit, the server returns an error with a retry_after hint. Wait the indicated time before retrying.

Rate limits are enforced server-side with Redis-backed counters. In production, rate limiting uses a fail-closed model — if the rate limit backend is unavailable, requests are denied rather than allowed.

Operational endpoints

Endpoint	Purpose
`https://mcp.revkeen.com/`	Root metadata and public server information
`https://mcp.revkeen.com/healthz`	Health check (returns `200 OK` when healthy)
`https://mcp.revkeen.com/mcp`	Remote MCP endpoint (Streamable HTTP)

Troubleshooting

Host cannot connect

Confirm the URL is https://mcp.revkeen.com/mcp — not an older SSE or stdio endpoint.
Check that your host supports Streamable HTTP transport. Claude Desktop requires the @anthropic-ai/mcp-remote bridge (see setup above).
Verify your network allows outbound HTTPS to mcp.revkeen.com.

OAuth window does not open

Check for browser popup blockers — the OAuth flow opens in a new browser tab.
If you are behind a corporate proxy, ensure mcp.revkeen.com and your OAuth provider are allowlisted.
Try disconnecting and reconnecting in your host to re-trigger the flow.

Connected but tools are missing

Reconnect with the scopes you actually need. If you only granted customers:read, invoice tools will not appear.
Some hosts cache the tool list. Try reloading or restarting the host after reconnecting.

Tool call returns 403

The authenticated user may not have access to the target merchant. Verify your RevKeen account has the correct merchant role.
Check that the tool's required scope was granted during OAuth.

Tool call returns rate limit error

Wait for the retry_after period indicated in the error response.
If you are running automated workflows, add backoff logic between tool calls.
The per-merchant limit (300/min) is shared across all sessions — coordinate with teammates if multiple people are connected.

Data looks stale or empty

MCP reads live data from RevKeen. If results are empty, verify the merchant has the expected data in the RevKeen Dashboard.
The MCP server does not cache business data between calls.

When to use MCP vs SDKs vs REST vs CLI

Surface	Best for	Tradeoffs
MCP →	AI hosts and agent workflows — natural language queries, copilot integrations	Read-only today, scope-limited, requires OAuth
SDKs →	Application code you own and deploy — type-safe, full API coverage	Requires API key management, no AI-native features
API Reference →	Raw HTTP integrations, webhook receivers, protocol details	Most flexible but most manual
CLI →	Terminal workflows, operator scripts, quick lookups	Best for humans, not for code

If you are building an AI agent that needs to take actions (create invoices, process refunds), use the REST API → with an API key today. MCP write tools are coming soon.

Self-hosting and local development

For contributors or advanced local development, you can run the MCP server from the RevKeen monorepo:

pnpm --filter @revkeen/mcp-server dev

The local server at apps/mcp-server uses the official MCP SDK with the same Streamable HTTP transport, OAuth bearer-token verification, scoped tool access, launch-policy model, and rate limiting as production.