# MCP server

> Connect Claude, ChatGPT, Cursor, VS Code, Codex, or any MCP client to BloomText with the BloomText MCP server.

Source: https://www.bloomtext.com/developers/api/mcp/

The BloomText MCP server lets any [Model Context Protocol](https://modelcontextprotocol.io) client read and send BloomText messages. It's a remote server, so there's nothing to install: point your client at the URL and authenticate with an API key. The agent gets exactly the scopes and conversations that key has.

```text filename="Server URL"
https://mcp.bloomtext.com/mcp
```

## Connect your client

Replace `YOUR_BLOOMTEXT_API_KEY` with a key from an app user created for the agent. Don't have one? [Request API access](https://calendly.com/tyler-bloom/bloomtext-homepage-demo-request?utm_campaign=api-access).

Run this once in your terminal:

```bash filename="Terminal"
claude mcp add --transport http bloomtext https://mcp.bloomtext.com/mcp \
  --header "Authorization: Bearer YOUR_BLOOMTEXT_API_KEY"
```

Check it's connected with `claude mcp list`, or type `/mcp` inside Claude Code.

In Claude on the web or desktop:

1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Name it `BloomText` and paste `https://mcp.bloomtext.com/mcp` as the URL.
3. Under advanced settings, add the header `Authorization: Bearer YOUR_BLOOMTEXT_API_KEY`.
4. Enable the connector in a chat from the tools menu.

> **Warning:** Claude.ai connectors run on Anthropic's infrastructure. Confirm your organization has a BAA with Anthropic before connecting a key that can read patient conversations.

In ChatGPT with developer mode enabled for your workspace:

1. Open **Settings → Connectors → Create**.
2. Name it `BloomText`, set the MCP server URL to `https://mcp.bloomtext.com/mcp`, and choose header authentication.
3. Paste `Bearer YOUR_BLOOMTEXT_API_KEY` as the `Authorization` value.
4. Turn the connector on in a conversation.

> **Warning:** Confirm your OpenAI workspace is covered by a BAA before connecting a key that can read patient conversations.

Use the **Add to Cursor** button above, or add this to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project):

```json filename=".cursor/mcp.json"
{
  "mcpServers": {
    "bloomtext": {
      "url": "https://mcp.bloomtext.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_BLOOMTEXT_API_KEY" }
    }
  }
}
```

Use the **Add to VS Code** button above, or add this to `.vscode/mcp.json`. VS Code prompts for the key the first time and stores it securely:

```json filename=".vscode/mcp.json"
{
  "inputs": [
    { "type": "promptString", "id": "bloomtext-key", "description": "BloomText API key", "password": true }
  ],
  "servers": {
    "bloomtext": {
      "type": "http",
      "url": "https://mcp.bloomtext.com/mcp",
      "headers": { "Authorization": "Bearer ${input:bloomtext-key}" }
    }
  }
}
```

Add the server to `~/.codex/config.toml`, reading the key from your environment:

```toml filename="~/.codex/config.toml"
[mcp_servers.bloomtext]
url = "https://mcp.bloomtext.com/mcp"
bearer_token_env_var = "BLOOMTEXT_API_KEY"
```

Then export `BLOOMTEXT_API_KEY` in the shell you start Codex from.

Any client that supports remote MCP servers over Streamable HTTP works. Use this config shape:

```json filename="mcp.json"
{
  "mcpServers": {
    "bloomtext": {
      "type": "http",
      "url": "https://mcp.bloomtext.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_BLOOMTEXT_API_KEY" }
    }
  }
}
```

For clients that only speak stdio, bridge with `mcp-remote`:

```bash filename="Terminal"
npx mcp-remote https://mcp.bloomtext.com/mcp --header "Authorization: Bearer ${BLOOMTEXT_API_KEY}"
```

## Let your agent set it up

Paste this into your coding agent and it will wire up the server for you:

**Set up the BloomText MCP server:**

```text
Add the BloomText MCP server to this project. It's a remote Streamable HTTP server at https://mcp.bloomtext.com/mcp that authenticates with the header 'Authorization: Bearer <key>'. Read the key from the BLOOMTEXT_API_KEY environment variable and never hard-code it. Setup docs: https://www.bloomtext.com/developers/api/mcp.md
```

## Tools

