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:
- The client registers itself with dynamic client registration
(
POST /register), then opensGET /authorizewith a PKCES256challenge. - 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).
- On submit, the server signs in to
identity.spoonity.comthe same way the dashboard does and fetches the list of vendors the account can access. - 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.
- The server redirects back to the client with an authorization code (valid
5 minutes), which the client exchanges at
POST /tokenfor 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:
- One vendor on the account: it is active from the start.
- Several vendors: the session starts with no vendor, and the server's
MCP
instructionstell the agent that before doing anything else it must calllist_vendors, ask the user which vendor they mean, and callset_active_vendor. Loyalty-platform calls fail until a vendor is set. - Vendor in the URL: connecting to
https://mcp.spoonity.com/<vendorId>starts the session on that vendor, if the account has access to it. An id the account cannot reach is ignored and the default applies. - Switching mid-session: call
set_active_vendoragain. Every later call in the session uses the new vendor. - A vendor granted after you signed in: call
refresh_vendor_list. It re-reads the account's vendors from the identity service without signing out.
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.
Spoonity Links (36)#
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:
- 28 fixed URIs, for example
customers://list,segments://list,campaigns://list,managed-campaigns://list,loyalty://tiers,loyalty://perks,stores://list,reports://templates,vendor://config,templates://list,catalogs://list,reference://countries,reference://timezonesandanalytics://questions. - 22 URI templates, for example
customers://profile/{customer_id},customers://transactions/{customer_id},segments://reach/{segment_id},campaigns://stats/{campaign_id},managed-campaigns://detail/{vendor_campaign_id},reports://data/{template_id}andstores://hours/{store_id}. Some templates also support listing, so a client can discover instances.
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#
- No Pass Studio tools. There are no tools for
wallet-api.spoonity.com(Pass Studio programs, sites, drafts and artwork; see Wallet). The only wallet tools are the loyalty platform's legacy Passbook and Google Pay ones (list_passbook,update_passbook_card,update_googlepayand related), which target a different, older pass system. The closest the server gets to Pass Studio iscms_get_brand/cms_update_brand, since Pass Studio reads brand colors, logo and artwork from the CMS brand record. - The
vendor_campaignmanaged-campaign endpoints currently return 403. As of 2026-08-27,build_managed_campaignandqueue_managed_campaignreturned"Insufficient permissions"for every vendor and role tried. The path that works today iscreate_campaignwithconfig.type: "managed_loyalty", thensend_campaign, which is what the dashboard does. The billing warning above still applies if the endpoint starts accepting calls. - Access is allowlisted. Only allowlisted email domains and addresses can sign in, so a merchant's own staff generally cannot connect unless Spoonity has added them.
- Sessions do not survive a restart. After a deploy or restart, clients must re-initialize (the token is still valid). The 50-session cap is server-wide.
- Many tools. 373 tools is more than some clients handle comfortably. If your client lets you switch individual tools off, turn off the groups you do not need.
- Insights tools call the Insights API, not the Insights app. The nine
insights_*tools call the same Insights API (/insights/*paths) that Prism's own backend uses, not the Insights app's own/api/*routes. If a number looks wrong, the fix is in the Insights API's query compiler, not in this server. - No CMS personalization rules or admin workflow actions. CMS's
/blocks/{blockId}/rulesendpoints and the approve, reject, schedule, publish, unpublish and version-restore actions have no tools, by design. - stdio mode is single-vendor.
set_active_vendorandrefresh_vendor_listwork only over HTTP with OAuth.
See also#
- Authentication, whose Service-to-service section covers the OIDC calls this server makes to Links, CMS and Insights
- CMS, Links, Wallet and Insights, the services these tools call
- The server's own
tools/list,resources/listandprompts/listresponses, which carry every tool's description and input schema