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:

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

Available tools

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

Customers

Invoices

Payments

Orders

Subscriptions

Meters and pricing

Storefront

Usage billing

Integrations

Scope model

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

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

How access works

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:

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

Operational endpoints

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

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.

See also