Use Charm from Claude and ChatGPT (MCP)

Charm ships an MCP (Model Context Protocol) server on top of the public API, so AI assistants like Claude and ChatGPT can read and act on your loyalty program — “how many points does jane@example.com have?”, “give her 500 bonus points”, “list rewards redeemed this week” — using the same guarded endpoints as the REST API.

Connect an assistant

• Endpoint: https://charm.appfleece.app/api/mcp (Streamable HTTP)
• Auth: a one-time connection code from the Charm admin, or a Charm API key from Settings → API, handed over once on Charm’s approval page or sent as a header, depending on the client.

Fastest: Set up in chat. In the Charm admin, open Set up in chat (on the home page, and offered in onboarding). It shows the endpoint and gives you a one-time connection code, valid for 15 minutes and good for one connection. Add the endpoint as a custom connector in claude.ai or ChatGPT; the assistant opens Charm’s approval page, you type the code, and the card shows the assistant as connected. No API key, and no need to ask us to enable the API: this connection is on for every store. Once the program is live, the card on the home page offers prompts for tuning it instead of building it. The merchant walkthrough is Set up in chat.

A code connection can read the shop, read and change the program (shop:read, program:read, program:write, analytics:read). It cannot see customer data or move points. It runs on a key Charm manages, listed in Settings → API as Chat assistant (Charm); revoking that key disconnects every assistant connected with a code.

Browser assistants with your own key (claude.ai, ChatGPT): when you want different scopes, for example read-only access for a support team, create a key in Settings → API and paste it on the approval page instead of a code. The connector then runs on short-lived tokens derived from that key. Connected assistants are listed under Settings → API → Connected assistants and in the Set up in chat card, where one click disconnects them.

Header-capable clients (Claude Code, IDEs, custom MCP clients): send the key yourself:

claude mcp add --transport http charm https://charm.appfleece.app/api/mcp --header "Authorization: Bearer chrm_live_..."

How it behaves

• Tools mirror the API. The public API’s endpoints are exposed as MCP tools, generated from the same registry — path, query, and body parameters flatten into one tool argument object, so the tools can never drift from the API. Minting a customer session token is the one thing left out: that is a storefront backend’s job, not a chat’s. tools/list leaves out the tools’ output schemas to stay small; each result’s structuredContent follows the endpoint’s response schema in the API reference.
• Annotated for the client. Reads (including the points estimates, which are POSTs that change nothing) are marked read-only; deletes are marked destructive, so a client can ask before running one. Every tool call shows up in Settings → API → Developer console as MCP mcp/<tool name>.
• Your key’s scopes are the assistant’s capabilities. A read-only key exposes only read tools; granting a write scope adds the matching mutation tools. Revoking the key cuts the assistant off entirely.
• Same guards as HTTP. Every tool call passes the same scope checks, rate limits, and idempotency handling as a direct API request. Mutations accept an optional idempotency_key argument; without one, each call is treated as a fresh “do this now” instruction.

Tip

Give an assistant the narrowest key that does the job — a read-only key is enough for reporting and support lookups, and it makes the assistant physically unable to change balances.

Changing the program from an assistant

With program:write on the key, the assistant can also tune the program: “add a 50-point rule for a product review with a photo”, “add a seasonal gift for 400 points until Christmas”, “raise Gold to 2 000 points and give it free shipping”. The tools follow the same rule-level endpoints as the API:

• charm_list_program_rule_types — the catalog behind the admin’s pickers: every earning rule, reward and tier benefit type with the fields it takes, their ranges, choices and defaults. The assistant reads this first, so it sends only what a type accepts.
• charm_create_earning_rule, charm_update_earning_rule, charm_delete_earning_rule, and the same three for rewards; charm_create_tier, charm_update_tier and charm_delete_tier; charm_update_program_settings (the program and points names, the expiry policies — nothing else).
• charm_list_program_changes and charm_undo_program_change — who changed what, in the admin or through the API, with the diff; one call puts a change back.

Three guards keep this safe:

