Add MCP docs (#952)

Author: ekurutepe

docs/tools/mcp.mdx

@@ -0,0 +1,51 @@
+---
+title: RevenueCat MCP Server
+sidebar_label: RevenueCat MCP
+slug: mcp
+excerpt: AI-powered subscription management through natural language interactions
+hidden: false
+---
+
+The RevenueCat MCP (Model Context Protocol) Server enables AI assistants to manage subscription apps, products, entitlements, and everything in-between without requiring direct dashboard access. This powerful tool provides 26 different capabilities for complete subscription management through natural language interactions.
+
+## Getting Started
+
+### 1. [Overview](./mcp/overview)
+Learn what MCP is, explore deployment options, and understand the core features and capabilities of the RevenueCat MCP server.
+
+### 2. [Setup](./mcp/setup)
+Get your API keys and configure the MCP server for either cloud deployment or local VS Code/Cursor extension.
+
+### 3. [Tools Reference](./mcp/tools-reference)
+Complete reference documentation for all 26 available tools, organized by category with detailed parameter tables.
+
+### 4. [Usage Examples](./mcp/usage-examples)
+Natural language interaction examples and common usage patterns to help you get the most out of the MCP server.
+
+### 5. [Best Practices & Troubleshooting](./mcp/best-practices-and-troubleshooting)
+Security considerations, best practices, troubleshooting guides, and advanced usage patterns.
+
+## Quick Start
+
+Choose your deployment option:
+
+**Cloud Server**: Perfect for team collaboration and production use
+- Access: `https://mcp.revenuecat.ai/mcp`
+- Authentication: Bearer token with your RevenueCat API v2 key
+
+**Local Extension**: Ideal for individual development
+- Install from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=RevenueCat.revenuecat-mcp-extension)
+- Configure with your API key directly in VS Code/Cursor
+
+## What You Can Do
+
+With natural language commands, you can:
+
+- **Manage Apps**: Create, update, and configure apps across all platforms
+- **Handle Products**: Set up subscription products and in-app purchases
+- **Control Entitlements**: Define and manage user access permissions
+- **Organize Offerings**: Create and structure subscription offerings and packages
+- **Generate Paywalls**: Build paywalls for your offerings
+- **Monitor Configuration**: Review and validate your subscription setup
+
+Start with the [Overview](./mcp/overview) to understand the fundamentals, or jump to [Setup](./mcp/setup) if you're ready to begin configuration.

docs/tools/mcp/best-practices-and-troubleshooting.mdx

