# Spoonity MCP Server

`mcp.spoonity.com` is a production [Model Context Protocol](https://modelcontextprotocol.io)
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.**

```bash
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`):

```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:

```json
{
  "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](#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:

- **One vendor on the account:** it is active from the start.
- **Several vendors:** the session starts with no vendor, and the server's
  MCP `instructions` tell the agent that before doing anything else it must
  call `list_vendors`, ask the user which vendor they mean, and call
  `set_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_vendor` again. 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`](../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](/docs/flags) |
| Spoonity Insights | The Insights API | The same service identity plus `X-Spoonity-Vendor`; see [Insights](/docs/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](/docs/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](#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](/docs/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](/docs/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](/docs/cms) and [Flags](/docs/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://timezones` and `analytics://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}` and `stores://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](/docs/wallet)).
  The only wallet tools are the loyalty platform's legacy Passbook and Google
  Pay ones (`list_passbook`, `update_passbook_card`, `update_googlepay` and
  related), which target a different, older pass system. The closest the
  server gets to Pass Studio is `cms_get_brand` / `cms_update_brand`, since
  Pass Studio reads brand colors, logo and artwork from the CMS brand record.
- **The `vendor_campaign` managed-campaign endpoints currently return 403.**
  As of 2026-08-27, `build_managed_campaign` and `queue_managed_campaign`
  returned `"Insufficient permissions"` for every vendor and role tried. The
  path that works today is `create_campaign` with
  `config.type: "managed_loyalty"`, then `send_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}/rules` endpoints and the approve, reject, schedule,
  publish, unpublish and version-restore actions have no tools, by design.
- **stdio mode is single-vendor.** `set_active_vendor` and
  `refresh_vendor_list` work only over HTTP with OAuth.

## See also

- [Authentication](/docs/authentication), whose Service-to-service section
  covers the OIDC calls this server makes to Links, CMS and Insights
- [CMS](/docs/cms), [Links](/docs/links), [Wallet](/docs/wallet) and
  [Insights](/docs/insights), the services these tools call
- The server's own `tools/list`, `resources/list` and `prompts/list`
  responses, which carry every tool's description and input schema
