Loyalz MCP server

What the server gives an agent

Most marketing MCP servers hand an assistant one ad account. Loyalz is the layer that already holds every connected ad platform next to the store's settled orders, the loyalty programme the store runs, the creative pipeline that feeds the ads and the calendar that schedules the brand's social posts. The MCP server exposes all four through one connection, scoped to one merchant account:

• Insights — query spend, clicks, conversions, revenue, orders, POAS/ROAS and every calculated metric across Meta, Google, TikTok, LinkedIn, WooCommerce, Shopify, Sellasist and e-mail; build and edit dashboards; define custom metrics from formulas; list campaigns and individual ads with their results and creative; ask the ad platform for de-duplicated reach and frequency; read search terms, campaign set-up, conversion actions and bid strategies live from Google Ads, and placements, new vs returning customers, hour of day, ad-set attribution windows, audience size and pixel status live from Meta.
• Loyalty — read and shape the programme (levels, quests, tasks, benefit collections, leaderboards), grant points, cashback or benefits to a named customer, read the ledgers.
• Creative Studio — brand profile and references, concept runs for statics and video with a human review gate on prompts, ad copy with a compliance check, approvals, publishing approved creatives into an existing Meta ad set as paused ads, and a brand playbook learned from the brand's own results.
• Content Calendar — the brand's connected social accounts (Facebook, Instagram, LinkedIn, TikTok, YouTube, X), a media library fed by uploads, links or Studio creatives, and scheduled posts. The agent writes drafts; a person approves them.

Prompts that work on day one

• "Compare Meta and Google spend against store revenue for the last 30 days, by week, and tell me which channel has the better POAS."
• "Add a KPI card with blended CAC to the Weekly dashboard."
• "Create a quest worth 200 points for customers who follow us on Instagram."
• "Show the three best-performing ads in our summer campaign and draft a static concept run from the winner."
• "Put the approved summer creative on Instagram and Facebook for Friday at 6 pm, as a draft I can approve."

Connect

You need a Loyalz merchant account and an MCP token. Tokens are created in the merchant panel under Settings → Agents API; each token is bound to one merchant and can be revoked there at any time. Send it as a Bearer header on the SSE request and on every message. Tokens in the URL are not accepted.

Claude Code

claude mcp add --transport sse loyalz https://api.loyalz.io/api/mcp/sse --header "Authorization: Bearer <token>"

Claude Desktop, Cursor, Windsurf and other mcpServers clients

