> ## 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

> 透過遠端 MCP 端點，讓 AI 工具使用 Brightalk API。

Brightalk MCP 讓支援遠端 MCP 的 AI 工具呼叫與 REST API 相同的操作：聯絡人、AI 通話、批次撥號、大型任務、自動化執行、通話結果、錄音、LINE 訊息與簡訊。它使用同一組組織 API 金鑰、權限範圍與限制。

## 端點

端點是 `https://api.brightalk.ai/mcp`，以 Streamable HTTP 提供。每個請求都必須在 `Authorization` 標頭以 bearer 權杖帶上在 [Brightalk API 設定](https://www.brightalk.ai/settings/integrations/api)建立的 `bt_live_` 金鑰，方式與[身分驗證與權限範圍](https://docs.brightalk.ai/zh-Hant/authentication.md)相同。沒有帶格式正確金鑰的請求會傳回 `401`。

請把金鑰放在執行 AI 工具那台機器的環境變數 `BRIGHTALK_API_KEY`。下方範例都從這個變數讀取，所以設定檔裡不會出現金鑰。

## 唯讀模式

使用 `https://api.brightalk.ai/mcp?read_only=true` 可以隱藏所有會寫入資料、撥打電話或發送訊息的工具。其餘工具能讀取什麼，仍由金鑰的權限範圍決定。

## Claude Code

將這個項目加入專案根目錄的 `.mcp.json`。Claude Code 啟動時會把佔位符號換成環境變數的值。

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

## Codex

將這個項目加入 `~/.codex/config.toml`。`bearer_token_env_var` 填的是環境變數的名稱，不是金鑰本身。

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

## 其他客戶端

任何支援遠端 MCP 與自訂請求標頭的客戶端都能連線。填入端點網址，並在 `Authorization` 標頭以 bearer 權杖傳送金鑰。只提供 OAuth 登入的連接器無法連線。

## 權限範圍與限制

每一次工具呼叫，都是以您的金鑰發出的一個 API 請求。它需要與對應 REST 操作相同的權限範圍，計入相同的[速率限制](https://docs.brightalk.ai/zh-Hant/rate-limits.md)，並遵守相同的[冪等性](https://docs.brightalk.ai/zh-Hant/idempotency.md)規則。發起通話、啟動批次、執行含通話或訊息步驟的自動化，以及發送 LINE 訊息或簡訊，都可能聯絡到真人並產生費用。建立批次本身不會開始撥號；查詢與簡訊預覽不會發送訊息。

## 簡訊字數與點數

每段簡訊扣 1 點，電信抬頭、`[署名]`、變數代入後的文字及最終短網址都計入。

| 工具 | 字數與分段限制 |
| - | - |
| `brightalk_create_sms`、`brightalk_create_sms_batch` | 支援長簡訊。含中文、全形符號或換行時，單封 70 字；超過後每段 66 字，最多 6 段（396 字）。純 GSM 單封 160 單位；長簡訊每段 152 單位，最多 912 單位。 |
| `brightalk_preview_sms`、`brightalk_send_sms` | 單封聯絡人發送管道。最多 70 個 UTF-16 單位或 159 ASCII bytes，超過就會拒絕。預覽不發送、不扣點，也不適用於長簡訊工具。 |

71–132 個中文編碼字元扣 2 點，133–198 個扣 3 點。GSM 的 `^`、`{`、`}`、`[`、`]`、`~`、`|`、`\` 各佔 2 單位；換行、底線 `_` 或反引號（U+0060）會改用中文編碼。不支援 emoji／非 BMP 字元。完整規則見[簡訊字數與扣點](https://docs.brightalk.ai/zh-Hant/guides/personalized-notifications.md#sms-length-and-credits)。

## 名單超過 1,000 筆

一般撥號與簡訊批次最多接受 1,000 筆名單。更多名單請使用[大型簡訊或撥號任務](https://docs.brightalk.ai/zh-Hant/guides/large-tasks.md)，每個任務最多 10 萬筆：

1. 用 `brightalk_create_bulk_task` 建立任務。
2. 用 `brightalk_upload_bulk_task_chunk` 上傳完整名單，每次最多 1,000 筆。
3. 用 `brightalk_start_bulk_task` 明確啟動背景處理。
4. 用 `brightalk_get_bulk_task` 查詢整體進度，再用 `brightalk_list_bulk_task_parts` 找到各批次結果。

只建立任務或上傳名單不會發送簡訊或撥號。啟動代表授權系統依設定時間執行；啟動成功不代表處理完成，任務完成也可能包含失敗結果。唯讀模式提供進度查詢，但會隱藏建立、上傳與啟動工具。

## 目前的限制

* 只能以 API 金鑰登入，尚未提供 OAuth 登入。
* 同一模式下，每把金鑰看到的工具清單都相同；唯讀模式包含查詢與簡訊預覽。列出工具只檢查金鑰格式；金鑰是否有效及具備所需權限範圍，要透過實際查詢確認。
* 每個請求各自獨立，伺服器不會在請求之間保留工作階段。


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