AI agents (MCP)
Connect Claude, Cursor and other AI agents to the Bloss MCP server so they can read your Bloss data, or your brand's, and answer questions about it.
Bloss runs an MCP (Model Context Protocol) server, so an AI agent such as Claude or Cursor can read your Bloss data and answer questions like "how much did I earn this month?" or "which of my students haven't posted this week?". Brand admins of a brand on the Scale plan can also ask about their brand: "how did our campaign do this week?". The agent sees what an API token you create lets it see, and it can't change anything.
What you need
- A Bloss account. The MCP server is free for creators and coaches. Brand tools need a brand on the Scale plan (see Brand tools).
- An MCP client that connects to a remote server over HTTP. Clients that support sign-in (Claude and ChatGPT connectors, for example) connect with Sign in with Bloss. Others, such as Claude Code or Cursor, can also use an API token or a brand key in a header.
| Setting | Value |
|---|---|
| Server URL | https://www.bloss.app/api/mcp |
| Transport | HTTP (Streamable HTTP) |
| Sign-in | Sign in with Bloss (OAuth), or the header Authorization: Bearer blsp_… |
Connect with Sign in with Bloss
Use this in apps that add MCP servers as connectors, such as Claude or ChatGPT. You don't copy a token: you sign in to Bloss and choose what the app may read.
Add Bloss as a connector
In the app's settings, add a custom connector (or remote MCP server) with the URL https://www.bloss.app/api/mcp. The exact steps depend on the app.
Sign in and choose permissions
The app opens Bloss. Sign in if you need to. Bloss shows which app is asking, the site it will send you back to, and the permissions it wants. Tick only what you want it to have, and optionally limit it to Only these brands. Money data (earnings, payouts) is never ticked unless the app asks for it. Click Allow.
Ask a question
You're back in the app, connected. Ask about your Bloss data.
To change what an app can read, connect it again and choose different permissions. To cut it off, go to AccountConnected apps, click Disconnect next to the app and confirm with Disconnect: it loses access at once.
Connect with a token
Create a token for the agent
Go to AccountAPI tokens and click Create token. Name it after the agent (for example "Claude"), and tick only the permissions you want it to have. Always include Your account: name, email, roles and memberships: the agent starts by reading it to learn which brands you belong to. For brand tools, also tick what you need under Brand (Scale plan). Click Create token. See API tokens.
Add the Bloss server to your client
The Token created window has a Connect an AI agent (MCP) section. Pick your app, and the setup is ready with your token already in it:
- Claude Code: copy the command and run it in a terminal.
- Cursor and VS Code: click Add to Cursor or Add to VS Code and confirm in the app, or copy the
mcp.jsonit shows. - Claude Desktop: copy the config into
claude_desktop_config.json. - Other: copy the config, or the server URL and header.
The token is shown only while that window is open. If you set up your client later, use the steps below with your token in place of blsp_….
Run this in a terminal:
claude mcp add --transport http --scope user bloss https://www.bloss.app/api/mcp \
--header "Authorization: Bearer blsp_…"--scope user adds Bloss for all your projects. Then start Claude Code and run /mcp to check that bloss is connected.
Ask a question
Ask the agent something about your Bloss data, for example "What are my earnings across brands?" or "Show my views per day in Glow Skincare for the last two weeks." The agent picks the right tools and tells you what it found.
What the agent can do
The agent reads the same data as the Platform API, within your token's permissions:
- Your account and the brands you belong to.
- Your creator profile, stats, brands and their posting rules, videos and daily views, bounties and Streak Survivor.
- Your earnings and payouts, if the token has the Money data permission.
- Your coaching workspace (students, notes, stages and rules), if you're a coach.
- The brands you administer, if they're on the Scale plan. See Brand tools.
Common questions have their own tools. For everything else, the agent searches the full list of read operations and runs the one it needs.
The server also offers ready-made prompts, if your app shows them: an earnings check, a video audit, a coach check-in, a weekly brand report and a campaign health check. It shares Bloss's reference pages too (key concepts, error codes and the list of operations), so the agent reads numbers the way Bloss means them.
Brand tools
If you're a brand admin, full or limited, of at least one brand on the Scale plan, the agent also gets brand tools: the Brand API as tools. Otherwise it doesn't see them at all. If your token is limited with Only these brands, at least one of the chosen brands must be on Scale.
The brand tools read what the token's Brand (Scale plan) permissions allow: the brand's settings and team, creators, videos, sets and tags, payout cycles and campaign reach, and with the money permissions, pay rules, payouts, campaign spend and funds.
| Ask | The agent reads |
|---|---|
| "How did Glow Skincare do this week?" | The current payout cycle, the campaign's videos and views for it, and per day, plus the roster and the week's videos by creator. |
| "Which creators are behind on posting?" | The roster, the brand's posting cadence, and each quiet creator's views per day and posting compliance. |
| "Which tags bring the most views?" | The brand's tags with their stats. |
| "Any new recruitment applications?" | Applications from the brand's recruitment page. |
| "How much of our 5,000 USD budget is left for the September and October cycles?" | Campaign spend for those cycles against the budget. Full admins only. |
| "What's waiting in the Base pay queue?" | The instant base pay queue. Full admins only. |
A few rules carry over from the API:
- Pay data needs a full admin. Money tools answer
forbiddenfor a limited admin, whatever the token's permissions. See Full vs limited admins. - Each brand must be on Scale. If you administer several brands, a tool asked about one that isn't on Scale answers
plan_required. - The subscription is the agency owner's. Anyone else gets
forbidden.
Connect with a brand key
A brand key (blsk_…) can connect too, in the same Authorization: Bearer header. Use one for an agent that belongs to the brand rather than to a person, for example a shared team assistant.
An agent on a brand key sees only brand tools, and only those the key's permissions allow. Every tool reads the key's own brand and nothing else. After you create the key, the API key created window shows the setup for your app with the key already in it, as for a token. It uses the server name bloss-brand, so a brand key and your own token can both be added to the same app. The Bloss server tells the agent the brand's id when it connects, so you don't have to. If you need it yourself, it's under SettingsIntegrationsAPI Keys, next to Brand ID.
What it can't do
Everything is read-only. The agent can't post, edit, delete, pay, approve or invite anything, and it can't change your settings. If you ask it to, it should tell you to do it in the Bloss app.
It also can't see more than you can: another creator's earnings, a brand you don't belong to, or anything outside your token's permissions.
Privacy and control
- The token decides what the agent sees. Leave Money data unticked if you don't want an agent reading your earnings or a brand's pay, and use Only these brands to keep it to some of your brands.
- What the agent reads goes to the agent's provider. Data the agent reads becomes part of your conversation with it, so the AI provider's own privacy terms apply to it.
- Payout details stay masked. The agent sees where you're paid and whether your account is set up, never full payment details.
- Requests count toward your rate limit. Agent calls share your limit with your other tokens. See Rate limits.
- Turn it off any time. Revoke the token in AccountAPI tokens, or the brand key in SettingsIntegrationsAPI Keys, and the agent loses access right away.
Troubleshooting
| What you see | What to do |
|---|---|
| The server won't connect, or says the token is missing, invalid, expired or revoked | Check the header is exactly Authorization: Bearer followed by your token. Create a new token if it expired or was revoked. |
| The agent says it needs a permission | Create a new token with that permission, and update your client's config. |
A tool says not_found | The brand or item isn't yours, or your token is limited to other brands. |
| The agent has no brand tools | None of the brands you administer (within Only these brands) is on the Scale plan, or the token has no Brand (Scale plan) permissions. |
A tool says plan_required | That brand isn't on the Scale plan. The agency owner can change it in agency billing. |
A tool says forbidden | Pay data needs a full admin, and the subscription the agency owner. |
A tool says rate_limited | Wait a minute and ask again. |
Related
- API tokens
- Platform API
- Use your data with AI agents (creators)
- Use your coaching data with AI agents (coaches)
- Use your brand's data with AI agents (brand admins)
Last reviewed Oct 23, 2026