# AI agents (MCP) (/docs/developers/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](/docs/developers/api-tokens) you create lets it see, and it can't change anything.

## What you need [#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](#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](#connect-with-sign-in-with-bloss). Others, such as Claude Code or Cursor, can also use an [API token](/docs/developers/api-tokens) or a [brand key](#connect-with-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 [#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.

<Steps>
<Step>

### Add Bloss as a connector [#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.

</Step>
<Step>

### Sign in and choose permissions [#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**.

</Step>
<Step>

### Ask a question [#ask-a-question]

You're back in the app, connected. Ask about your Bloss data.

</Step>
</Steps>

To change what an app can read, connect it again and choose different permissions. To cut it off, go to <UiPath>Account › Connected apps</UiPath>, click **Disconnect** next to the app and confirm with **Disconnect**: it loses access at once.

## Connect with a token [#connect-with-a-token]

<Steps>
<Step>

### Create a token for the agent [#create-a-token-for-the-agent]

Go to <UiPath>Account › API tokens</UiPath> 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](/docs/developers/api-tokens).

</Step>
<Step>

### Add the Bloss server to your client [#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.json` it 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_…`.

<Tabs items={['Claude Code', 'Cursor', 'VS Code', 'Claude Desktop', 'Other clients']}>
<Tab>

Run this in a terminal:

```bash
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.

</Tab>
<Tab>

Add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:

```json title="mcp.json"
{
  "mcpServers": {
    "bloss": {
      "url": "https://www.bloss.app/api/mcp",
      "headers": {
        "Authorization": "Bearer blsp_…"
      }
    }
  }
}
```

Keep this file out of version control if it holds your token.

</Tab>
<Tab>

Add the server to `.vscode/mcp.json` in your project, or run **MCP: Open User Configuration** from the Command Palette for every project:

```json title="mcp.json"
{
  "servers": {
    "bloss": {
      "type": "http",
      "url": "https://www.bloss.app/api/mcp",
      "headers": {
        "Authorization": "Bearer blsp_…"
      }
    }
  }
}
```

Keep this file out of version control if it holds your token.

</Tab>
<Tab>

Claude Desktop's config file starts local servers only, so it reaches Bloss through `mcp-remote`, which needs [Node.js](https://nodejs.org). Open <UiPath>Settings › Developer › Edit Config</UiPath> and add this to `claude_desktop_config.json`:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "bloss": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.bloss.app/api/mcp", "--header", "Authorization:${BLOSS_AUTH}"],
      "env": {
        "BLOSS_AUTH": "Bearer blsp_…"
      }
    }
  }
}
```

Restart Claude Desktop. To skip the token, add Bloss as a custom connector instead and use [Sign in with Bloss](#connect-with-sign-in-with-bloss).

</Tab>
<Tab>

Add a remote (HTTP) MCP server with the URL `https://www.bloss.app/api/mcp` and the header `Authorization: Bearer blsp_…`. The exact steps depend on your client: look for "add MCP server" in its settings or docs.

A client that can only sign in through a browser uses [Sign in with Bloss](#connect-with-sign-in-with-bloss) instead.

</Tab>
</Tabs>

</Step>
<Step>

### Ask a question [#ask-a-question-1]

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.

</Step>
</Steps>

## What the agent can do [#what-the-agent-can-do]

The agent reads the same data as the [Platform API](/docs/developers/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](#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 [#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](/docs/developers/platform-api#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 `forbidden` for a limited admin, whatever the token's permissions. See [Full vs limited admins](/docs/brands/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 [#connect-with-a-brand-key]

A [brand key](/docs/developers/api-tokens#brand-keys) (`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 <UiPath>Settings › Integrations › API Keys</UiPath>, next to **Brand ID**.

## What it can't do [#what-it-cant-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 [#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](/docs/developers/platform-api#rate-limits).
- **Turn it off any time.** Revoke the token in <UiPath>Account › API tokens</UiPath>, or the brand key in <UiPath>Settings › Integrations › API Keys</UiPath>, and the agent loses access right away.

## Troubleshooting [#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](/docs/agencies/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 [#related]

- [API tokens](/docs/developers/api-tokens)
- [Platform API](/docs/developers/platform-api)
- [Use your data with AI agents](/docs/creators/tools/api-and-ai-agents) (creators)
- [Use your coaching data with AI agents](/docs/coaches/api-and-ai-agents) (coaches)
- [Use your brand's data with AI agents](/docs/brands/settings/api-and-ai-agents) (brand admins)