• Dry run first. Every program write takes dry_run: true and answers with the exact diff and the one-line summary the admin shows, writing nothing. The server’s instructions tell the assistant to preview, show you, and only then repeat the call for real.
• No silent overwrites. Every write takes if_revision, the program’s revision the assistant last read. If you (or another assistant) changed the program meanwhile, the write is refused and the assistant re-reads. The admin’s own Save does the same check the other way round.
• Members are asked about. An assistant can add a VIP tier (charm_create_tier, at any position above the entry tier) or remove one (charm_delete_tier). While tiers are off nobody moves. While they are live, the dry run’s member_impact says how many members would move up, move down or be re-placed from a removed tier, and which gift codes promotions would issue; the real call is refused until it carries confirm_member_impact: true. Members of a removed tier are re-placed quietly: no “you reached a tier” email and no tier gifts.
• Deletes ask first. Removing an earning rule, reward, membership, partner group or campaign is refused until the call carries confirm_delete: true, so the assistant has to show you the dry run of what goes away and get your yes.
• The referral program in one place. charm_get_referral_program reads both sides’ rewards, the friend’s discount code and the code prefix; charm_update_referral_program changes any of them (“give referrers 750 points and friends 15 % off their first order over 40 €”). Live friend codes follow the new settings when it saves, and the change is logged and undoable like any other.
• Who earns, and which e-mails go out. charm_get_eligibility and charm_update_eligibility cover the customer audience (all, retail only, B2B only), excluded customer, order and product tags, excluded products, variants and collections, gift cards, discounted items, subscription renewals, membership purchases and the opt-in requirement. charm_list_email_templates shows every customer e-mail and whether it actually sends; charm_update_email_template switches one on or off, and its dry run says how many members have an address. Campaign e-mails are switched per campaign. charm_get_email_template_copy and charm_update_email_template_copy read and change an e-mail’s text, in the shop’s main language and its other languages; null puts Charm’s default line back, and text with a link is refused as in the editor.
• Paid memberships, ready for you to launch. charm_create_membership sets up a membership with its term or renewal cadence, grace period, extra points and benefits, sold through an existing product or a draft one Charm creates (unpublished, priced in the shop currency). It is created off sale; charm_update_membership_sale puts it on sale once its product is active (with your confirmation, see below). charm_update_membership changes it; once a membership has members, its billing and length stay as they were sold. charm_delete_membership removes one that is off sale and never had a member. A product that already sells a membership cannot sell a second.
• The partner programme. charm_get_affiliate_program_settings and charm_update_affiliate_program_settings cover the default commission on codes and links, the buyer discount (live partner codes that inherit it follow), what commission is calculated on, holdback, attribution window, code prefix, terms page and UTM tags. Partner groups with their own rates are charm_list_affiliate_groups and charm_create_affiliate_group, charm_update_affiliate_group, charm_delete_affiliate_group. Opening applications and approving partners stay in the admin.
• Paying partners. Charm never sends money. Once you have paid a partner yourself, tell the assistant: charm_list_due_partner_payouts shows who is owed what, and charm_record_partner_payout records the payment exactly as Record payment in the admin does, after you confirm the amount. The partner gets the usual confirmation e-mail unless you say not to.
• The switches, with your yes every time. charm_list_program_switches and charm_update_program_switch turn the program, VIP tiers, all customer e-mails or referrals on or off, and charm_update_membership_sale puts a membership on or off sale. Every real flip is refused until the call carries confirm_switch: true; the dry run and the refusal say what the switch does: for VIP tiers how many members land in each tier, how many gift codes are created and the most they can cost, for e-mails which ones start going out. The assistant is told to show you that and ask. Switching the partner programme on or off stays in the admin.
• The launch announcement. charm_get_launch_announcement and charm_send_launch_announcement send the one-off e-mail that tells your members the program is live, each with their own balance. It goes out once and cannot be taken back, so it needs confirm_send: true; charm_send_launch_announcement_test sends a test to the shop’s own address first. Members a welcome e-mail reached in the last 90 days are left out, and a shop can send it 7 days after installing Charm.

Bonus campaigns work the same way: “double points this weekend on the Summer collection” or “put the 10 % reward on sale for 300 points until Sunday” become charm_create_campaign, previewed with dry_run first. Two extra rules protect your customers’ inboxes and your margins:

• A campaign created by an assistant sends no email unless it switches an email phase on. The dry run’s would_email shows how many members an enabled phase would reach; the real call that enables one is refused until it carries confirm_email_impact: true, so the assistant shows you that number and asks first.
• A multiplier is capped at 10×, and only draft, ended or cancelled campaigns can be deleted — a running one is cancelled.

Titles in every language. Rules, rewards, tier names and benefit labels take per-language titles (title_translations, name_translations, label_translations). charm_list_program_rule_types tells the assistant which languages your shop publishes, so a Czech-and-Slovak shop gets both.

See what changed. Everything an assistant changes — and everything you change in the admin — is listed under Programs → Change history, with who did it and an Undo button.

Grant program:write only to an assistant you supervise: Settings → API warns before it lets you.

Related

• API overview — endpoints, scopes, keys, and rate limits
• Set up Shopify Flow triggers and actions