@@ -0,0 +1,110 @@
+---
+title: Best Practices & Troubleshooting
+sidebar_label: Best Practices & Troubleshooting
+slug: best-practices-and-troubleshooting
+excerpt: Best practices, troubleshooting, and security considerations for RevenueCat MCP
+hidden: false
+---
+
+## Best Practices
+
+### API Key Management
+
+- **Use dedicated keys**: Create separate API keys for different environments (development, staging, production)
+- **Principle of least privilege**: Use read-only keys when write access isn't needed
+- **Regular rotation**: Periodically rotate your API keys for security
+
+### Naming Conventions
+
+- **Package identifiers**: Follow RevenueCat conventions:
+  - `$rc_monthly` for monthly subscriptions
+  - `$rc_annual` for annual subscriptions
+  - `$rc_three_month`, `$rc_six_month` for other durations
+  - `$rc_lifetime` for lifetime purchases
+  - `$rc_custom_*` for custom packages
+
+### Workspace Organization (Local Extension)
+
+- **One workspace per project**: Keep different RevenueCat projects in separate workspaces
+- **Environment separation**: Use different API keys for different environments
+- **Documentation**: Keep your `mcp.json` structure documented for team members
+
+## Troubleshooting
+
+### Common Issues
+
+#### MCP Server Not Enabled (Local Extension)
+
+**Symptoms**: No responses from RevenueCat commands in chat
+**Solution**:
+
+1. Go to **Cursor Settings → MCP**
+2. Click **Enable**
+3. Click **Refresh**
+
+#### MCP Server Disconnected
+
+**Symptoms**: Previously working commands stop responding
+**Solution**:
+
+1. Go to **Cursor Settings → MCP** (for local extension)
+2. Click **Refresh**
+3. If issues persist, reload the window
+
+#### API Key Issues
+
+**Symptoms**: Authentication errors or "unauthorized" responses
+**Solution**:
+
+1. Verify your API key is correct
+2. Check key permissions (read vs write)
+3. Ensure the key belongs to the correct project
+4. For local extension: Re-run `RevenueCat: Set Project Secret Key`
+5. For cloud server: Update your Authorization header
+
+#### Missing mcp.json (Local Extension)
+
+**Symptoms**: Extension doesn't work after setting API key
+**Solution**:
+
+1. The extension should create `mcp.json` automatically
+2. If missing, remove and re-add your API key
+3. Check that the MCP server port is correctly configured
+
+### Debug Information
+
+For troubleshooting:
+
+1. Check the VS Code Developer Console for debug logs (local extension)
+2. Verify `mcp.json` contains the correct server configuration (local extension)
+3. Test with simple commands like "Show me my project details"
+4. Ensure API key has proper permissions in RevenueCat dashboard
+
+## Security Considerations
+
+- **Never commit `mcp.json`**: Always add it to `.gitignore` (local extension)
+- **Use environment-specific keys**: Don't use production keys in development
+- **Regular key rotation**: Change API keys periodically
+- **Team access**: Use separate keys for each team member when possible
+- **Monitor usage**: Regularly review API key usage in your RevenueCat dashboard
+
+## Error Handling
+
+Both deployment options provide detailed error responses including:
+
+- Authentication errors for missing or invalid tokens
+- API errors with full RevenueCat API response details
+- Validation errors for invalid parameters
+
+All errors are returned in a consistent format with `isError: true` and descriptive error messages.
+
+## Getting Help
+
+- **RevenueCat Documentation**: [docs.revenuecat.com](https://docs.revenuecat.com)
+- **API Reference**: [docs.revenuecat.com/reference](https://docs.revenuecat.com/reference)
+- **Support**: Contact RevenueCat support through the dashboard
+- **Community**: Join the RevenueCat community discussions
+
+---
+
+_This MCP server leverages the Model Context Protocol to provide seamless integration between RevenueCat's API and your development workflow. Happy monetizing! 🚀_

docs/tools/mcp/overview.mdx

@@ -0,0 +1,51 @@
+---
+title: RevenueCat MCP Server Overview
+sidebar_label: Overview
+slug: overview
+excerpt: AI-powered subscription management through natural language interactions
+hidden: false
+---
+
+The RevenueCat MCP (Model Context Protocol) Server enables AI assistants to manage subscription apps, products, entitlements, and everything in-between without requiring direct dashboard access. This powerful tool provides 26 different capabilities for complete subscription management through natural language interactions.
+
+## What is MCP?
+
+[Model Context Protocol](https://modelcontextprotocol.io/) is a standard that allows AI assistants to securely access external tools and data sources. The RevenueCat MCP server acts as a bridge between AI assistants (like Claude, GPT-4, etc.) and the RevenueCat API, enabling natural language interactions with your subscription infrastructure.
+
+## Deployment Options
+
+The RevenueCat MCP server is available in two deployment configurations, each with the same core functionality but different setup and use cases:
+
+### Cloud MCP Server
+
+**Best for:**
+
+- Team collaboration and shared access
+- Production environments
+- Integration with multiple AI assistants or applications
+- When you need a centralized, always-available service
+
+**Access:** `https://mcp.revenuecat.ai/mcp`
+
+### Local MCP Extension (VS Code/Cursor)
+
+**Best for:**
+
+- Individual developer use
+- Local development and testing
+- Quick setup and immediate use
+- Integration with your existing Cursor/VS Code workflow
+
+**Install:** Available in the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=RevenueCat.revenuecat-mcp-extension)
+
+## Core Features & Capabilities
+
+Both deployment options provide identical functionality with 26 powerful tools for:
+
+- **Project Management**: Access and view RevenueCat project details
+- **App Management**: Create, read, update, and delete apps across multiple platforms (iOS, macOS, Android, Amazon, Stripe, RC Billing, Roku)
+- **Product Management**: Manage subscription products and in-app purchases
+- **Entitlement Management**: Control user access and permissions
+- **Offering & Package Management**: Create and manage subscription offerings
+- **Paywall Management**: Create and manage paywalls
+- **Analytics Integration**: Built-in tracking for tool usage

docs/tools/mcp/setup.mdx

@@ -0,0 +1,120 @@
+---
+title: RevenueCat MCP Server Setup
+sidebar_label: Setup
+slug: setup
+excerpt: Configure RevenueCat MCP Server for cloud or local deployment
+hidden: false
+---
+
+## Prerequisites
+
+- RevenueCat project with API v2 access
+- RevenueCat API v2 secret key
+
+## Getting Your API Key
+
+1. Open your [RevenueCat dashboard](https://app.revenuecat.com/)
+2. Navigate to your project's **API Keys** page
+3. **Create a new API v2 secret key** and copy it
+
+> **💡 Tip**: Create a dedicated API key for the MCP server to keep your credentials organized.
+
+> **⚠️ Permissions**:
+>
+> - Use a **write-enabled key** if you plan to create/modify resources
+> - A **read-only key** works if you only need to view data
+
+## Cloud MCP Server Setup
+
+### Using with MCP Inspector
+
+For testing and development:
+
+```bash
+npx @modelcontextprotocol/inspector@latest
+```
+
+Configure the inspector with:
+
+- **Transport Type**: Streamable HTTP
+- **URL**: `https://mcp.revenuecat.ai/mcp`
+- **Authentication**: Bearer Token with your RevenueCat API v2 secret key
+
+### Using with VS Code Copilot
+
+Add to your VS Code settings:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "revenuecat": {
+        "type": "http",
+        "url": "https://mcp.revenuecat.ai/mcp",
+        "headers": {
+          "Authorization": "Bearer YOUR_API_V2_SECRET_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+### Using with Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "revenuecat": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"],
+      "env": {
+        "FETCH_BASE_URL": "https://mcp.revenuecat.ai/mcp",
+        "FETCH_HEADERS": "{\"Authorization\": \"Bearer YOUR_API_V2_SECRET_KEY\"}"
+      }
+    }
+  }
+}
+```
+
+## Local MCP Extension Setup
+
+### 1. Install Extension
+
+1. Open VS Code or Cursor
+2. Go to Extensions marketplace
+3. Search for "RevenueCat MCP"
+   > **⚠️ Visual Studio Marketplace**:
+   >
+   > This only works if your VS Code fork has access to the Visual Studio Marketplace.
+   >
+   > If not, you can install the extension manually by downloading the [VSIX file](https://drive.google.com/file/d/1VcyqirfdJtrAMuDnMTBkU8USCbdvMTMn/view?usp=share_link).
+4. Click **Install**
+
+### 2. Configure Extension
+
+1. Open Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
+2. Run: **RevenueCat: Set Project Secret Key**
+3. Paste your API key when prompted
+
+This creates an `mcp.json` file in your workspace with the MCP server configuration.
+
+> **🔒 Security**: Add `mcp.json` to your `.gitignore` to avoid committing your API credentials.
+
+### 3. Enable MCP in Cursor
+
+1. Go to **Cursor Settings → MCP**
+2. Click the **Enable** button
+3. Click the **Refresh** icon to activate the server
+
+## VS Code Extension Commands
+
+The local extension provides additional VS Code commands for key management:
+
+| Command                                    | Description                           |
+| ------------------------------------------ | ------------------------------------- |
+| `RevenueCat: Set Project Secret Key`       | Set or update your API key            |
+| `RevenueCat: Remove Project Secret Key`    | Delete your stored API key            |
+| `RevenueCat: Show your project secret key` | Display your current API key (masked) |