Connecting AI Assistants (Beta)
Beta. The MCP server is in beta: its tools and their results may change as we improve it.
Our Model Context Protocol (MCP) server lets AI assistants such as Claude work with the posts, the asset library and the loyalty programs of your teams on your behalf. Once it's connected, you can ask questions like:
- How many points did members earn and redeem each month this year, and what share of the points earned was redeemed?
- Who are the 10 members with the most available points who have never redeemed a reward? Include their tier and email address.
- How many members joined each month this year, by tier, and how many points do they hold in total?
- Who were our top 5 Instagram creators this quarter by number of posts, and what's the sentiment of what they post?
- Find last month's 5-star reviews that mention shipping, and summarize what customers liked about it.
- Find the images in our library that don't have alternative text yet, write some for them, and tag them "reviewed".
The assistant chooses and combines the tools it needs to answer, and summarizes the results. It can only see and change what you can in TrueLoyal: every tool applies the same OAuth scopes, role permissions and access to boards and social feeds as the matching Advocacy API endpoints.
Connecting
Teams opt in to the MCP server: a member of the team with the team_security permission turns on mcp_enabled with
Update a team. Assistants can only access the teams that turned it on.
The server is served from https://mcp.trueloyal.com over the Streamable HTTP transport and authenticates with
OAuth 2.0, like the Advocacy API. To connect an assistant, add a custom connector (or MCP server) with that URL, then
sign in with your TrueLoyal account and authorize it when the assistant asks you to. For example, in Claude, go to
Settings, then Connectors, and choose Add custom connector; in Claude Code, run:
claude mcp add --transport http trueloyal https://mcp.trueloyal.comAssistants register themselves as OAuth applications when they connect, so you don't need to create one. We support Claude (including Claude Desktop, Cowork and Claude Code), ChatGPT, Grok, GitHub Copilot (in VS Code, JetBrains, Eclipse and Xcode), Cursor, the Gemini CLI, the OpenAI Codex CLI, Goose and the MCP Inspector. The server only accepts the access tokens of these assistants, not those of the OAuth applications you create for the API, so that access for AI assistants stays separate from your integrations. To use another assistant, contact us.
Scopes
Each tool requires the scope of the endpoint it mirrors, so grant the ones you want the assistant to use:
| Tools | Scope | Permission of your role |
|---|---|---|
search_posts, aggregate_posts, get_post | posts:read | |
update_posts | posts:write | moderate_tint |
list_teams | teams:read | |
list_tints | tints:read | |
list_social_feeds | social_feeds:read | |
list_saved_filters | saved_filters:read | |
list_accounts | accounts:read | accounts_read |
search_assets, aggregate_assets, get_asset | assets:read | assets_read |
update_assets | assets:write | assets_edit, and assets_archive to archive or restore assets |
list_collections | collections:read | assets_read |
search_members, aggregate_members, get_member | people:read | people_r |
list_member_attributes, list_transaction_attributes | schemas:read | schemas_r |
list_rewards | rewards:read | rewards_r |
list_activities | activities:read | activities_r |
search_transactions, aggregate_transactions, get_transaction | transactions:read | transactions_r |
These tools are in early access, and are only available to teams in our early access program:
| Tools | Scope | Permission of your role |
|---|---|---|
create_member_attribute, create_transaction_attribute | schemas:write | schemas_cu |
create_activity, update_activity | activities:write | activities_cu |
create_reward, update_reward, create_coupons | rewards:write | rewards_cu |
list_coupons | rewards:read | rewards_r |
list_rules | activities:read or rewards:read, for the rules of activities or rewards | activities_r or rewards_r |
create_rule, update_rule, update_default_rule | activities:write or rewards:write, for the rules of activities or rewards | activities_cu or rewards_cu |
list_tiers | tiers:read | |
create_tier_settings, create_tier, update_tier | tiers:write | |
list_forms | forms:read | forms_r |
Updating posts and assets
update_posts changes the status (public, private or deleted by moderation), status reasons, tags, alternative text,
highlighting and pinning of the posts it's given, like moderating them in TrueLoyal. update_assets adds and removes
tags and collections, sets the title, description and alternative text, and archives or restores the assets it's given.
Both take the IDs of up to 250 posts or assets at a time, which the assistant finds with search_posts or
search_assets first, and never delete anything permanently, so updating them again undoes their changes. They're
marked as destructive, so clients that support it ask you to confirm before using them.
Assistants only see the assets in your library that aren't in a collection, or that are in at least one collection your role gives you access to.
Limits
To keep the server fast for everyone, it limits how often assistants can call it, per minute:
| Limit | Calls a minute |
|---|---|
| Requests of each user | 120 |
| Tool calls for each team | 600 |
Searches for each team (search_*, aggregate_*, get_member, get_transaction, list_member_attributes and list_transaction_attributes) | 60 |
Aggregations for each team (aggregate_*), which also count as searches | 20 |
Changes by each user (update_posts, update_assets and the other tools that change records) | 20 |
When a tool call goes over a limit, the assistant is told how many seconds to wait and can try again. Requests over the
limit of each user get a 429 Too Many Requests response with a Retry-After header. Tools can also be temporarily
unavailable, for example during maintenance, in which case the assistant is asked to try again later.
What the data covers
The assistant works with the data we already collect and compute for your posts:
- The sentiment of posts is computed from their text and is positive, neutral or negative.
- The objects seen in images (such as person or cat) are only available to teams with image recognition enabled.
- Posts aren't classified by topic. Assistants group them by hashtag or tag instead, or read a sample of them to find the themes they have in common.
- Creators are ranked by the number of posts they published: engagement (likes, comments and shares) isn't available.
- Times are grouped in the time zone the assistant asks for, which it takes from you or defaults to UTC.