Spoonity API Documentation View as Markdown Prism console

Spoonity MCP Server#

mcp.spoonity.com is a production Model Context Protocol server that exposes most of the Spoonity platform to an AI agent as MCP tools, resources and prompts. It covers the loyalty platform (customers, tiers, perks, stores, campaigns, reports), Spoonity Links, Spoonity CMS, Spoonity Flags, Apex Marketing Automation and Spoonity Insights. Claude, ChatGPT, Cursor or any other MCP client can call it directly.

It is not a REST API you call with curl and an API key the way CMS or Links are. It is one MCP endpoint that a person connects a chat client to. After that person signs in with their own Spoonity account, the agent acts on their behalf, limited to the vendors that account can reach.

This page covers what an integrator needs: the endpoint, how to connect a client, the OAuth flow, how vendor selection works, and the shape of the tool, resource and prompt surface. It does not list every tool. Each tool's description and input schema are served by the server itself in its tools/list response, which is the exhaustive, always-current reference.

Counts on this page were measured by running the server's own registration code (registerTools, registerResources, registerPrompts) against a fresh McpServer and reading back what it registered, at commit 29afddd (29afddd8982b19daed01e912d3db73f2c091acfc) of the server repository's main branch, dated 2026-09-22. The page was then brought up to 00c9a77 (00c9a77bab5e6f478423af05ac171fb8f9c89efd, 2026-10-08, PRs #30 to #33): the only change to the registered surface in that range is the new Flags group of 12 tools, so the tool total below is the measured 361 plus those 12, not a fresh registration run; the resource and prompt counts did not move. Deploys are made by hand, so the live server can briefly lag main.

Surface Count
Tools 373
Resources 50 (28 fixed URIs and 22 URI templates)
Prompts 23

Endpoint and transport#

Production URL: https://mcp.spoonity.com

The MCP endpoint is the bare root. There is no /mcp path; a request to https://mcp.spoonity.com/mcp returns 404.

Method and path Auth Purpose
POST / Bearer The MCP Streamable HTTP endpoint. Every JSON-RPC message (initialize, tool calls, resource reads, prompt fetches) goes here. Responses are plain JSON.
GET / Bearer Server-to-client stream for an existing session (Mcp-Session-Id required). Without a bearer token or session header, GET / returns a human-readable landing page instead.
DELETE / Bearer Ends a session.
POST /{vendorId} (numeric, for example /106078) Bearer Same endpoint, but the session starts on that vendor instead of the token's default, provided the signed-in account has access to it. GET and DELETE work on this path too.
GET /health None Liveness: { status, activeSessions, uptime_seconds, memory_mb, heap_mb, version, node }.
GET /.well-known/oauth-authorization-server None OAuth 2.0 Authorization Server Metadata (RFC 8414).
GET /.well-known/oauth-protected-resource None OAuth 2.0 Protected Resource Metadata (RFC 9728).

An unauthenticated POST / returns 401 with WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", which is what prompts a compliant client to start the OAuth flow.

Sessions. Each MCP session gets its own server instance and API client, tracked by the Mcp-Session-Id header, so state never leaks between sessions. A session expires after 30 minutes without activity. The server holds at most 50 concurrent sessions and answers 429 beyond that. Sessions live in memory only: after a server restart, a request carrying an old session id gets 404 with the JSON-RPC error "Session not found. Server was restarted. Please re-initialize.", and the client must send a new initialize. Your OAuth token survives the restart; only the session does not.

stdio mode. The same code also runs as a local stdio server for a developer working from a checkout of the server repository, authenticated with a dashboard session key for a single vendor. No OAuth flow applies, and vendor switching is not available in that mode. Integrators connecting to mcp.spoonity.com do not use it.

Connecting a client#

Every client below discovers the OAuth endpoints on its own from the URL. You only supply https://mcp.spoonity.com (or https://mcp.spoonity.com/<vendorId> to start on a specific vendor) and then sign in when the browser opens.

Claude (claude.ai and Claude Desktop). Settings, then Connectors, then "Add custom connector". Enter https://mcp.spoonity.com as the URL and complete the Spoonity sign-in.

Claude Code.

claude mcp add --transport http spoonity https://mcp.spoonity.com

Then run /mcp inside Claude Code and choose the server to sign in.

Cursor. Add it to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):

