MCP tools

Connect to https://regular-subs.fly.dev/mcp (Streamable HTTP) with an agent key; see Connect an agent. Changes go through plan_change and apply_plan with any command from Commands.

#What the server tells agents

Sent to every agent when it connects:

You are connected to Usual Subagent: the agent connection to a Shopify store's
subscriptions in Usual.

To look things up, use find_subscriptions (filters by status, product, customer, next
charge date) and get_subscription. Subscription data mirrors Shopify and is kept current
automatically; get_sync_status shows the last re-check.

How to make changes:
1. Call list_commands to see what you can do and each command's input schema.
2. Call plan_change with the command, its input and a short reason. Nothing changes yet.
3. Show the plan's diff to the user if they're present, then call apply_plan with the plan id.

Plans expire after 15 minutes and are refused if anything changed since they were made;
create a new plan if that happens. Riskier plans need a person to approve them in the
app. If plan_change returns status "awaiting_approval", tell the user and check back with
get_plan. Every change is recorded in list_activity and most can be undone with undo_change.

#Start here

#See how subscriptions are doing

get_overview · Read-only

Start here. Whether everything is working (Shopify updates, nightly re-check, billing), active subscribers, monthly recurring revenue, charges due in 7 days, payments retrying, new and cancelled in 30 days, and what's left to set up.

No input.

#Making changes

#List the changes you can make

list_commands · Read-only

Every change you're allowed to make, with a description, risk level, whether it can be undone, and the JSON schema of its input. Call this before plan_change.

No input.

#Preview a change

plan_change · Read-only

Preview a command without applying it. Returns a plan with a diff of exactly what would change, how many records it touches, and whether a person must approve it. Apply it with apply_plan. If nothing would change, returns status "noop".

#Apply a preview

apply_plan · Makes changes

Apply a plan from plan_change exactly as previewed. Refused if the plan expired, needs approval, or the store changed since it was made (then make a new plan).

#Check a preview

get_plan · Read-only

Current status of a plan, e.g. to see whether a person has approved it.

#See every change

list_activity · Read-only

Every applied change, newest first: who made it (person, integration or agent), why, what changed, and whether it can be undone. Use it to explain what happened.

#Undo a change

undo_change · Read-only

Reverse an earlier change from list_activity. Returns a plan to review and apply, like plan_change.

#Subscriptions

#Find subscriptions

find_subscriptions · Read-only

Search subscriptions, newest first. Combine filters, e.g. active subscriptions for a product charging next week. Returns lines, prices, schedule and status, plus total and nextCursor for paging.

#Look up a subscription

get_subscription · Read-only

One subscription in full, by our id or its Shopify contract GID.

#See a subscription's history

get_subscription_history · Read-only

What happened to one subscription, newest first: created, skips, reschedules, pauses, cancellations (with reason), charges and failed payments, and who did each (customer, merchant_user, agent, api_key, shopify, usual).

#Get a link for the customer to manage it

get_portal_link · Read-only

A link that opens one subscription in the store's customer portal, where the customer can skip, reschedule, pause, update their card or cancel themselves. view=cancel goes straight to cancelling (they still see the one offer for their reason). Safe to send: they log in first and only see their own subscriptions. Use it when a customer would rather do it themselves, or when you can't make the change for them.

#Cancellation offers

#Get the offer for a customer who wants to cancel

get_save_offer · Read-only

When a customer asks to cancel, ask why, then get the one offer that fits their reason (skip, deliver later, less often, pause, swap, or a discount the store allows). Share it once, in your words. If they take it, plan subscriptions.accept_save_offer; if not, plan subscriptions.cancel right away. Never make cancelling harder.

#See how cancellation offers are doing

get_retention · Read-only

Over the last N days (default 30): customers shown an offer, how many stayed, the save rate, monthly revenue kept, and saves and cancellations by reason and by offer.

#Offers

#List offers

list_offers · Read-only

Subscription offers shoppers can choose on product pages: name, delivery frequencies, discount and products. Change them with plan_change and the offers.* commands.

No input.

#Look up an offer

get_offer · Read-only

One offer, by our id or its Shopify selling plan group GID.

#Billing

#See how billing is going

get_billing_summary · Read-only

Charges and failures in the last 24 hours, charges waiting to retry or on the customer (3D Secure), subscriptions due in the next 7 days, and whether billing is paused.

No input.

#List charges and payment attempts

list_billing_cycles · Read-only

Each subscription charge (one per billing period) with its attempts and errors. Filter by state, e.g. retry_scheduled for failing payments, or by subscription. To retry one now, plan the billing.retry_now command (always needs a person's approval).

#Customer emails

#See which customer emails were sent

list_notifications · Read-only

Customer emails Usual sent, skipped or couldn't send (confirmation, renewal reminder, payment failed, cancellation), newest first, with the reason when one wasn't sent. Recipients are masked. Pass subscriptionId for one subscription.

#Imports

#List imports

list_imports · Read-only

Subscriptions brought in from another app (Recharge, Skio, Appstle...): each upload, its status (checking, ready, importing, imported, released) and how many are ready, need fixing, or were imported.

No input.

#Check an import

get_import · Read-only

One import: problems grouped by kind with example rows (fix them in the file and upload again), warnings, a preview of what will be created, failures, and how many are waiting to bill. Moving a store from Recharge: once the merchant has connected it (imports.connect, done in the admin), plan imports.fetch; otherwise plan imports.create with a CSV export. Wait for status ready, review this, plan imports.start, then imports.release_billing. For a connected import that switch cancels each one in Recharge quietly; for an upload, only run it once the old app has stopped charging.

#Store

#Check the last re-sync with Shopify

get_sync_status · Read-only

Recent re-checks of our subscription data against Shopify: when, how many checked, and how many were out of date. To start one, plan the subscriptions.reconcile command.

No input.

#Read store settings

get_settings · Read-only

Store-wide settings: sender name, support email, the failed-payment retry schedule, which customer emails are sent, and which cancellation offers customers see.

No input.