Developers POST api.motiverewards.com/v1/mcp Get started

Model Context Protocol

Run your org from your AI agent.

Motive speaks the open Model Context Protocol, so any MCP client (Claude Desktop or Code, Cursor, or your own agent) can create events, sell tickets, lay out vendor floors, manage your shop, and read live analytics in plain language. You connect once; your agent does the clicking.

◆

Everything runs through the same validated logic as the dashboard, scoped to your organization by API key. An agent-built event is identical to a hand-built one, with no shadow data and no drift.

Quickstart

Three steps, about two minutes. You'll need admin access to your Motive org.

1

Generate a connection key

In the dashboard, open Integrations and click Generate key. Copy it now; for security it's shown once. Keys look like mtvk_your_sample_key_123.

Generate your key

2

Point your MCP client at Motive

Every MCP client connects with the same two things: the endpoint https://api.motiverewards.com/v1/mcp and your key in an x-api-key header. For Claude Desktop, paste this into claude_desktop_config.json (on Mac: ~/Library/Application Support/Claude/) and restart the app.

claude_desktop_config.jsonjson
{
  "mcpServers": {
    "motive": {
      "url": "https://api.motiverewards.com/v1/mcp",
      "headers": { "x-api-key": "mtvk_your_key_here" }
    }
  }
}

The same URL and x-api-key header work in Claude Code (claude mcp add), Cursor, Windsurf, and any custom MCP agent. Once connected, motive shows up in your client's tools.

3

Ask it to do something

That's it. Try a real request:

you, to your agentprompt
Create a Saturday card show at the Brooklyn Expo next weekend.
Add $10 general admission and a $25 early-access tier, and set up
a 25-table vendor floor. Show me before you publish.

Connect a client

Claude Desktop uses the JSON above. Here are the other three ways to connect, depending on what your client can send.

Connect to a claude.ai session

A web claude.ai session cannot send custom headers, so the Motive connector uses OAuth instead of a pasted key. You approve access once from your Motive dashboard, and Claude stays connected. No key ever touches the browser.

1

Open the connector settings

In claude.ai, go to Settings then Connectors and click Add custom connector.

2

Paste the Motive endpoint

Enter https://api.motiverewards.com/v1/mcp as the connector URL and continue. Claude registers itself automatically and sends you to Motive to sign in.

3

Approve on Motive

Sign in to your Motive dashboard, pick the organization to connect (if you belong to more than one), and choose scopes. Read and write are selected by default. Check Allow irreversible actions only if your agent needs the dangerous tools.

4

Start working

Approve, and Claude returns to your session with Motive connected. The motive tools show up in your connector list, ready to use in plain language.

◆

The dangerous scope is off by default and can only be granted by an org owner or admin. Read and write cover most work, so leave the box unchecked unless your agent needs to refund, delete, publish, or blast.

Claude Code

Claude Code takes the endpoint and your key on the command line. One command adds Motive over the streamable HTTP transport with your key in an x-api-key header.

terminalbash
claude mcp add --transport http motive https://api.motiverewards.com/v1/mcp \
  --header "x-api-key: mtvk_your_key_here"

mcp-remote

Some clients accept only a URL with no header field but still run the connection locally. For those, mcp-remote bridges the URL to Motive and attaches your key on your machine.

terminalbash
npx mcp-remote https://api.motiverewards.com/v1/mcp \
  --header "x-api-key: mtvk_your_key_here"
◆

This is a local process, not a web session. mcp-remote runs on your machine and forwards your x-api-key for you, so it is functionally the same as the Claude Code and Desktop header path. A pure browser-only claude.ai session must use the OAuth connector above.

Authentication

Every request carries your organization's key in an x-api-key header. The key is the org scope: a key can only ever touch its own organization's data. Generating a key needs an owner or admin. Keys are minted with read and write scopes by default (Read and draft); irreversible actions additionally require a key explicitly granted the dangerous scope. To get one, an owner chooses Full access when generating the key under Integrations → Claude → Developers in the dashboard (or on the API Keys page, where your workspace shows it). Only an owner can create Full access, because such a key acts with owner rank, including changing roles and removing members. A key's scopes are fixed when it is generated, so a Read and draft key never gains them: generate a new one and revoke the old. Keys are hashed at rest and shown exactly once at creation.

verify your connectioncurl
curl -X POST https://api.motiverewards.com/v1/mcp \
  -H 'x-api-key: mtvk_your_key_here' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Revoke a key anytime from the dashboard, and it stops working immediately. Rotate freely; an org can hold several keys.

Tools

230 tools across your whole org, grouped by what they touch. READ tools answer questions; WRITE tools change data; CONFIRM tools are irreversible or high-impact (refunds, deletes, publishes, blasts, role changes) and need a key with the dangerous scope plus a two-step confirm: the agent calls once to preview the exact impact, then again with confirm: true to actually run it.

◆

You will not see all 230 in tools/list. Loading every definition on every request costs your agent roughly 26,000 tokens before it does any work, so Motive serves a small always-loaded core plus two meta-tools, and your agent fetches the rest on demand.

find_tools — describe the capability you need in plain words (“cancel a published event”, not a guessed tool name) and get back matching tools with their parameters. It never returns nothing: if there is no strong match you get the closest candidates, so an agent can see what does exist rather than concluding a capability is missing.

call_tool — invoke any tool in the table below by name, including ones not loaded up front. The tool’s own parameters go inside an arguments object, not at the top level: call_tool({ name: "cancel_event", arguments: { eventId: "...", confirm: true } })