Each tool maps to one API endpoint and requires the same [scope](https://www.bloomtext.com/developers/api/authentication/#scopes). The agent only sees tools its key's scopes allow.

| Tool | Does | Scope |
| --- | --- | --- |
| `get_organization` | Returns the organization the key belongs to. | `organization:read` |
| `list_users` | Lists organization members. | `users:read` |
| `list_conversations` | Lists conversations the app user is in. | `conversations:read` |
| `get_conversation` | Returns one conversation. | `conversations:read` |
| `list_messages` | Reads messages in a conversation, newest page first. | `messages:read` |
| `list_replies` | Reads a message's thread. | `messages:read` |
| `send_message` | Sends a message or threaded reply. | `messages:write` |
| `add_reaction` | Reacts to a message. | `reactions:write` |
| `remove_reaction` | Removes the app user's reaction. | `reactions:write` |
| `list_participants` | Lists who is in a conversation. | `participants:read` |
| `list_broadcasts` | Lists broadcasts and their status. | `broadcasts:read` |
| `create_export` | Starts a conversation export. | `exports:write` |
| `get_export` | Checks an export and returns its download URL. | `exports:read` |

`send_message` and `create_export` generate idempotency keys for you, so an agent retrying a tool call never sends twice.

## Use cases

Each prompt works as-is once the server is connected. Swap in your own conversation names.

<details>
<summary>Morning catch-up</summary>

Summarize overnight messages so the front desk starts the day knowing what needs a reply.

**Morning catch-up:**

```text
Read the messages sent since 6pm yesterday in every conversation you can see. Group them into: needs a staff reply, already handled, and FYI. Keep patient details out of the summary; use conversation names only.
```

</details>

<details>
<summary>Schedule change notice</summary>

Post a change to a staff group and acknowledge the request that prompted it.

**Schedule change:**

```text
Reply in the Scheduling group thread: 'Dr. Lee's 2pm is moved to 3pm today.' Then react 👍 to the original request so staff know it's handled.
```

</details>

<details>
<summary>Handoff triage</summary>

Find patient messages that need a person and route them to the right staff group.

**Handoff triage:**

```text
Find messages from the last 2 hours that ask a clinical question or mention a problem. For each, post 'Needs a staff reply' with the conversation name in the Front Desk group. Don't reply to the patient yourself.
```

</details>

<details>
<summary>Unanswered messages</summary>

Catch conversations where the last word is still the patient's.

**Unanswered messages:**

```text
List conversations where the most recent message is from someone outside our staff and is older than 1 hour. Show the conversation name and how long it's been waiting.
```

</details>

<details>
<summary>Records export</summary>

Package a conversation's history for the chart or a records request.

**Records export:**

```text
Export last month's messages from the Intake conversation and give me the download link when it's ready.
```

</details>

<details>
<summary>Care team check</summary>

Make sure the right people are in a conversation.

**Care team check:**

```text
List the participants in the Johnson family care team conversation and tell me if anyone from the Nursing group is missing.
```

</details>

## Agent skill

The [BloomText API skill](https://www.bloomtext.com/developers/api/skills/bloomtext-api/SKILL.md) teaches an agent the API's rules: authentication, idempotency, pagination, error codes, and what never to send. Agents that support [Agent Skills](https://agentskills.io) load it automatically when a task involves BloomText.

```bash filename="Terminal"
mkdir -p .claude/skills/bloomtext-api
curl -o .claude/skills/bloomtext-api/SKILL.md https://www.bloomtext.com/developers/api/skills/bloomtext-api/SKILL.md
```

```bash filename="Terminal"
mkdir -p ~/.codex/skills/bloomtext-api
curl -o ~/.codex/skills/bloomtext-api/SKILL.md https://www.bloomtext.com/developers/api/skills/bloomtext-api/SKILL.md
```

Download [SKILL.md](https://www.bloomtext.com/developers/api/skills/bloomtext-api/SKILL.md) into your agent's skills folder, or paste it into its system instructions.

## Safety

> **Warning:** An agent with `messages:write` can post as your app user in every conversation it's in. Start with read-only scopes, add the app user only to the conversations the agent needs, and review what it sends before widening access.

- Messages the agent sends appear under its app user's name, so staff always know what came from it.
- An organization admin can revoke the key or remove the app user at any time.
- Keep patient data inside tools covered by a BAA. See [Security and BAA](https://www.bloomtext.com/developers/api/security-and-baa/).

For building your own agent loop on the REST API instead, see [Build an AI agent](https://www.bloomtext.com/developers/api/ai-agents/).