{
  "mcpServers": {
    "loyalz": {
      "type": "sse",
      "url": "https://api.loyalz.io/api/mcp/sse",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Any MCP client or SDK

GET https://api.loyalz.io/api/mcp/sse
Authorization: Bearer <token>
Accept: text/event-stream

# the server advertises the messages URL in the first event;
# POST every JSON-RPC message there with the same Authorization header

After connecting, call tools/list once. The catalog below is what it returns. Creative Studio tools take an input object, including reads with no fields ({"input": {}}); the other tools take their arguments directly.

Claude.ai and ChatGPT connector directories

The hosted directories of Claude and ChatGPT sign users in with OAuth 2.1 and expect the Streamable HTTP transport; a static token in a header is accepted by Claude Code, Claude Desktop, Cursor, Windsurf, the SDKs and self-hosted agents, but not by those two directories. OAuth sign-in and Streamable HTTP for the Loyalz server are in progress. Until they ship, connect through a header-capable client as shown above; this page will name the directory entries the day they are live.

Authentication, tenancy and audit

• One token, one merchant. The connection context is the merchant that owns the token. No tool takes a merchant id, a user id or a "switch account" argument; to work on another account, connect with that account's token.
• Bearer only. The token travels in the Authorization header of the SSE request and of every POST to the messages endpoint. Session URLs are not credentials and a session cannot outlive its token: revocation is checked again before each tool call.
• Plan gates apply as in the app. Insights tools need Insights enabled on the account; Creative Studio tools need the Shark plan or higher; Content Calendar tools need the calendar switched on for the account. A gated call returns a clear refusal, never partial data.
• Writes are idempotent. Tools that change state or spend credits take an idempotency_key; a retried call with the same key returns the original result instead of acting twice.
• Audit. Actions taken through the server are logged per merchant and readable with get_mcp_history. Studio and publishing keep their own operation registers.

Tool catalog

113 tools · 55 in Creative Studio · generated from the server registry on 28 October 2026

read no state change   writes changes data in your account   spends credits charges Studio credits or reserves them

What can go wrong, and what cannot

• Money. No tool moves money or changes a subscription. Studio steps marked "spends credits" draw on prepaid credits; studio_list_credit_packs only returns checkout links, it never purchases.
• Ads. studio_publish creates ads in an existing Meta ad set in a paused state; nothing goes live without a human switching it on in Ads Manager. Read tools never change the ad account, including the ones that read Google Ads and Meta live.
• Social posts. Calendar tools create and edit drafts, and a draft never publishes. A post goes out at its time only once it is approved: in the Loyalz panel, or with calendar_approve_post when the user explicitly asks the agent to approve that post. Editing an approved post sends it back to draft.
• Customers. Granting points, cashback or benefits changes a real customer's balance and is logged with the reason you pass. Use idempotency keys.
• Data. Tool responses contain your account's marketing data, order aggregates, customer e-mails on the loyalty ledgers and creative assets. Whatever your AI client does with a tool response is governed by that client's own policy; Loyalz does not send your data to any model vendor as a side effect of a tool call.
• Limits. Studio calls that trigger vision or generation work are throttled per account; a throttled call returns a retry hint instead of failing silently. Live Meta reads on one ad account are spaced at least 8 seconds apart, so a large request takes a while.

For directory reviewers and integrators

• First-party API. The server runs on api.loyalz.io, the same backend that serves the Loyalz merchant panel. Every tool reads or writes the merchant's own Loyalz account; the Google Ads and Meta read-live tools also read the merchant's own ad accounts, through the connection the merchant made in Loyalz, and nothing else.
• Accounts and plans. A merchant account is required (book a demo to get one). Insights tools need Insights enabled on the account; Creative Studio tools need the Shark plan. A fully provisioned test account can be issued for review on request to majewski@loyalz.io.
• Read and write are separate tools. There is no catch-all request tool; each tool does one thing and is marked above as read, writes, or spends credits. Writes take an idempotency key. The Google Ads and Meta read-live tools also carry readOnlyHint: true in tools/list.
• Side effects with money or reach. Studio generation tools spend prepaid credits. studio_publish creates paused ads only. Calendar tools write drafts; calendar_approve_post is the only tool that lets a post publish, and it is meant for an explicit request from the user. Nothing moves money, changes a subscription or sends messages to customers.
• Known limitations. One merchant per token; no account switching inside a session. Studio vision and generation calls are throttled per account. Ad-platform data is as fresh as the last sync (daily, with intraday syncs for the store), except in the Google Ads and Meta read-live tools, which ask the platform at call time.
• Categories. Marketing analytics · Advertising · E-commerce · Loyalty and CRM · Creative production · Social media scheduling.

Privacy, terms and support

• Privacy policy: loyalz.io/legal/privacy/
• Terms: loyalz.io/legal/terms/ and terms for brands
• Deleting your data, including Meta data: loyalz.io/legal/data-deletion/
• Support and listing questions: majewski@loyalz.io; privacy matters: privacy@loyalz.io
• Status of the server: this page is updated when the catalog changes; the current build answers tools/list with 113 tools.

Changelog

• 2026-10-28 — Catalog now 113 tools. Meta Ads read live in Insights (2 tools): insights rows with placements, demographics, new vs returning customers and hour of day, and the fields of one ad set, campaign, ad account, pixel or an ad set's audience-size estimate. Both refuse fields outside an allow-list. The Google Ads and Meta read-live tools carry readOnlyHint in tools/list.
• 2026-10-24 — Catalog now 111 tools. Google Ads read live in Insights (5 tools): search terms, campaign settings, conversion actions, bid strategies and a read-only GAQL query. Creative Studio says what the brand profile is missing and refuses a paid run on an incomplete profile until the user confirms it; approving prompts can put the brand's logo on the images.
• 2026-10-23 — Catalog now 106 tools. Content Calendar (14 tools); campaigns, individual ads and live reach in Insights (3 tools); in Creative Studio (12 tools) the brand playbook, coverage map, audiences, brand brief, logo placement, ad-copy compliance check and the results of published ads.
• 2026-09-23 — Creative Studio (43 tools) added; authentication is header-only, the ?token= query parameter was retired; catalog now 77 tools.
• 2026-07-17 — Insights tools: metric catalog, query engine, dashboards and calculated metrics.
• 2026-06 — First public version: loyalty programme tools.

Get a merchant account Read: why one MCP for ads and the store