Building Agent-Native Monetization with RevenueCat MCP Server

The Problem: Subscription Infrastructure Wasn't Built for Agents

If you've ever scaffolded a new app from inside an AI coding assistant, you know the drill: the agent can write your Swift, generate your Kotlin, stub your API handlers — but the moment monetization enters the picture, you're kicked out of the flow. You're tabbing over to a dashboard, manually creating products, copying entitlement IDs, wiring up offerings, then pasting configuration back into your editor. The loop breaks.

That friction is the exact gap the RevenueCat MCP Server is designed to close.

Model Context Protocol (MCP) is an open standard that lets AI assistants securely call external tools and APIs. The RevenueCat MCP Server implements this protocol against RevenueCat's infrastructure, exposing 26 tools that let an AI agent — Claude, GPT-4, Cursor's AI, or any other MCP-compatible client — create apps, products, entitlements, offerings, packages, and paywalls entirely through natural language, without the developer ever touching the dashboard. Source

This tutorial walks through how to configure both authentication methods, understand the full tool surface, build practical agentic workflows, and run everything safely in production.

How It Works: The Architecture in One Paragraph

The cloud-hosted MCP Server lives at https://mcp.revenuecat.ai/mcp and acts as a thin, authenticated bridge between your AI assistant and the RevenueCat REST API v2. When your agent sends a natural language request — "Create a monthly subscription product for my iOS app" — the MCP server translates that intent into the appropriate API call, executes it against your RevenueCat project, and streams the result back to the agent. No local daemon, no Docker container required. Source

Step 1: Authentication — Do This Right

Authentication is where most teams trip up. The MCP server supports two methods, and which one you use depends on your client.

Method 1: OAuth (VS Code & Cursor only — recommended for IDE use)

VS Code Copilot and Cursor both support an automatic OAuth flow. When you connect either client, RevenueCat's OAuth server handles token issuance transparently — no API key to copy-paste or rotate manually.

Important: RevenueCat uses a curated client allowlist for OAuth. If your MCP client isn't VS Code or Cursor, the OAuth flow will fail with an "Unknown MCP Client" error. You'll need to contact RevenueCat Support to register your client. Source

For VS Code Copilot, add to your mcp.json:

