> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect AI tools to the Brightalk API through the remote MCP endpoint.

Brightalk MCP lets an AI tool that supports remote MCP call the same operations as the REST API: contacts, AI calls, batches, large tasks, Automation runs, call results, recordings, LINE messages, and SMS. It uses the same organization API keys, scopes, and limits.

## Endpoint

The endpoint is `https://api.brightalk.ai/mcp`, served over Streamable HTTP. Every request must carry a `bt_live_` key from [Brightalk API settings](https://www.brightalk.ai/settings/integrations/api) in the `Authorization` header as a bearer token, exactly as described in [Authentication and scopes](https://docs.brightalk.ai/en/authentication.md). A request without a well-formed key returns `401`.

Keep the key in an environment variable named `BRIGHTALK_API_KEY` on the machine that runs your AI tool. The examples below read it from there, so no configuration file contains the key.

## Read-only mode

Use `https://api.brightalk.ai/mcp?read_only=true` to hide every tool that writes data, places calls, or sends messages. The scopes on the key still decide what each remaining tool may read.

## Claude Code

Add this entry to `.mcp.json` in your project root. Claude Code replaces the placeholder with the value of the environment variable when it starts.

```json theme={null}
{
  "mcpServers": {
    "brightalk": {
      "type": "http",
      "url": "https://api.brightalk.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${BRIGHTALK_API_KEY}"
      }
    }
  }
}
```

## Codex

Add this entry to `~/.codex/config.toml`. `bearer_token_env_var` takes the name of the environment variable, not the key itself.

```toml theme={null}
[mcp_servers.brightalk]
url = "https://api.brightalk.ai/mcp"
bearer_token_env_var = "BRIGHTALK_API_KEY"
```

## Other clients

Any client that supports remote MCP and custom request headers can connect. Enter the endpoint URL and send the key in the `Authorization` header as a bearer token. Connectors that only offer OAuth sign-in cannot connect.

## Scopes and limits

A tool call is an API request made with your key. It needs the same scope as the matching REST operation, counts against the same [rate limits](https://docs.brightalk.ai/en/rate-limits.md), and follows the same [idempotency](https://docs.brightalk.ai/en/idempotency.md) rules. Placing calls, starting batches, running Automations with call or message steps, and sending LINE messages or SMS can reach real people and incur charges. Creating a batch does not start dialing; queries and SMS preview do not send messages.

## SMS length and credits

Each part costs 1 credit. The carrier title, `[sender]` prefix, resolved variables and final short URL all count.

| Tool | Length and segment limits |
| - | - |
| `brightalk_create_sms`, `brightalk_create_sms_batch` | Multipart supported. Chinese, full-width symbols or line breaks allow 70 characters for one part, then 66 per part, up to 6 parts (396 characters). GSM allows 160 units for one part, then 152 per part, up to 912 units. |
| `brightalk_preview_sms`, `brightalk_send_sms` | Single-part contact-send path: at most 70 UTF-16 code units or 159 ASCII bytes; longer text is rejected. Preview neither sends nor charges and does not preview the multipart tools. |

71–132 UCS-2 characters cost 2 credits; 133–198 cost 3. GSM `^`, `{`, `}`, `[`, `]`, `~`, `|` and `\` each use 2 units. Line breaks, underscores `_` or backticks (U+0060) switch to UCS-2. Emoji/non-BMP characters are unsupported. See [SMS length and credits](https://docs.brightalk.ai/en/guides/personalized-notifications.md#sms-length-and-credits) for the full rules.

## Lists above 1,000 recipients

Standard call and SMS batches accept up to 1,000 recipients. For larger lists, use a [large SMS or call task](https://docs.brightalk.ai/en/guides/large-tasks.md) with up to 100,000 recipients:

1. Create the task with `brightalk_create_bulk_task`.
2. Upload the complete list with `brightalk_upload_bulk_task_chunk`, up to 1,000 recipients per request.
3. Explicitly start background processing with `brightalk_start_bulk_task`.
4. Query overall progress with `brightalk_get_bulk_task`, and use `brightalk_list_bulk_task_parts` to find individual batch results.

Creating and uploading a task do not send SMS or place calls. Starting it authorizes execution at the configured time; a successful start response does not mean the work is complete. A completed task can include failed results. Read-only mode exposes the progress queries but hides create, upload, and start tools.

## Current limits

* Sign-in is by API key only. OAuth sign-in is not available.
* Within a mode, every key sees the same tool list. Read-only mode includes queries and SMS preview. Listing tools checks only the key's format; make a real query to verify that the key is valid and has the required scope.
* Each request is independent. The server keeps no session between requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.