{
  "mcpServers": {
    "spoonity": {
      "url": "https://mcp.spoonity.com"
    }
  }
}

ChatGPT. Add https://mcp.spoonity.com as an MCP connector and sign in with your Spoonity credentials.

Any other MCP client. A client that speaks Streamable HTTP with OAuth uses the same url entry as Cursor. A client that only supports stdio can reach it through the mcp-remote bridge, which runs the OAuth flow in your browser:

{
  "mcpServers": {
    "spoonity": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.spoonity.com"]
    }
  }
}

Authentication#

Inbound: OAuth 2.1 with PKCE, not an API key#

There is no vendor-mintable API key for this server. Connecting is an interactive sign-in, implemented as an OAuth 2.1 authorization server in front of your own Spoonity account. The live discovery document advertises:

Field Value
issuer https://mcp.spoonity.com/
authorization_endpoint https://mcp.spoonity.com/authorize
token_endpoint https://mcp.spoonity.com/token
registration_endpoint https://mcp.spoonity.com/register
revocation_endpoint https://mcp.spoonity.com/revoke
response_types_supported code
grant_types_supported authorization_code, refresh_token
code_challenge_methods_supported S256
token_endpoint_auth_methods_supported client_secret_post, none
scopes_supported empty (there are no scopes; access is whatever your Spoonity account can reach)