{
  "servers": {
    "revenuecat-mcp": {
      "url": "https://mcp.revenuecat.ai/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

No Authorization header needed — VS Code's OAuth flow handles credential injection automatically. Source

OAuth tokens issued through this flow are prefixed atk_, expire after 1 hour, and are automatically refreshed via a refresh token (rtk_) valid for 1 month. Source

Method 2: API v2 Secret Key (all clients)

Every MCP-compatible client supports this path. You pass a sk_-prefixed secret API key as a Bearer token in the Authorization header. This is the universal option, and the one you'll use for headless agents, CI/CD pipelines, and server-side orchestration.

Getting your key: 1. Open your RevenueCat dashboard 2. Navigate to your project → API Keys 3. Click + New secret API key — copy the sk_... value immediately

Permissions matter: Use a write-enabled key if your agent will create or modify resources. A read-only key is sufficient for audit or inspection agents. Source

Configuration examples by client

Claude Code (CLI):

claude mcp add --transport http revenuecat https://mcp.revenuecat.ai/mcp \
  --header "Authorization: Bearer YOUR_API_V2_SECRET_KEY"

Cursor (mcp.json):

{
  "servers": {
    "revenuecat": {
      "url": "https://mcp.revenuecat.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_secret_key_here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "revenuecat": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.revenuecat.ai/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "YOUR_API_V2_SECRET_KEY"
      }
    }
  }
}

OpenAI Codex CLI (~/.codex/config.toml):

[mcp_servers.revenuecat]
command = "npx"
args = [
  "mcp-remote",
  "https://mcp.revenuecat.ai/mcp",
  "--header",
  "Authorization: Bearer ${AUTH_TOKEN}"
]
env = { AUTH_TOKEN = "YOUR_API_V2_SECRET_KEY" }
type = "stdio"
startup_timeout_ms = 20_000

Windows note: Replace npx with the full path C:\Program Files\nodejs\npx.cmd and include required env vars (APPDATA, LOCALAPPDATA, HOME, SystemRoot). Source

Testing your connection with MCP Inspector:

npx @modelcontextprotocol/inspector@latest

Set Transport Type → Streamable HTTP, URL → https://mcp.revenuecat.ai/mcp, and paste your Bearer token. Fire Show me my project details — a successful response confirms the setup. Source

Step 2: The 26 Tools — Organized by What They Do

The RevenueCat MCP server exposes 26 tools across six functional categories. Understanding this surface tells you what your agent is actually capable of. Source

🔷 Project Tools (1 tool)

📱 App Management (6 tools)

📦 Product Management (2 tools)

🔑 Entitlement Management (7 tools)

🗂 Offering & Package Management (5 tools)

🖼 Paywall Management (tools included in the 26)

The full parameter schema for each tool — including all required vs. optional fields — lives in the Tools Reference.

Step 3: Agentic Workflow Patterns

Here's where MCP becomes genuinely powerful. These are real prompt patterns you can give to Claude or any capable LLM once the MCP server is connected.

Pattern 1: Full App Bootstrap (Single Prompt)

This is the "greenfield" pattern — scaffold an entire monetization layer in one agent turn:

I'm building a new iOS photo editing app. Please:
1. Create an iOS app called "SnapPro" with bundle ID com.mycompany.snappro
2. Create a monthly subscription product for it
3. Create an annual subscription product for it
4. Create an entitlement called "pro_features" with display name "Pro Features"
5. Attach both products to the pro_features entitlement
6. Create a "default" offering and add monthly and annual packages to it
7. Set the default offering as the current offering

The agent executes each tool in sequence, threading output IDs (like app_id, entitlement_id) into subsequent calls automatically. Source

Pattern 2: Cross-Platform Mirroring

Launch parity across stores without the tedium:

Create the same "Premium Monthly" subscription product for both my iOS app
and my Android app, then attach both to the existing "premium" entitlement.

The agent calls mcp_RC_create_product twice (once per app_id), retrieves the product IDs, then calls mcp_RC_attach_products_to_entitlement with both IDs in a single array. Source

Pattern 3: Offering Audit & Inspection

Perfect for a read-only agent with a sk_-prefixed read-only key:

Show me the complete configuration for my main offering — all packages,
their attached products, and which entitlements are involved.

Pattern 4: Naming Convention Enforcement

Have an agent validate that all your packages follow RevenueCat's reserved identifiers before a release:

List all packages across all offerings. Flag any that don't use the standard
$rc_monthly, $rc_annual, $rc_three_month, $rc_six_month, $rc_lifetime,
or $rc_custom_* naming conventions.

RevenueCat's own best practices docs prescribe these exact identifiers for predictable SDK behavior. Source

Pattern 5: Offering Metadata Updates for Remote Config

You can store arbitrary JSON in offering metadata. An agent can update this programmatically — useful for feature flags or A/B test parameters:

Update the "summer_sale" offering metadata to set { "discount_badge": "40% OFF",
"highlight_color": "#FF6B35" } and mark it as the current offering.

Step 4: Production Best Practices

Separate Keys per Environment

Create distinct sk_ keys for dev, staging, and production. Never let an agent writing to your production project use the same credential as your development sandbox. Source

Scope Keys to Intent

Never Commit Keys to Version Control

Use environment variables or secrets management (e.g., .env, Vault, GitHub Actions secrets). The Claude Desktop and Codex CLI configurations above both demonstrate the ${AUTH_TOKEN} pattern for this reason. Source

OAuth Scopes Follow Least Privilege Too

If you're building a custom integration using the OAuth flow (not VS Code/Cursor), request only the scopes your agent needs. For example, an agent that only reads offerings needs project_configuration:offerings:read, not read_write. Full scope list: OAuth 2.0 Implementation Guide.

Incremental Changes > Bulk Operations

RevenueCat's own usage guidance recommends smaller, sequential changes over large bulk operations. This makes it easier to identify failures and roll back. Source

Error Handling

The MCP server returns structured errors with isError: true and descriptive messages covering: - Authentication errors — missing/invalid token or wrong key permissions - Validation errors — missing required parameters - API errors — full RevenueCat API response details

Build your agent prompts to explicitly ask for confirmation after each major resource creation step. Source

OAuth Troubleshooting Reference

Since OAuth issues are the most common setup failure:

Source

What's Next: The Agent-First Monetization Stack

The RevenueCat MCP Server represents a clear architectural shift: subscription infrastructure as a programmatic primitive, not a dashboard you visit. Once your AI assistant can manage entitlements and offerings directly, entire workflows become automatable:

• New feature launched? An agent creates a new entitlement, product, and offering, then links them — all triggered from a single natural language spec.
• New platform added? An agent mirrors your existing product catalog to the new store.
• Pricing experiment? An agent creates a new offering with different package metadata, ready for RevenueCat Experiments — without any dashboard clicks.

The 26 tools available today cover the full project configuration surface. Combined with the cloud-hosted endpoint that requires zero local infrastructure, it's the fastest path from "I'm building something" to "monetization is wired up."

Quick-Start Checklist

• [ ] Create a dedicated sk_ API v2 secret key for your MCP client in the RevenueCat Dashboard
• [ ] Choose your client: VS Code or Cursor → use OAuth; everything else → use API key
• [ ] Add the MCP server config to your client (mcp.json, Claude Desktop config, or Codex TOML)
• [ ] Verify with: "Show me my project details"
• [ ] Review the Tools Reference to understand your agent's full capability surface
• [ ] Create separate keys for dev vs. production environments

Sources

• RevenueCat MCP Server Overview
• RevenueCat MCP Server Setup
• RevenueCat MCP Tools Reference
• RevenueCat MCP Usage Examples
• RevenueCat MCP Best Practices & Troubleshooting
• API Keys & Authentication
• OAuth 2.0 Implementation Guide
• Model Context Protocol