Skip to main content
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 in the Authorization header as a bearer token, exactly as described in Authentication and scopes. 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.

Codex

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

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, and follows the same idempotency 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. 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 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 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.