Every rule still applies through call_tool: CONFIRM tools return their preview first, scope checks still refuse, and the audit log records the real tool name. It is a router, not a bypass. The table below is the complete catalogue reachable this way — not what you will see listed on connect.

ToolTypeWhat it does
Events
create_eventWRITECreate an event: date, venue, capacity, visibility, and an optional Spotify playlist, album or song link. Returns a draft with its public URL.
update_eventWRITEEdit an existing event's details, including its Spotify link (pass an empty spotifyUrl to remove it). Adding a link needs Spotify connected first (set_spotify_integration or the dashboard's Integrations tab).
publish_eventCONFIRMTake a draft event live and shareable publicly.
cancel_eventCONFIRMCancel a published event. It stays in the system as cancelled and its RSVPs, orders and tickets are preserved. Does not refund anyone.
delete_eventCONFIRMPermanently delete an event. Refused if it has any tickets sold, RSVPs, or check-ins — cancel it instead.
get_event_detailsREADFull configuration and analytics for one event, including whether the org has connected Spotify.
list_eventsREADYour org's events, filterable by upcoming, past, or live. Capped at 50 per call; page with offset.
get_event_analyticsREADRSVPs, check-ins, ticket revenue, per-tier breakdown, and Soundtrack plays.
get_event_revenue_summaryREADGross revenue, orders, and tickets sold for an event.
Event photo albums
The photos guests and hosts add to an event after it starts. Rolled out per organization: until albums are turned on for yours, these answer not found. Hosts only (moderators and above).
get_event_albumREADAn event album’s settings (who can see it, who can add photos, open or closed), its visible, hidden and removed photo counts, and the organization’s album storage used against its limit.
list_event_album_photosREADThe album’s photos as hosts see them, newest first, including ones hidden by moderation and their open report counts; filter to removed to find one to restore. Capped at 50 per call; page with offset.
update_event_album_settingsWRITEChange who can see the album, who can add photos, and whether it takes new ones. Closing an album deletes nothing.
add_event_album_photoWRITEAdd one photo (base64 bytes or an http(s) URL) as the person behind the connection, through the same path as an app upload: the same limits, location data stripped, and an activity-feed entry. JPEG, PNG or WebP.
remove_event_album_photoWRITETake a photo out of the album and the activity feed. Kept for 30 days so it can be restored.
restore_event_album_photoWRITEPut back a photo a host removed, within 30 days. Refused for a photo its uploader removed or moderation removed.
Luma distribution
get_luma_sync_statusREADWhether a Luma calendar is connected, and per event: the lu.ma URL, sync state, last sync, and guests plus revenue that arrived via Luma. Call it with no eventId for the org-wide summary.
publish_event_to_lumaCONFIRMList an already-published Motive event on the org's connected Luma calendar as a public lu.ma page; registrations there sync back as RSVPs. A draft or cancelled event is refused. Re-running it re-syncs rather than listing twice, and never notifies Luma guests.
cancel_luma_publishCONFIRMPull an event's Luma listing. The Motive event is untouched; Luma notifies its own registrants. A paid listing needs refundLumaGuests before Luma will cancel it.
Tickets & orders
add_ticket_typesWRITEAdd ticket tiers to an event: name, price, quantity. Appends by default; pass mode: "replace" to delete the existing lineup and start over.
update_ticket_typeWRITEEdit one ticket tier in place.
remove_ticket_typeCONFIRMPermanently remove one ticket tier from an event.
get_ticket_availabilityREADPer-tier price and how many tickets remain.
list_ordersREADTicket orders for an event, newest first.
get_orderREADFull detail for one ticket order.
refund_orderCONFIRMIssue a Stripe refund for a ticket order.
RSVPs & check-ins
approve_rsvpWRITEApprove one pending RSVP and admit the applicant.
deny_rsvpCONFIRMDeny one pending RSVP, rejecting the applicant.
review_pending_rsvpsREADSuggest approvals for pending RSVPs without changing anything.
list_attendeesREADAn event's attendees with names and RSVP status. Capped at 50 per call; page with offset.
list_check_insREADEveryone who has checked in, plus the total.
invite_to_eventCONFIRMInvite all members or a chosen list to an event.
Vendor floor
configure_vendor_tablesWRITEBuild a full vendor floor: tiers, pricing, and grid map.
list_vendor_tablesREADList vendor tables for one event or all.
create_vendor_tableWRITECreate a single vendor table for an event.
bulk_create_vendor_tablesWRITECreate many identical vendor tables at once.
update_vendor_tableWRITEUpdate one table's name, price, status, or tiers.
delete_vendor_tableCONFIRMPermanently delete a single vendor table.
clear_table_positionWRITEUnplace a table from the floor map, keeping the table.
update_table_positionWRITEMove a single table to a new grid cell.
get_vendor_availabilityREADOpen versus reserved tables by type.
get_vendor_table_settingsREADWhether vendor sales are enabled and how they behave.
update_vendor_table_settingsWRITEToggle vendor sales and related settings for an event.
list_table_typesREADThe table tiers configured for an event.
create_table_typeWRITECreate a single vendor table tier.
update_table_typeWRITEEdit a table tier's name, price, or color.
delete_table_typeCONFIRMPermanently delete a table tier.
get_vendor_analyticsREADVendor order counts and revenue for an event.
Vendor orders & vendors
list_vendor_ordersREADVendor table orders for one event or all.
refund_vendor_orderCONFIRMRefund a completed vendor table order in full.
approve_or_deny_vendor_orderCONFIRMApprove or deny a pending vendor order; notifies the vendor.
list_vendor_waitlistREADPeople waiting for a table to open up.
list_vendor_profilesREADCross-event vendor identities for the organization.
get_vendor_profileREADOne vendor's profile plus their recent orders.
Vendor-booth discounts & add-ons
list_discount_codesREADVendor-table discount codes for an event.
create_discount_codeWRITECreate a percentage-off vendor-table discount code.
update_discount_codeWRITEToggle, re-cap, or edit a discount code.
delete_discount_codeCONFIRMPermanently delete a vendor-table discount code.
list_add_onsREADVendor-table add-ons offered for an event.
create_add_onWRITECreate an optional vendor-table add-on.
update_add_onWRITEEdit an add-on's name, price, or inventory.
delete_add_onCONFIRMPermanently delete a vendor-table add-on.
Vendor messaging
send_vendor_messageCONFIRMEmail a blast to an event's vendors.
list_vendor_messagesREADVendor message blasts already sent for an event.
Shop products
list_shop_couponsREADCoupon / promo codes for shop products.
create_shop_couponWRITECreate a shop coupon — fixed dollar or percent off, optionally scoped to products and gated on a minimum quantity.
update_shop_couponWRITEToggle, re-scope, or edit a shop coupon.
delete_shop_couponCONFIRMPermanently delete a shop coupon.
create_productWRITECreate a shop product, always as a draft.
publish_productWRITEPublish a draft product so it becomes purchasable.
list_productsREADThe organization's shop products with status.
get_productREADOne product's details, images, variants, and stock.
update_productWRITEEdit a product's name, images (add or replace), or fulfillment.
unpublish_productWRITETake a product off sale by reverting it to draft.
archive_productWRITERemove a product from the active catalog.
add_product_variantWRITEAdd a size or color variant with its own price.
update_product_variantWRITEEdit a variant's size, color, price, or stock.
remove_product_variantCONFIRMPermanently remove a single variant from a product.
list_stock_notificationsREADBuyers waiting on a sold-out variant to come back — who, which size, and since when. They are emailed automatically on restock.
Shop orders
list_shop_ordersREADShop orders (merch purchases), newest first.
get_shop_orderREADOne shop order's status, fulfillment, and customer.
update_shop_order_fulfillmentWRITESet fulfillment status or attach shipping tracking.
refund_shop_orderCONFIRMIssue a full Stripe refund for a shop order.
Members
list_org_membersREADLook up members by name or email.
get_member_detailsREADOne member's profile plus their event activity.
get_members_listREADMembers with join date, points, and opt-outs.
get_member_growthREADMember-growth time series over a range.
get_member_countREADTotal active members, a fast headline number.
get_team_membersREADStaff (owner, admins, moderators) with their roles.
get_onboarding_statusREADThe org's setup and onboarding checklist state.
remove_memberCONFIRMRemove a member from the organization (soft delete).
invite_org_membersCONFIRMEmail people the org's public join link.
Communications
preview_member_blastREADPreview an org-wide member SMS without sending.
list_blast_membersREADMembers with per-person SMS-blast eligibility flags.
get_member_blast_historyREADHistory of org-wide member SMS blasts.
send_org_member_blastCONFIRMText and email every eligible active org member. Reports each channel separately — a send can be partial.
preview_event_blastREADPreview an event SMS without sending.
get_event_blast_historyREADHistory of SMS blasts for one event.
get_event_blast_statsREADDelivery stats for one specific event blast.
send_event_blastCONFIRMText and email an event's going and maybe attendees. Reports each channel separately — a send can be partial.
preview_event_announcementREADWho an announcement about an upcoming event would reach, built from the attendees of past events — guests and walk-ins with no Motive account included. Counts only — no recipient names or addresses are returned — and it sends nothing.
send_event_announcementCONFIRMEmail an upcoming event to the people who came to past ones, guests and walk-ins included. Email only — nobody is texted — and limited to one announcement per org per 24 hours.
list_notificationsREADOrg activity log — the notifications Motive sent your staff (orders, payouts, vendor bookings, new members), one row per occurrence with its delivery status. Org-level only; never an individual member's personal notifications.
Host announcements
Posts from the Announcements page: a short message to every member, or to one event’s guests, with a bell notification for every account holder plus app push, text or email as picked (an event’s guests without an account get the email only). Each call is made as the person behind the connection, so the page’s own rules apply: moderators and above, or a listed host for their own event. While announcements are switched off on Motive, all four answer that they are off to any key allowed to call them.
preview_host_announcementREADWho a post would reach before it is sent: how many account holders get the bell notification, and how many each of app push, text and email would reach, guests without an account included in email. Counts only, and it sends nothing.
list_host_announcementsREADThe organization’s posts, newest first, with each one’s channels, status, reach, image and link card. Filter by event or scope; page with offset.
list_host_announcement_audiencesREADThe membership plans a post to plan members can go to, each with its price and how many people have access to it now. Moderators and above.
send_host_announcementCONFIRMPost a message to the community, to an event’s guests or to the members of one or more plans (by id or name), now or at a set time, on the channels you pick, optionally with one image or GIF and one link card to a product, event, membership plan, course or bookable service. The preview shows the audience, per-channel counts, the image and the link card; a push, text or email cannot be unsent.
update_host_announcementCONFIRMFix the text of a sent post (not its image or link). The preview shows the post, its current text and the new text. The page and bell text change; app push, text and email already delivered stay as sent, and nobody is notified again.
delete_host_announcementCONFIRMDelete a post: it leaves the history and the event page and its bell notifications are reworded. Messages already delivered are not recalled.
Team & roles
assign_roleCONFIRMGive a member a team role or invite staff.
revoke_roleCONFIRMRevoke a staff role, demoting to regular member.
list_pending_invitesREADPending, not-yet-accepted team invites.
resend_inviteWRITEResend a team invite and reset its expiry.
cancel_inviteWRITECancel a pending team invite.
Organization
update_organizationWRITEEdit org profile, branding, privacy, and policies.
publish_organizationCONFIRMPublish the org and make its public surfaces live.
set_shop_statusWRITESet shop status: disabled, draft, or published.
set_shop_integrationWRITEEnable or disable the shop feature.
update_shop_settingsWRITESet the org's default shipping price, free-shipping quantity, processing-time windows, and backorder policy.
set_vendor_tables_statusWRITEEnable or disable the vendor-tables feature.
set_spotify_integrationWRITEConnect or disconnect Spotify, which event Soundtrack links need. Disconnecting hides the players but keeps every link.
set_developer_integrationWRITEEnable or disable the developer-integration feature.
get_checkout_linkREADThe full-page checkout link for one product, membership plan, bookable service or paid event, to put on your own website. When the item cannot be paid for through a link, it says why.
get_policy_versionsREADVersion history of a single org policy.
get_policy_audit_logREADWho created, updated, or published a policy.
get_policy_acceptance_statusREADWhere each member stands on a given policy.
Custom domains
add_custom_domainWRITERegister a custom domain for the org's public pages.
verify_custom_domainWRITEVerify a pending domain by checking its DNS.
list_custom_domainsREADCustom domains with verification status and DNS records.
delete_custom_domainCONFIRMRemove a custom domain and de-register it from Vercel.
Website (Motive Sites)
generate_siteWRITEStart here: generate 1-3 complete site designs from the org's real data and logo colours, each checked and repaired. Stored as candidates; never saved to the draft or published.
apply_site_variantWRITECopy one generated variant into the draft, all-or-none and revision-guarded. Does not publish.
get_site_blueprintREADWhich capabilities are live, the sections the page must contain, the brand colour and logo-derived brand kit, presets, font pairs, and data warnings.
list_site_sectionsREADThe section library: hero, events, shop, membership, book, text, FAQ, call to action, custom sections composed from blocks (heading, text, image, button, gallery, quote, stats, spacer, video, divider), policies, with their settings and limits; plus the surfaces (event, product, checkout, sign-in, account, receipt) and their settings.
get_siteREADThe site document (draft, else live, else a generated starting draft).
edit_siteWRITEChange the draft with operations (add/move/update/remove sections and blocks, set the theme, configure a surface), applied all-or-none.
check_siteREADCoverage, contrast, security and content findings, each with the edit that fixes it, plus the draft's preview status and visual findings. Blocking findings stop a publish.
preview_siteREADSee the unpublished draft: a private 1-hour preview link, screenshots at 390, 820 and 1440 px, and visual checks on the rendered page (overflow, clipped text, broken images, empty sections, contrast, page weight). Required before every publish.
publish_siteCONFIRMMake the draft the org's live public page. Refuses until the current draft has been previewed with no blocking visual finding.
rollback_siteCONFIRMMake an earlier published site version live again.
upload_site_imageWRITEAdd a photo (https link, attachment or file) to the org's site image library; returns the asset id the site's image settings take.
list_site_imagesREADThe images the site can show, by asset id: the site image library plus the org's logo, cover, product and event photos.
request_site_integrationWRITELog something the site cannot do yet (an embed, other languages, pick-your-amount donations, extra pages, members-only areas, forms, live data) as a counted integration request, and get the closest thing that works today to offer instead. Changes nothing on the site.
API keys
get_connection_infoREADWhich org this connection is bound to, its scopes, and whether the dangerous scope is granted. Call it first when anything looks wrong.
list_api_keysREADActive API keys, masked, with last-used info and each key's scopes, including whether it holds dangerous.
revoke_api_keyCONFIRMRevoke an API key; integrations using it stop working.
Billing
get_subscriptionREADCurrent plan tier, status, and billing period.
list_invoicesREADBilling invoices, newest period first.
get_upcoming_invoiceREADPreview the not-yet-issued invoice for this period.
get_invoiceREADFull detail for a single invoice.
get_invoice_pdf_urlREADA downloadable URL for an invoice PDF.
get_invoice_receiptREADA structured receipt for an invoice.
get_current_usageREADThis month's usage across all metered channels.
get_payment_methodREADThe default payment method, masked.
get_billing_audit_logREADChronological record of billing changes.
Member subscriptions
Recurring dues your members pay you — not the Billing rows above, which are what your org pays Motive. Rolled out per organization: until member subscriptions are turned on for yours, these twenty-five answer not found.
list_membership_plansREADYour recurring-dues plans, newest first, every status (draft, published, archived) with each plan's active price in cents. Capped at 50 per call; page with offset.
get_membership_planREADOne dues plan in full: interval, perks and entitlement keys, trial, term, seats, pause and proration policy, its Stripe product once published, the active price, every way to pay (main price first) and which one buyers see pre-selected, members on a live subscription, old slugs from a rename, and its checkout and page links with whether buyers can use them yet.
get_membership_analyticsREADHow your dues plans are doing: active members, monthly recurring run rate in cents, churn and collections over a window, and per plan a count of members in each subscription status. Pass a plan id for one plan’s numbers.
list_membership_discount_codesREADDiscount codes for your membership plans: percent or fixed amount off, for the first payment, every payment or a number of months, with plan scope, redemption cap, uses and expiry.
create_membership_discount_codeWRITECreate a membership discount code. Buyers type it at the subscription checkout; it discounts the dues (never the joining fee) for its duration. The amount and duration cannot be edited later.
update_membership_discount_codeWRITESwitch a membership discount code on or off, or change its plans, redemption cap or expiry.
delete_membership_discount_codeCONFIRMPermanently delete a membership discount code. Members already using it keep their discount.
list_membership_plan_pricesREADA plan's price version history, newest version first — repricing mints a new version rather than editing the old one. Not a member's payment history.
list_member_subscriptionsREADWho is actually paying you: subscribers with their plan, what they pay each period in cents, and their state (active, trialing, past_due, paused, unpaid, canceled). Filter by planId or status. Default 50 per call, ceiling 200; page with offset. Not the free member roster — that is get_members_list.
get_member_subscriptionREADOne subscriber in full, including the dunning picture on a failed payment: attempt count, decline code, and a stripeWillRetry flag. When it is false Stripe has stopped retrying and the member must fix their card. Not get_subscription, which is your org's own Motive plan.
list_member_invoicesREADOne subscriber's dues invoices, newest first: what each period charged, whether it was paid, what was already refunded and what can still be refunded (refundableCents). The 50 newest, as in the dashboard. Not list_invoices, which is what your org pays Motive.
cancel_member_subscriptionWRITECancel one member at the END of the current period: they keep what they paid for, then are not charged again. No refund.
comp_member_subscriptionWRITEWaive one member's dues (the membership keeps renewing at $0), or remove the comp with comped: false. Refunds nothing already paid.
suspend_member_benefitsWRITEPause one member's benefits until a date while billing continues — a club closed for the season. Touches no payment.
restore_member_benefitsWRITEGive a paused member their benefits back now. Billing was never stopped.
cancel_member_subscription_nowCONFIRMEnd one member's subscription immediately: access stops now and cannot be restarted. Issues no refund for the rest of the period — that is refund_member_invoice.
refund_member_invoiceCONFIRMRefund a member's paid dues invoice to their card, in full (omit the amount) or in part, in cents. The preview shows the stored balance. Spends the same hourly refund cap as order refunds. Does not cancel the membership.
write_off_member_invoiceCONFIRMMark an invoiced member's unpaid invoice uncollectible, for good. Invoiced memberships only — a card membership that cannot be collected ends on its own. Refunds and cancels nothing.
create_membership_planWRITECreate a recurring dues plan — the paid tier itself, not a subscriber. Always a DRAFT: it creates nothing in Stripe and nobody can subscribe until it is published. Prices are in cents.
update_membership_planWRITEEdit an existing dues plan. Not the price (that mints a version), not the status, and not the billing shape or early-termination fee of a published plan. entitlementKeys and perks REPLACE the stored list rather than merging into it. A rename moves the plan’s slug and keeps the old one in previousSlugs. defaultOptionKey picks the way to pay buyers see pre-selected, on any plan, live included.
get_membership_upgradesREADWhich of the org’s other plans a member on one plan is offered as an upgrade (e.g. Collector → Grader), with each target’s status and pitch. Only published targets are shown to members.
set_membership_upgradesWRITELink a plan to the plans its members are offered as an upgrade, with an optional one-line pitch; [] clears. Replaces the list. Configuration only — members confirm and pay the prorated difference themselves.
set_membership_plan_priceWRITEChange what a plan costs by minting a NEW immutable price version. Existing subscribers stay pinned to the version they agreed to. On a published plan this creates a real Stripe Price.
set_membership_option_priceWRITEAdd or re-price an extra way to pay on a plan — every month, 3 months, 6 months or year (month_1, month_3, month_6, year_1) — at least 100 cents. Not the main price, which stays the buyer’s default. Members already on the option keep their price. On a published plan this creates a real Stripe Price.
remove_membership_optionWRITEStop offering one extra way to pay so new buyers cannot pick it. Members already on it keep renewing at their price; nothing is cancelled or refunded. The main price cannot be removed.
publish_membership_planCONFIRMTake a dues plan live so members can subscribe and be charged. Creates a real Stripe product and price, and a Stripe product cannot be deleted once used — only archived. Refused if the plan has no price or if it is archived. If your dues storefront is still a draft, it goes live with the plan. Motive collects the dues and pays them out with your regular payouts.
unpublish_membership_planWRITETake a live tier off the storefront so nobody new can subscribe. Returns it to DRAFT and touches nothing in Stripe: existing subscribers keep renewing at the price they agreed to and keep their entitlements. Cancels nothing and refunds nobody. Only publish_membership_plan puts it back, and that needs the dangerous scope.
archive_membership_planWRITERetire a tier the org no longer offers. A status change, never a delete — every subscription points at the plan for the life of the agreement. Refused while any member still has a live subscription on the plan; unpublish it instead.
restore_membership_planWRITEUn-archive a retired tier. It comes back as a DRAFT, never straight back to published. publish_membership_plan is what makes it sellable again.
set_membership_statusWRITEThe org-level switch: draft arms memberships for authoring with the storefront dark, disabled turns the surface off. Deliberately unguarded on the way down, and it cancels, refunds and revokes nothing. It cannot reach live — that is take_memberships_live.
take_memberships_liveCONFIRMTakes the whole dues storefront live, so published plans become publicly purchasable and cards are charged on a recurring schedule. Refused unless at least one plan is published. Usually not needed: publish_membership_plan takes a draft storefront live with the plan. Use this after the storefront was set back to draft.
Bookings
A service sold on a date the customer proposes — a coffee cart, a catering package — priced from the seller's own rules. Rolled out per organization: until bookings are turned on for yours (pause_bookings with draft does that, once bookings are on for the platform), these answer not available — except refund_booking_payment, settle_booking_refund and accept_booking, which are never switched off, so money a customer already paid can be given back and a card already held can still be charged. They need the booking and payment ids, which the booking reads do not return while bookings are off, so keep them from the refund you are finishing or from the seller’s dashboard.
pause_bookingsWRITEThe organization’s own bookings switch, short of going live. draft takes a live booking page off the air (no new requests, and a customer holding a price cannot pay until it goes live again), and on an organization whose bookings are off it is what switches them on so services can be authored. disabled switches bookings off: every bookings tool except the two refund tools answers not available. Cancels, refunds and emails nobody; every booking keeps its date. Deliberately unguarded, so a broken page can always come down.
take_bookings_liveCONFIRMPublish the organization’s booking page, which opens every published bookable service on it to the public at once, not just the one being discussed. The preview names each service that goes live and how many of them a customer can book and pay for with no seller review. Refused unless bookings are on for the platform, the organization is public and at least one service is published. Reports storefront: whether a customer can actually open the page, and if not, why. Not publish_bookable_service, which publishes one service. Refused from the dashboard’s Ask Motive chat. Reversible with pause_bookings.
preview_booking_quoteREADPrice a booking before anybody commits — give it a bookable and, if the seller charges per unit, how many. Returns the quote line by line in cents (base or per-unit charge, minimum-spend top-up, add-ons, travel, tax) plus the deposit due now and the balance due later; while the storefront checkout is on, a customer who books there pays the whole total. Creates no booking, holds no date and takes no money.
get_booking_availabilityREADWhich days a bookable can be booked on, one row per day, plus the window the seller accepts (their notice period and horizon). Says why a day is closed — blacked out, or already held. Reserves nothing. Default 50 days per call, ceiling 500; page with offset. Not get_vendor_availability or get_ticket_availability, which count inventory at an event.
list_bookable_servicesREADThe seller’s bookable services — the coffee cart, the catering package, the studio hour — with name, status, slug, timezone and pricing model. Lists every status including draft and archived, and returns the status per row. Also reports storefront: whether the public booking page actually renders, and if not, why. Default 50 per call, ceiling 500; page with offset.
get_bookable_serviceREADOne bookable service in full — description, status, timezone, approval requirement, the whole pricing spec (base or per-unit rate, minimum spend, add-ons, travel zones, tax, deposit) and the intake-form questions. Readable in every status. Returns the offer, not its calendar: use get_booking_availability for days and preview_booking_quote for a price.
list_bookingsREADBooking requests customers have made — who asked, which service, which date, how many units, status and money — newest requested date first, filterable by status. Carries customer details. Pages by cursor, not offset: returns nextCursor and deliberately no total and no offset. Default 50, maximum 100.
get_bookingREADOne booking in full for the seller who owns it — customer name, email and phone, service and date, units, the quote line by line, deposit and balance, payment legs, and every intake-form answer. The answers are here and not on list_bookings on purpose. Not get_booking_availability.
create_bookable_serviceWRITECreate the thing a seller offers on a date the customer proposes — a coffee cart, a catering package — with its price, options, travel zones, deposit and booking window. Always created as a DRAFT: invisible to customers, not on the storefront, not bookable. Prices in cents; the currency comes from the org and cannot be changed later. Not create_product (a shop item), create_event (a dated happening with tickets) or create_add_on (a vendor-booth extra) — this service’s own extras are the addOns inside its pricing.
update_bookable_serviceWRITEEdit a service’s name, copy, price, options, booking window, intake questions and approval setting. pricing MERGES field by field: send only what changes and everything you leave out is kept, so a partial edit cannot silently delete an option group, a tax rate or a deposit. Supplying optionGroups replaces the whole list of option groups (add-ons, a travel area, anything else the customer chooses), because an element has no id to merge on. availability merges the same way and cannot write blocked days — that is set_bookable_service_blackout_dates alone. Reports storefront, because this is the tool that changes what a customer is charged. An archived service must be restored before it can be edited, and the timezone is fixed once a service leaves draft.
set_bookable_service_blackout_datesWRITEClose or re-open days on one service’s calendar. A DELTA, not a replacement: name only the days that change, so two edits cannot undo each other. Cancels nothing — a booking already on that day keeps it, and the block only stops new requests. Days are YYYY-MM-DD in the service’s own timezone. The only tool that writes blocked days.
unpublish_bookable_serviceWRITETake a service off the storefront and back to draft. New customers cannot find or book it; every existing booking keeps its date, and nobody is cancelled, refunded or notified. Reports whether the org’s booking page is still live afterwards, which is a separate question. Reversible by publishing again.
archive_bookable_serviceWRITERetire a service the seller no longer offers. It leaves the storefront, stops being bookable and becomes uneditable — but is never deleted, because every booking made against it points at this record. Reversible with restore_bookable_service. Cancels no booking and refunds nobody. Use unpublish_bookable_service instead if the seller may sell it again soon.
restore_bookable_serviceWRITEBring an archived service back as a DRAFT — editable again, and deliberately NOT back on the storefront, so a price that stopped working while it sat archived cannot go live unexamined. Publishing it is a separate step.
publish_bookable_serviceCONFIRMTake a bookable service live so customers can find it on the org’s booking page and request dates. The only move that puts an offering customers pay for in front of the public. Publishing a service does not by itself make the booking page visible — the org’s own booking status is a second switch — so the response reports storefront: whether a customer would see it, and if not, why. Refuses a service whose pricing cannot produce a quote, and an archived one. Reversible with unpublish_bookable_service; charges and notifies nobody.
delete_bookable_serviceCONFIRMPermanently delete a draft bookable service that nobody has booked. The record is removed, not archived, and nothing brings it back — prefer archive_bookable_service, which retires a service, keeps its bookings resolving and is reversible. The server refuses a published service (unpublish or archive it first), an archived one (restore it first), and any service a booking of any status points at.
create_bookingWRITEType in a booking the seller already took elsewhere — the one that arrived by DM or by phone. Creates ONE customer’s booking against a service. When it is priced on the spot it emails the customer their price and the link to their own booking page; a hand-priced request, or a date the seller’s calendar refuses, emails nobody. The price is always computed from the service’s own rates; there is no field for a total. Works against a DRAFT service, because the seller answering a DM has not necessarily published their page. Not create_bookable_service, which creates the offering itself. Read status: declined is a successful write meaning the seller’s own calendar refused that day.
release_booking_quoteWRITESend the customer their price, or change one already sent. Emails them the price and a link to pay. Every field is an INPUT to the seller’s own pricing (units and the chosen options) — the total, tax and deposit are always the engine’s. Sending selectedOptions replaces the customer’s whole selection. A booking whose date is held stays held. Not preview_booking_quote, which computes a price and tells nobody.
decline_bookingWRITETurn down a booking request, in the seller’s own words, and email the customer that reason verbatim. Deletes nothing: the row stays as declined, because a date the seller could not work is demand data. FINAL — a declined booking never moves again; the way back is a new create_booking. Use before the customer has paid; a confirmed booking is refused.
hold_booking_dateWRITEPromise a date to a customer who has not paid — takes that day off the seller’s public calendar through the last day you name, inclusive, in the service’s timezone. Emails nobody. expectedHeldThroughDateKey is required and is the hold you last read (or null): the server refuses the write if somebody changed it underneath you. Refused while the booking is being paid for, on an archived service, or when another booking already holds the day.
release_booking_holdWRITEGive a held date back without turning the customer away. The day returns to the public calendar and the customer’s price still stands, so they can still pay. Emails nobody. Takes the same required expectedHeldThroughDateKey. Not decline_booking, which is final.
fulfill_bookingWRITEMark a confirmed booking done — the seller’s own bookkeeping. Emails nobody, moves no money and pays nobody out. Only on or after the booking’s own date, and only for a booking whose payment has settled. Terminal: a fulfilled booking never moves again, and it keeps its date held rather than reopening it.
accept_bookingCONFIRMAccept a booking whose customer's card is held for the seller's review, and charge the card: the whole hold, or less, never more, in cents. The booking is confirmed and the customer is emailed; anything not charged is released. A hold not accepted within 6 days is released on its own, and decline_booking turns the customer down and releases it uncharged. Rate-capped per organization. Refused from the dashboard’s Ask Motive chat.
cancel_bookingCONFIRMCall off a confirmed (paid) booking the seller can no longer work. Cancelling is not refunding: it moves no money and what the customer paid stays with the business until refund_booking_payment is called, so refund first when the seller means to. Emails the customer that it was cancelled, naming any refund already made. Cannot be undone — the booking never moves again and its date reopens to other customers. The preview lists every payment still held. Rate-capped per organization. Refused from the dashboard’s Ask Motive chat.
refund_booking_paymentCONFIRMGive back what a customer paid for a booking, in whole or in part, in cents. Requires a requestId, a v4 UUID the agent generates once per refund and resends unchanged on the confirm call and every retry, because the payment provider de-duplicates on it; the server never mints one. Every refusal says whether money moved and what to do next. BOOKING_REFUND_OUTCOME_UNKNOWN means resend the same id, and BOOKING_REFUND_PROVIDER_REFUSED means nothing went back and a new refund needs a new id. Shares a per-organization refund cap with refund_order and refund_shop_order. Does not cancel the booking and emails nobody. Refused from the dashboard’s Ask Motive chat.
settle_booking_refundWRITECheck a booking refund whose outcome is unknown: asks the payment provider what became of it and updates the booking to match. Never sends a refund and never claims one, so it takes no requestId, is safe to call again and is not rate-capped. Answers refunded, not_refunded, still_in_progress or nothing_to_check. Refused from the dashboard’s Ask Motive chat, like the refund it checks.
Courses
Online courses of video and text lessons, sold or given away on the organization’s course page. Rolled out per organization: until courses are turned on for yours (from the dashboard; no tool here does it), these answer not available. Every course tool needs the admin role. A published course is visible only while the organization’s courses page is live, so the course tools report storefront: whether a customer can open the course page, and if not, why.
list_coursesREADYour online courses, one row each: title, status (draft, published or archived), who may watch (free, members or paid), price in cents, chapter and lesson counts, and how many lessons customers can actually see. Reports storefront: whether a customer can open that course page right now, and if not, why, with its public link. Default 50 per call, ceiling 500; page with offset.
get_courseREADOne course in full: title, summary, cover, access, price, storefront, and the whole outline with every chapter and lesson id, each lesson’s kind, free-preview flag, video link-check result and whether customers can see it. Long text bodies are cut and say so. Read it before reorder_course_outline.
create_courseWRITECreate a course with its title, summary, cover, access and (for a paid course) a one-time price in cents. Always a DRAFT no customer can see; chapters and lessons are added next. The currency is the organization’s. A cover URL is re-hosted on Motive storage. Recurring pricing (a subscription) is not available yet.
update_courseWRITEEdit a course’s title, summary, cover, access or price (recurring pricing is not available yet). Send only what changes. Moving to free or members clears the price; moving to paid needs one. On a published course customers see the change at once. Reports storefront.
publish_courseCONFIRMPublish a course so it appears on the course page and customers can enroll or buy it. The preview is built from the stored course: access, price, how many lessons customers can see, and the course page now and after. Publishing does not by itself make it visible: the organization’s courses page is a second switch, moved from the dashboard, so the response reports storefront. Refused with no watchable lesson, or a paid course with no price. Reversible with unpublish_course; charges and emails nobody.
unpublish_courseWRITETake a course off the course page and back to draft. Buyers keep what they bought; free and members-only viewers lose access until it is published again. Refunds and emails nobody. Also brings an archived course back as a draft.
archive_courseWRITERetire a course. It leaves the course page and cannot be bought, but nothing is deleted and nobody is refunded; buyers keep watching. Reversible with unpublish_course.
reorder_course_outlineWRITEReorder chapters and lessons, or move lessons between chapters, by sending the whole outline in its new order. An outline that misses or repeats anything is refused (course_outline_mismatch) rather than dropping content.
create_course_chapterWRITEAdd an empty chapter at the end of a course. Every lesson lives in a chapter.
rename_course_chapterWRITERename one chapter. Its lessons and position stay as they are.
delete_course_chapterCONFIRMPermanently delete an empty chapter. A chapter that still holds lessons is refused (course_chapter_not_empty); move or delete them first.
create_course_lessonWRITEAdd a lesson to a chapter: a video (YouTube, Vimeo, Loom, or a direct https .mp4, .webm or .m3u8 link; Motive hosts no video) or a page of text. The server checks a video link and the lesson stays hidden from customers until the check passes; the response says whether customers can see it and what to fix.
update_course_lessonWRITEEdit a lesson’s title, video link, text, length, free-preview flag, or switch it between video and text. A new link is checked again.
delete_course_lessonCONFIRMPermanently delete a lesson, for every customer including buyers. The preview says whether a published course would be left with nothing to watch.
recheck_course_lesson_linkWRITECheck a video lesson’s link again and save the result, after a private video was made public or embedding was allowed. Can make a lesson visible, or hide one whose video was taken down.
Media
generate_imageWRITEGenerate one hosted image with AI. Confirms before spending.
upload_imageWRITEHost an image on Motive storage — base64 bytes or an http(s) URL to re-host — and get back a public https URL.
Motive staff only
create_tracking_linkWRITECreate a shareable motiverewards.com link that records who opens it; the visitor sees the normal site. Refused unless the connection belongs to a Motive super admin.
list_tracking_linksREADEvery tracking link with its clicks, distinct visitors, known people and last open. Motive super admins only.
get_tracking_link_clicksREADWho opened one tracking link: totals, where they came from, country and device, then each click with the person (once signed in), location, device and source, 50 per page. Motive super admins only.

