# Recurly MCP > Recurly MCP Server connects your AI client directly to your subscription billing platform. Your agent can manage accounts, adjust subscriptions, and pull invoice data without leaving your chat interface. It gives your AI the autonomy to read customer profiles via `get_account_details`, list all active plans with `list_catalog_plans`, or even cancel a recurring charge using `cancel_subscription`. This is pure billing ops automation. ## Overview - **Category:** money-moves - **Price:** Free - **Tags:** recurring-revenue, subscription-management, invoicing, revenue-operations, customer-billing, financial-data ## Description You're connecting **Recurly**—your whole subscription billing engine—straight into your AI client. Your agent doesn't need to jump between UIs anymore; it manages accounts, adjusts subscriptions, and pulls invoice history right from the chat window. This is pure operational power for billing, period. ### Managing Customer Accounts Your agent can handle customer data like a pro. It retrieves a directory listing of every account you manage using `list_accounts`. If you need deep background on one person, your AI client uses `get_account_details` to pull all the core billing and profile info tied to a specific customer ID. Need to onboard someone new? Your agent handles that with `create_account`, letting you provide the required code, email, and name details to establish a brand-new billing record. ### Controlling Subscriptions The agent gives you total control over recurring revenue streams. You can read the current state of any plan instance by calling `get_subscription_details`; this pulls the status, when it renews, and what specific plan model is running. To start a user on a paid service, your agent executes `create_subscription` for an existing customer account. When a subscription needs to be killed, `cancel_subscription` immediately stops the recurring charge; remember, that action's irreversible. If a client falls off the wagon but shouldn't, your agent brings them back with `reactivate_subscription`. To get a high-level overview of all active revenue sources, you can call `list_subscriptions`, which lists every subscription instance managed in the system. ### Billing Records and Plans Catalog The server handles all your financial data. If you need to verify payments or audit past charges, calling `list_invoices` generates a complete, chronological list of every invoice Recurly has processed for you. For understanding what products you're selling, the agent uses `list_catalog_plans` to retrieve the full details and list of every available product plan model in your entire catalog. The system also provides comprehensive oversight by allowing your client to pull a full directory listing of all customer accounts via `list_accounts`, which is foundational for any billing task. ## Tools ### cancel_subscription Immediately cancels an active subscription; this action is irreversible. ### create_account Creates a new customer billing account using provided code, email, and name details. ### create_subscription Sets up a new recurring subscription for an existing customer account. ### get_account_details Retrieves all core billing and profile information for a specific customer account ID. ### get_subscription_details Pulls the current status, renewal date, and plan specifics for one given subscription ID. ### list_accounts Provides a directory listing of all customer accounts managed within Recurly. ### list_catalog_plans Retrieves the full list and details of every available product plan model in your catalog. ### list_invoices Generates a chronological list of all financial invoices that have been processed by Recurly. ### list_subscriptions Lists every subscription instance managed in the system, providing a high-level overview of current recurring revenue sources. ### reactivate_subscription Brings back a subscription that was previously cancelled or expired without needing manual intervention. ## Prompt Examples **Prompt:** ``` List the last 5 invoices generated in our account. ``` **Response:** ``` I executed `list_invoices` restricted to 5 items. The returned set includes invoice IN_UUID_1012 ($59.00 - Paid) and IN_UUID_1013 ($199.00 - Pending). ``` **Prompt:** ``` Cancel the subscription with ID 'sub_39xjd82kw0'. ``` **Response:** ``` Running the `cancel_subscription` tool. The subscription 'sub_39xjd82kw0' has been set to cancel. It will not renew at the end of the current billing cycle. ``` **Prompt:** ``` Retrieve the billing details for account code 'cus_alpha_92'. ``` **Response:** ``` I invoked `get_account_details` for 'cus_alpha_92'. The account corresponds to 'Alpha Corp'. It currently has an active subscription to the 'Enterprise Tier' and zero past due payments. ``` ## Capabilities ### Manage Customer Accounts The agent can list all customers, retrieve full billing profiles (`get_account_details`), and create entirely new customer records with `create_account`. ### Control Subscriptions You can read current subscription status (`get_subscription_details`) or execute major lifecycle changes: creating, canceling, or reactivating a plan instance. ### Handle Invoicing and Plans The agent retrieves full lists of historical invoices (`list_invoices`) and pulls all available billing models from the catalog with `list_catalog_plans`. ## Use Cases ### Diagnosing a Failed Payment A customer calls: 'My service stopped.' The support agent asks the AI to run `get_account_details` for their ID. The agent reports they are suspended, and the engineer runs `reactivate_subscription`. Problem solved in minutes without leaving the chat. ### Onboarding a New Client The sales team finalizes a deal. They ask the AI to first run `create_account` with the client's details, and then immediately follow up by calling `create_subscription` using the 'Premium Tier' ID they found via `list_catalog_plans`. ### Auditing Revenue Loss The RevOps team needs to see all subs that expired last month. They ask the agent to run `list_subscriptions`, filter for 'Expired', and then use the list IDs to bulk-check their status before planning re-engagement campaigns. ### Handling Immediate Cancellations A client is leaving early. The agent confirms the account via `get_account_details`, then immediately runs `cancel_subscription`. All necessary billing changes are logged and confirmed without needing a human to click 'Submit' on three different forms. ## Benefits - Cancel billing instantly. Instead of navigating deep into the vendor console to end a service, you just ask your agent to `cancel_subscription` with an ID. It handles the irreversible change immediately. - Full account visibility. Need to know if 'Alpha Corp' is good? Use `get_account_details`. You get their current subscription status and payment history in one go, bypassing multiple dashboard clicks. - Zero context switching for billing. Whether you need to check old payments via `list_invoices` or activate a new plan using `create_subscription`, the entire operation stays inside your chat window. - Manage the full lifecycle. If a customer's sub lapses, don't escalate it. Ask the agent to run `reactivate_subscription`. It handles re-enrolling them based on their existing profile. - Understand your inventory. Want to know what plans you sell? Call `list_catalog_plans` to see all available models without manually browsing the product setup pages. ## How It Works The bottom line is: you talk to your AI agent, and it handles the complex API calls to Recurly for you. 1. Add the Recurly MCP server to your authorized module list. 2. Configure the server using your specific Recurly subdomain and Private API Key. 3. Talk naturally to your AI client. It detects the billing task (e.g., 'cancel this sub') and executes the necessary tool call. ## Frequently Asked Questions **How do I check if an account is active before creating a new subscription using `get_account_details`?** First, run `get_account_details` with the customer ID. This returns their current billing status and any existing subscriptions. Only proceed to `create_subscription` if the details show they are eligible for a new plan. **What is the difference between `list_subscriptions` and `list_accounts`?** `list_accounts` gives you a directory of all customer profiles (the people). `list_subscriptions` lists every individual recurring service instance attached to those accounts (the actual services). **Can I cancel a subscription without knowing the specific plan name? Use `cancel_subscription`?** No, you typically need the unique Subscription ID for `cancel_subscription`. First, run `get_subscription_details` to retrieve the exact identifier before sending the cancellation command. **What if I want to see every invoice ever generated? Should I use `list_invoices`?** Yes, `list_invoices` is the tool for this. It pulls a chronological list of all billing records from the system. You can filter that output by date or status in your prompt. **Do I need to manually create an account before running `create_subscription`?** Yes, you must first run `create_account` and ensure the account exists with a valid ID. The subscription tool needs an existing billing container to attach the new service. **If I run `get_subscription_details` for a subscription ID that doesn't exist, how does the tool handle the error?** The tool returns a structured API error object instead of failing silently. You check the response body directly; it will contain an explicit failure code (like 404) and details stating the resource was not found. **When I use `list_accounts` and have thousands of customers, how do I handle pagination to get all data?** The tool uses cursor-based pagination. To retrieve everything, you must pass the 'next page' or last returned ID/cursor from one response into the subsequent call until no further records are listed. **What is the technical difference between running `cancel_subscription` and using `reactivate_subscription`?** Cancellation immediately flags the account for termination, stopping future billing cycles. Reactivation reverses that status change, restoring active payment mandates and ensuring continuous service eligibility. **How do I find my Subdomain and API Key?** Your subdomain is the first part of your Recurly portal URL (e.g., if you log in at `myproject.recurly.com`, your subdomain is `myproject`). To get your API Key, navigate inside Recurly to Integrations > API Credentials and generate or copy your 'Private API Key'. **Can it accidentally charge my customers?** While the server can manage subscriptions (e.g., setting up a customer with a plan), it strictly follows the billing logic predefined in your Recurly catalog settings. It doesn't bypass credit card validation or execute arbitrary charges directly without a plan context. **Does cancelling a subscription remove the account entirely?** No, using `cancel_subscription` stops future renewals for that specific plan item instance. The underlying user billing account remains intact and can hold other valid subscriptions or past invoices.