The flow:

  1. The client registers itself with dynamic client registration (POST /register), then opens GET /authorize with a PKCE S256 challenge.
  2. The server shows a Spoonity sign-in form asking for email and password. No vendor id is asked for. Above the fields a consent notice names the application asking for access (the client's registered name), the host the authorization code will be sent to, and a badge: Recognised application (the Claude and ChatGPT callbacks), Local application on this device (loopback), Browser extension, Desktop application (private-use scheme) or Unrecognised application. An unrecognised redirect host also shows a warning to continue only if you opened the page from that application, because signing in gives it access to your Spoonity account (spoonity-mcp-server #33).
  3. On submit, the server signs in to identity.spoonity.com the same way the dashboard does and fetches the list of vendors the account can access.
  4. If the account has exactly one vendor, that vendor is selected. If it has several, no vendor is selected yet; the choice happens in the chat (see Vendor selection below). An account with no vendors is refused at the form.
  5. The server redirects back to the client with an authorization code (valid 5 minutes), which the client exchanges at POST /token for an access token and a refresh token.

Token lifetimes. An access token is valid for 8 hours. The client renews it with the refresh token, and each refresh rotates the refresh token (a refresh token is valid for 30 days from sign-in, absolute: rotation carries the original expiry forward rather than extending it, so you sign in again after 30 days; it was 90 days before #33, and refresh tokens issued earlier are capped to the new limit on load). Behind the scenes the server keeps its own Spoonity platform session, which lasts 4 hours, and renews it automatically before it expires, so the agent does not see that shorter lifetime.

What is stored. To renew the Spoonity session without asking you again, the server keeps your Spoonity credential server-side, sealed with a Cloud KMS envelope (it was AES-256-GCM with a key held in the server's configuration before #33), alongside the issued tokens. The credential is sealed as soon as sign-in succeeds, is not decrypted when the server starts or rehydrates stored sessions, and is opened only at the moment it is used to log in to the platform. Your MCP client only ever holds the MCP access and refresh tokens, never your Spoonity password. Revoking the token (POST /revoke) removes it from the server, and so does the identity service rejecting the stored credential (for example after a password change): that ends the whole session family on the next renewal attempt. An hourly sweep also deletes expired tokens, sessions of emails that have left the allowlist, stale authorization codes, and registered clients that never obtained a token within 24 hours or have been idle for 180 days.

Redirect URIs. Clients registered through POST /register are held to the redirect URIs they registered. The Claude and ChatGPT callback URLs are always accepted, as are http://localhost:<any port>/callback and http://127.0.0.1:<any port>/callback for command-line clients, and https://<extension-id>.chromiumapp.org/... for Chrome extensions. Registration itself now refuses a redirect URI that is not https, a loopback address or a private-use scheme (such as myapp://callback), with the RFC 7591 error invalid_redirect_uri, because anything else would send authorization codes in cleartext. Registration is limited to 10 per hour per IP (it was 20).

First-party password grant. Spoonity's own Companion Chrome extension signs in with a direct username and password exchange at POST /token (grant_type=password). It is not advertised in the discovery document and third-party clients should use the authorization-code flow above.

Rate limits. POST /token allows 15 attempts per 15 minutes per IP, and the sign-in form allows 10 attempts per 15 minutes per IP. Past either limit the server answers 429.

Email allowlist. A correct Spoonity password is not enough on its own. The account's email must also be on the server's allowlist, which is a list of permitted email domains (Spoonity staff and a small number of partner domains) plus individually permitted addresses. The check runs at sign-in, at every token refresh, and on every authenticated request, so removing someone from the allowlist cuts off a live session immediately rather than at the next login. A refused account always sees the same message, "Access to this server is restricted to authorized accounts.", with no hint about which check failed. If you need access for an account outside Spoonity, ask your Spoonity contact to add it.

Vendor selection#

Almost every tool acts on one active vendor per session. How that vendor gets chosen:

Per-vendor platform hosts. Most merchants are served by the shared platform host api.spoonity.com. Some run on a dedicated cluster at api-<slug>.spoonity.com (for example api-cafemartinez.spoonity.com or api-innovativefoodbrands.spoonity.com). The server keeps a map of those vendors (47 vendor ids across 20 dedicated hosts at the commit above) and routes the loyalty-platform tools to the right host automatically whenever a vendor becomes active; set_active_vendor reports the host it chose as platform_host and whether it is custom as custom_endpoint. Reporting, marketing and identity stay on the shared hosts for every vendor. When a vendor has no mapped host, set_active_vendor first checks that the shared host actually serves that vendor and refuses to switch if it does not, rather than risk sending calls to a different merchant on the wrong cluster. Prism's BFF routes /api/loyalty/* with a copy of the same map; see docs/design/platform-host-routing.md.

The Links, CMS and Insights groups follow the same active vendor. The Apex group does not: Apex organizes data by workspace, so call apex_list_workspaces and apex_set_active_workspace before other apex_* tools.

Outbound: what each tool group calls#

Each tool group calls a different Spoonity service with the credential that service expects:

Tool group Backend How the server authenticates
Loyalty platform api.spoonity.com (or the vendor's dedicated api-<slug> host), reporting.spoonity.com, marketing.spoonity.com Your own Spoonity session for the active vendor, the same kind of session the dashboard uses
Spoonity Links links.spoonity.com The server's Google Cloud service identity: a Google-signed OIDC ID token plus X-Spoonity-Vendor: <active vendor id>
Spoonity CMS cms.spoonity.com The same service identity plus X-Spoonity-Vendor (and X-Spoonity-Vendor-Name as a hint when a vendor is used for the first time)
Spoonity Flags flags.spoonity.com (/admin/v1) The same service identity plus X-Spoonity-Vendor, X-Spoonity-User and X-Spoonity-Role; see Flags
Spoonity Insights The Insights API The same service identity plus X-Spoonity-Vendor; see Insights
Apex Marketing Automation api.getapex.app One Spoonity service account on Apex, unrelated to your own login

The service-identity calls fall under the Service-to-service section of Authentication. The ID token is minted from the Google Cloud metadata server and cached per audience. Because the vendor always comes from the session, no Links, CMS or Insights tool takes a vendor argument, so an agent cannot make the server fetch another vendor's data by naming it.

CMS treats this service identity as the editor role. It can create and edit spaces, blocks, translations and media metadata, run experiments, edit the brand record and submit a space for review. It cannot approve, reject, publish, unpublish or delete a space, delete a block or media, or manage API keys; those stay with a human admin in the CMS dashboard. The one exception is cms_import_legacy_content, whose publish: true option makes the imported spaces live immediately (its default is draft).

If a group's backend is not configured on a given server, its tools stay listed and each call returns isError: true with a "not configured" message instead of failing the session.

Tool groups#

373 tools at commit 00c9a77, in six groups. Links, CMS, Flags, Apex and Insights each keep a canonical name list in the source that their own tests check against; the loyalty-platform figure is the sum of its ten registration modules. All but the Flags row were read back from a live registration at 29afddd, not counted by hand; the Flags row is the 12 names in its canonical list at 00c9a77.

Group Tools Prefix Representative tools
Loyalty platform 216 none search_customers, create_tier, create_campaign, report_sales_summary
Spoonity Links 36 mostly none; 5 use links_ create_link, get_link_analytics, upsert_bio_page
Spoonity CMS 35 cms_ cms_add_block, cms_submit_space, cms_set_app_config
Spoonity Flags 12 flags_ flags_list_flags, flags_set_switch, flags_kill_flag
Apex Marketing Automation 65 apex_ apex_create_journey, apex_estimate_audience, apex_send_campaign
Spoonity Insights 9 insights_ insights_run_dashboard, insights_query, insights_status

Loyalty platform (216)#

The original surface, with no name prefix. It breaks down by module:

Module Tools Representative tools
Account and vendor selection 3 list_vendors, set_active_vendor, refresh_vendor_list
Customers 24 search_customers, edit_reward_points, merge_customers
Segments 5 create_segment, list_segment_criteria, get_segmentation_options
Marketing campaigns (v3, on marketing.spoonity.com) 9 create_campaign, send_campaign, get_campaign_reach
Managed loyalty campaigns and email templates 29 get_managed_campaign, test_managed_campaign, queue_managed_campaign
Loyalty (tiers, perks, redemptions, award links, verification, currencies) 48 create_tier, create_perk, create_award_link
Stores and catalogs 16 create_store, update_store_hours, create_catalog
Vendor settings, metadata, legacy wallet passes, API keys, content pages 44 get_vendor_settings, list_api_keys, update_terms_of_service
Reports, analytics and webhooks 30 generate_report, report_sales_summary, create_webhook
Employees 8 search_employees, create_employee, import_employees

The reports module includes 12 ready-made report_* tools (report_sales_summary, report_customer_growth, report_gift_card_liability and others) alongside the template-based generate_report / get_report_download / read_report_csv path.

Managed campaigns cost money. queue_managed_campaign sends a managed loyalty campaign and, before sending, bills the vendor's QuickPay balance for the full reach at each channel's per-recipient rate. It is not reversible. If the balance is short, the call fails with 402 and nothing is sent. send_managed_campaign (the older provider-direct path) also sends to real recipients. Both are marked destructiveHint: true so a client that asks before destructive actions will ask before these. Read get_managed_campaign first to confirm the reach and cost, and use test_managed_campaign, which is free and changes nothing, to preview. See also the 403 limit under Known limits.

Tool annotations. Loyalty-platform tools get MCP annotations from their names: get_, list_, search_, read_ and check_ tools are readOnlyHint: true; delete_ tools, unverify_customer and the two managed-campaign send tools are destructiveHint: true; update_, edit_ and set_ tools are idempotent. The other five groups declare their own annotations per tool.

Short links, routing rules, click analytics, deep-link configs, webhooks, bio pages, QR codes, custom domains and usage. Most tools carry no prefix (list_links, get_overview, get_timeseries, set_deeplink_config, get_link_qr, set_custom_domain, get_vendor_usage). Five carry links_ because the loyalty platform already has a tool with the same base name: links_list_webhooks, links_create_webhook, links_update_webhook, links_delete_webhook and links_get_vendor_settings. So create_webhook creates a loyalty-platform webhook and links_create_webhook creates a Links one. The Links API itself is documented at Links.

Spoonity CMS (35)#

Spaces and version history, blocks, media, translations, preview and delivery, content analytics, search, experiments, the app_config remote config (cms_get_app_config / cms_set_app_config, the same block type documented at CMS), the vendor brand record (cms_get_brand / cms_update_brand), lookups, and the legacy content importer. Every tool is limited to the editor role described above, so cms_submit_space (draft to review) is the handoff to a human reviewer. cms_import_legacy_content defaults to a dry run, is idempotent on re-run, and leaves imported spaces as drafts unless publish: true is passed.

Spoonity Flags (12)#

Spoonity Flags (flags.spoonity.com) is now the source of truth for app behaviour switches. The CMS app_config feature_flags, store_order.doxi_handoff and qa_feedback.testers remain only as the apps' bootstrap and fallback values (see CMS and Flags). Every tool carries a flags_ prefix and follows the active vendor, so none takes a vendor argument. The group authenticates as delegated identity: the server's service-account ID token plus X-Spoonity-Vendor (the active vendor), X-Spoonity-User (your email) and X-Spoonity-Role (editor unless the server is configured otherwise). Changes therefore appear in the Flags audit log with your email as the actor and the MCP service account as via. Like the other service-identity groups it returns a "not configured" error on a server that has no Flags credential.

Tool What it does
flags_list_flags List the flags in the vendor's workspace (one page plus nextCursor); switches imported from the CMS carry the tag app-config.
flags_get_flag One flag's workspace metadata: name, description, tags, owner, archived.
flags_get_definition A flag's definition in one environment (enabled, killed, treatments, rules, default rule) and its version.
flags_set_switch Turn an app switch on or off for everyone in one environment; creates the flag if missing and keeps existing targeting rules unless clear_rules=true.
flags_set_definition Replace a flag's whole definition, validated client-side, with optimistic locking on expectedVersion (a stale write is a 409 version_conflict).
flags_kill_flag Emergency stop: every context gets the default treatment until restored (destructive).
flags_restore_flag Un-kill a killed flag so rules and the default rule apply again.
flags_audit_log Read the change log for an environment, or the whole workspace with scope=workspace.
flags_list_segments List the segments in an environment with their key counts.
flags_get_segment One segment, and with include_keys=true a page of its member keys.
flags_patch_segment_keys Add and/or remove segment member keys (bare member ids), or replace the whole list; create_if_missing=true creates the segment. Used for the qa_feedback tester audience.
flags_import_app_config Seed flags from the vendor's public CMS app-config: one on/off flag per switch plus the qa_feedback tester segment. Dry run by default; pass dry_run=false to write.

The CMS tools picked up the matching change in #30: cms_set_app_config accepts the qa_feedback section and feature_flags.qa_feedback.

Apex Marketing Automation (65)#

Workspaces and their users, customers and customer properties, tags, journeys, campaigns (apex_send_campaign, apex_cancel_campaign, apex_resume_campaign), audience estimates, email analytics, quota and billing reads, configurations, sending domains and notifications. Start with apex_list_workspaces and apex_set_active_workspace.

Spoonity Insights (9)#

insights_status, dashboards (insights_list_dashboards, insights_get_dashboard, insights_run_dashboard, insights_run_tile, insights_export_tile) and ad hoc queries over the semantic views (insights_query_views, insights_describe_view, insights_query). No Insights tool accepts a vendor argument; the vendor is always the session's active vendor.

Resources#

50 resources, all belonging to the loyalty-platform group; Links, CMS, Apex and Insights expose tools only. Resources are read-only and addressed by URI:

URI schemes in use: customers, segments, segmentation, campaigns, managed-campaigns, loyalty, stores, reports, vendor, feedback, egift, insights, verification, reference, templates, catalogs, analytics and guide.

guide://usage is a usage guide written for the agent; it is a good first read for a client that supports resources.

Prompts#

23 prompts, reusable conversation starters for common workflows:

customer-lookup, customer-360, customer-merge, customer-support-case, transaction-investigation, bulk-point-adjustment, award-promotional-code, send-egift, create-campaign, campaign-performance, marketing-segment, email-template-preview, generate-report, custom-report, business-overview, loyalty-overview, setup-loyalty-program, setup-new-store, manage-store-hours, store-audit, vendor-onboarding, troubleshoot-auth and wallet-pass-setup.

marketing-segment walks the two-stage workflow of sizing a cohort in Insights and then rebuilding it as segment criteria you can act on. wallet-pass-setup first sends the user to Pass Studio (see below) and only falls back to the legacy pass tools once the vendor is confirmed to still be on the older system.

Known limits#

See also#