Image fields (coverImageUrl, imageUrls, logoUrl …) also describe an attachment:<id> form. That one is for files a person attached inside Ask Motive chat, and it is refused over this connector — there is no conversation here to resolve an id against. On this endpoint, use upload_image and pass the https URL it returns.

Example prompts

You describe the outcome; your agent sequences the tools.

"Set up next month's showcase: $10 GA, 20 early-access at $25, and a race-expo vendor floor with 8 booths."

create_event→add_ticket_types→configure_vendor_tables→publish_event

"How's the gala tracking, and which premium booths are still open?"

get_event_analytics→get_vendor_availability

"Make a cinematic cover for the card show and set it as the event image."

generate_image→update_event

Rate limits & cost

The MCP endpoint allows a generous request budget per minute. Read and management tools are free. The one metered tool is generate_image, which produces a real, hosted image on each call, so it's bounded on purpose:

  • Always one image per call, never a batch.
  • A per-organization cap of 25 generations per hour.
  • The server requires a confirmation before every generation.

Errors

The endpoint speaks JSON-RPC 2.0 over HTTP; transport problems come back as HTTP status codes.

StatusMeaningFix
400Missing or invalid API keySend a valid x-api-key. Check the key wasn't revoked.
503MCP not enabled for your org yetAsk us for access; we roll it out per organization.
429Rate limit reachedSlow down, or wait out the image-generation hourly cap.

A tool that fails at the business layer (say, publishing an event whose org is still a draft) returns a normal MCP result with isError: true and a plain-language message, and it won't crash your session.

→

Next: open Integrations in your dashboard to mint a key, or reply to your onboarding thread to have MCP enabled for your organization.