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.
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.
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.
{
"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.
Ask it to do something
That's it. Try a real request:
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.
Open the connector settings
In claude.ai, go to Settings then Connectors and click Add custom connector.
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.
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.
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.
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.
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.
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
217 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 217 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.
| Tool | Type | What it does |
|---|---|---|
| Events | ||
create_event | WRITE | Create an event: date, venue, capacity, visibility, and an optional Spotify playlist, album or song link. Returns a draft with its public URL. |
update_event | WRITE | Edit 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_event | CONFIRM | Take a draft event live and shareable publicly. |
cancel_event | CONFIRM | Cancel a published event. It stays in the system as cancelled and its RSVPs, orders and tickets are preserved. Does not refund anyone. |
delete_event | CONFIRM | Permanently delete an event. Refused if it has any tickets sold, RSVPs, or check-ins — cancel it instead. |
get_event_details | READ | Full configuration and analytics for one event, including whether the org has connected Spotify. |
list_events | READ | Your org's events, filterable by upcoming, past, or live. Capped at 50 per call; page with offset. |
get_event_analytics | READ | RSVPs, check-ins, ticket revenue, per-tier breakdown, and Soundtrack plays. |
get_event_revenue_summary | READ | Gross 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_album | READ | An 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_photos | READ | The 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_settings | WRITE | Change who can see the album, who can add photos, and whether it takes new ones. Closing an album deletes nothing. |
add_event_album_photo | WRITE | Add 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_photo | WRITE | Take a photo out of the album and the activity feed. Kept for 30 days so it can be restored. |
restore_event_album_photo | WRITE | Put back a photo a host removed, within 30 days. Refused for a photo its uploader removed or moderation removed. |
| Luma distribution | ||
get_luma_sync_status | READ | Whether 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_luma | CONFIRM | List 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_publish | CONFIRM | Pull 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_types | WRITE | Add ticket tiers to an event: name, price, quantity. Appends by default; pass mode: "replace" to delete the existing lineup and start over. |
update_ticket_type | WRITE | Edit one ticket tier in place. |
remove_ticket_type | CONFIRM | Permanently remove one ticket tier from an event. |
get_ticket_availability | READ | Per-tier price and how many tickets remain. |
list_orders | READ | Ticket orders for an event, newest first. |
get_order | READ | Full detail for one ticket order. |
refund_order | CONFIRM | Issue a Stripe refund for a ticket order. |
| RSVPs & check-ins | ||
approve_rsvp | WRITE | Approve one pending RSVP and admit the applicant. |
deny_rsvp | CONFIRM | Deny one pending RSVP, rejecting the applicant. |
review_pending_rsvps | READ | Suggest approvals for pending RSVPs without changing anything. |
list_attendees | READ | An event's attendees with names and RSVP status. Capped at 50 per call; page with offset. |
list_check_ins | READ | Everyone who has checked in, plus the total. |
invite_to_event | CONFIRM | Invite all members or a chosen list to an event. |
| Vendor floor | ||
configure_vendor_tables | WRITE | Build a full vendor floor: tiers, pricing, and grid map. |
list_vendor_tables | READ | List vendor tables for one event or all. |
create_vendor_table | WRITE | Create a single vendor table for an event. |
bulk_create_vendor_tables | WRITE | Create many identical vendor tables at once. |
update_vendor_table | WRITE | Update one table's name, price, status, or tiers. |
delete_vendor_table | CONFIRM | Permanently delete a single vendor table. |
clear_table_position | WRITE | Unplace a table from the floor map, keeping the table. |
update_table_position | WRITE | Move a single table to a new grid cell. |
get_vendor_availability | READ | Open versus reserved tables by type. |
get_vendor_table_settings | READ | Whether vendor sales are enabled and how they behave. |
update_vendor_table_settings | WRITE | Toggle vendor sales and related settings for an event. |
list_table_types | READ | The table tiers configured for an event. |
create_table_type | WRITE | Create a single vendor table tier. |
update_table_type | WRITE | Edit a table tier's name, price, or color. |
delete_table_type | CONFIRM | Permanently delete a table tier. |
get_vendor_analytics | READ | Vendor order counts and revenue for an event. |
| Vendor orders & vendors | ||
list_vendor_orders | READ | Vendor table orders for one event or all. |
refund_vendor_order | CONFIRM | Refund a completed vendor table order in full. |
approve_or_deny_vendor_order | CONFIRM | Approve or deny a pending vendor order; notifies the vendor. |
list_vendor_waitlist | READ | People waiting for a table to open up. |
list_vendor_profiles | READ | Cross-event vendor identities for the organization. |
get_vendor_profile | READ | One vendor's profile plus their recent orders. |
| Vendor-booth discounts & add-ons | ||
list_discount_codes | READ | Vendor-table discount codes for an event. |
create_discount_code | WRITE | Create a percentage-off vendor-table discount code. |
update_discount_code | WRITE | Toggle, re-cap, or edit a discount code. |
delete_discount_code | CONFIRM | Permanently delete a vendor-table discount code. |
list_add_ons | READ | Vendor-table add-ons offered for an event. |
create_add_on | WRITE | Create an optional vendor-table add-on. |
update_add_on | WRITE | Edit an add-on's name, price, or inventory. |
delete_add_on | CONFIRM | Permanently delete a vendor-table add-on. |
| Vendor messaging | ||
send_vendor_message | CONFIRM | Email a blast to an event's vendors. |
list_vendor_messages | READ | Vendor message blasts already sent for an event. |
| Shop products | ||
list_shop_coupons | READ | Coupon / promo codes for shop products. |
create_shop_coupon | WRITE | Create a shop coupon — fixed dollar or percent off, optionally scoped to products and gated on a minimum quantity. |
update_shop_coupon | WRITE | Toggle, re-scope, or edit a shop coupon. |
delete_shop_coupon | CONFIRM | Permanently delete a shop coupon. |
create_product | WRITE | Create a shop product, always as a draft. |
publish_product | WRITE | Publish a draft product so it becomes purchasable. |
list_products | READ | The organization's shop products with status. |
get_product | READ | One product's details, images, variants, and stock. |
update_product | WRITE | Edit a product's name, images (add or replace), or fulfillment. |
unpublish_product | WRITE | Take a product off sale by reverting it to draft. |
archive_product | WRITE | Remove a product from the active catalog. |
add_product_variant | WRITE | Add a size or color variant with its own price. |
update_product_variant | WRITE | Edit a variant's size, color, price, or stock. |
remove_product_variant | CONFIRM | Permanently remove a single variant from a product. |
list_stock_notifications | READ | Buyers 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_orders | READ | Shop orders (merch purchases), newest first. |
get_shop_order | READ | One shop order's status, fulfillment, and customer. |
update_shop_order_fulfillment | WRITE | Set fulfillment status or attach shipping tracking. |
refund_shop_order | CONFIRM | Issue a full Stripe refund for a shop order. |
| Members | ||
list_org_members | READ | Look up members by name or email. |
get_member_details | READ | One member's profile plus their event activity. |
get_members_list | READ | Members with join date, points, and opt-outs. |
get_member_growth | READ | Member-growth time series over a range. |
get_member_count | READ | Total active members, a fast headline number. |
get_team_members | READ | Staff (owner, admins, moderators) with their roles. |
get_onboarding_status | READ | The org's setup and onboarding checklist state. |
remove_member | CONFIRM | Remove a member from the organization (soft delete). |
invite_org_members | CONFIRM | Email people the org's public join link. |
| Communications | ||
preview_member_blast | READ | Preview an org-wide member SMS without sending. |
list_blast_members | READ | Members with per-person SMS-blast eligibility flags. |
get_member_blast_history | READ | History of org-wide member SMS blasts. |
send_org_member_blast | CONFIRM | Text and email every eligible active org member. Reports each channel separately — a send can be partial. |
preview_event_blast | READ | Preview an event SMS without sending. |
get_event_blast_history | READ | History of SMS blasts for one event. |
get_event_blast_stats | READ | Delivery stats for one specific event blast. |
send_event_blast | CONFIRM | Text and email an event's going and maybe attendees. Reports each channel separately — a send can be partial. |
preview_event_announcement | READ | Who 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_announcement | CONFIRM | Email 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_notifications | READ | Org 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_announcement | READ | Who 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_announcements | READ | The organization’s posts, newest first, with each one’s channels, status, reach, image and link card. Filter by event or scope; page with offset. |
send_host_announcement | CONFIRM | Post a message to the community or to an event’s guests, 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_announcement | CONFIRM | Fix 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_announcement | CONFIRM | Delete 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_role | CONFIRM | Give a member a team role or invite staff. |
revoke_role | CONFIRM | Revoke a staff role, demoting to regular member. |
list_pending_invites | READ | Pending, not-yet-accepted team invites. |
resend_invite | WRITE | Resend a team invite and reset its expiry. |
cancel_invite | WRITE | Cancel a pending team invite. |
| Organization | ||
update_organization | WRITE | Edit org profile, branding, privacy, and policies. |
publish_organization | CONFIRM | Publish the org and make its public surfaces live. |
set_shop_status | WRITE | Set shop status: disabled, draft, or published. |
set_shop_integration | WRITE | Enable or disable the shop feature. |
update_shop_settings | WRITE | Set the org's default shipping price, free-shipping quantity, processing-time windows, and backorder policy. |
set_vendor_tables_status | WRITE | Enable or disable the vendor-tables feature. |
set_spotify_integration | WRITE | Connect or disconnect Spotify, which event Soundtrack links need. Disconnecting hides the players but keeps every link. |
set_developer_integration | WRITE | Enable or disable the developer-integration feature. |
get_checkout_link | READ | The 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_versions | READ | Version history of a single org policy. |
get_policy_audit_log | READ | Who created, updated, or published a policy. |
get_policy_acceptance_status | READ | Where each member stands on a given policy. |
| Custom domains | ||
add_custom_domain | WRITE | Register a custom domain for the org's public pages. |
verify_custom_domain | WRITE | Verify a pending domain by checking its DNS. |
list_custom_domains | READ | Custom domains with verification status and DNS records. |
delete_custom_domain | CONFIRM | Remove a custom domain and de-register it from Vercel. |
| API keys | ||
get_connection_info | READ | Which org this connection is bound to, its scopes, and whether the dangerous scope is granted. Call it first when anything looks wrong. |
list_api_keys | READ | Active API keys, masked, with last-used info and each key's scopes, including whether it holds dangerous. |
revoke_api_key | CONFIRM | Revoke an API key; integrations using it stop working. |
| Billing | ||
get_subscription | READ | Current plan tier, status, and billing period. |
list_invoices | READ | Billing invoices, newest period first. |
get_upcoming_invoice | READ | Preview the not-yet-issued invoice for this period. |
get_invoice | READ | Full detail for a single invoice. |
get_invoice_pdf_url | READ | A downloadable URL for an invoice PDF. |
get_invoice_receipt | READ | A structured receipt for an invoice. |
get_current_usage | READ | This month's usage across all metered channels. |
get_payment_method | READ | The default payment method, masked. |
get_billing_audit_log | READ | Chronological 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_plans | READ | Your 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_plan | READ | One 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_analytics | READ | How 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_codes | READ | Discount 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_code | WRITE | Create 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_code | WRITE | Switch a membership discount code on or off, or change its plans, redemption cap or expiry. |
delete_membership_discount_code | CONFIRM | Permanently delete a membership discount code. Members already using it keep their discount. |
list_membership_plan_prices | READ | A 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_subscriptions | READ | Who 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_subscription | READ | One 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_invoices | READ | One 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_subscription | WRITE | Cancel one member at the END of the current period: they keep what they paid for, then are not charged again. No refund. |
comp_member_subscription | WRITE | Waive one member's dues (the membership keeps renewing at $0), or remove the comp with comped: false. Refunds nothing already paid. |
suspend_member_benefits | WRITE | Pause one member's benefits until a date while billing continues — a club closed for the season. Touches no payment. |
restore_member_benefits | WRITE | Give a paused member their benefits back now. Billing was never stopped. |
cancel_member_subscription_now | CONFIRM | End 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_invoice | CONFIRM | Refund 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_invoice | CONFIRM | Mark 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_plan | WRITE | Create 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_plan | WRITE | Edit 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_upgrades | READ | Which 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_upgrades | WRITE | Link 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_price | WRITE | Change 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_price | WRITE | Add 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_option | WRITE | Stop 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_plan | CONFIRM | Take 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_plan | WRITE | Take 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_plan | WRITE | Retire 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_plan | WRITE | Un-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_status | WRITE | The 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_live | CONFIRM | Takes 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_bookings | WRITE | The 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_live | CONFIRM | Publish 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_quote | READ | Price 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_availability | READ | Which 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_services | READ | The 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_service | READ | One 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_bookings | READ | Booking 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_booking | READ | One 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_service | WRITE | Create 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_service | WRITE | Edit 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_dates | WRITE | Close 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_service | WRITE | Take 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_service | WRITE | Retire 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_service | WRITE | Bring 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_service | CONFIRM | Take 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_service | CONFIRM | Permanently 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_booking | WRITE | Type 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_quote | WRITE | Send 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_booking | WRITE | Turn 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_date | WRITE | Promise 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_hold | WRITE | Give 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_booking | WRITE | Mark 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_booking | CONFIRM | Accept 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_booking | CONFIRM | Call 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_payment | CONFIRM | Give 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_refund | WRITE | Check 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_courses | READ | Your 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_course | READ | One 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_course | WRITE | Create 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_course | WRITE | Edit 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_course | CONFIRM | Publish 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_course | WRITE | Take 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_course | WRITE | Retire 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_outline | WRITE | Reorder 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_chapter | WRITE | Add an empty chapter at the end of a course. Every lesson lives in a chapter. |
rename_course_chapter | WRITE | Rename one chapter. Its lessons and position stay as they are. |
delete_course_chapter | CONFIRM | Permanently delete an empty chapter. A chapter that still holds lessons is refused (course_chapter_not_empty); move or delete them first. |
create_course_lesson | WRITE | Add 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_lesson | WRITE | Edit 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_lesson | CONFIRM | Permanently 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_link | WRITE | Check 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_image | WRITE | Generate one hosted image with AI. Confirms before spending. |
upload_image | WRITE | Host 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_link | WRITE | Create 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_links | READ | Every tracking link with its clicks, distinct visitors, known people and last open. Motive super admins only. |
get_tracking_link_clicks | READ | Who 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_eventRate 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.
| Status | Meaning | Fix |
|---|---|---|
400 | Missing or invalid API key | Send a valid x-api-key. Check the key wasn't revoked. |
503 | MCP not enabled for your org yet | Ask us for access; we roll it out per organization. |
429 | Rate limit reached | Slow 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.
Developers