# Botstar — how to use (mcp.ai)

Connect your Botstar account and use 31 tools for AI chatbots straight from your AI agent. Connect with your own API key. BotStar is a comprehensive chatbot platform that enables businesses to design, develop, and train chatbots visually for Messenger and websites.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_botstar?ms=1787291520000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `botstar_create_bot`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/botstar`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/botstar/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/botstar/create/bot` — Tool to create a new bot in BotStar. Use when you need to create a new bot instance with a specific name.
  - body: { name: string }
- `POST https://api.mcp.ai/api/botstar/create/bot/attribute` — Tool to create a new bot attribute in BotStar. Bot attributes are global variables for a bot and support multilingual values. Use when you need to define custom data fields for your bot.
  - body: { env?: string, desc?: string, name: string, value?: string, bot_id: string, data_type: string, additional_values?: object }
- `POST https://api.mcp.ai/api/botstar/create/cms/entity` — Tool to create a CMS entity in BotStar with a name and optional fields. Use when you need to define a new content structure with custom fields supporting various data types.
  - body: { env?: string, name: string, bot_id: string, fields?: object[] }
- `POST https://api.mcp.ai/api/botstar/create/entity/fields` — Tool to create entity field(s) in BotStar CMS. Supports multiple field types including text, multiple_values, single_option, multiple_options, image, date, and entity. Use when you need to add new fie
  - body: { env?: string, botId: string, fields: object[], entityId: string }
- `POST https://api.mcp.ai/api/botstar/create/entity/item` — Tool to create a new entity item in BotStar CMS. Use when adding items to a CMS entity with custom field values.
  - body: { env?: string, name: string, bot_id: string, status?: string, entity_id: string, additional_fields?: object }
- `POST https://api.mcp.ai/api/botstar/create/user/attributes` — Tool to create custom user attributes in BotStar. Use when you need to define new custom attributes for users with specified field name and type.
  - body: { bot_id: string, field_name: string, field_type: string }
- `POST https://api.mcp.ai/api/botstar/delete/bot/attribute` — Tool to delete a bot attribute by ID. Use when you need to remove a custom attribute from a bot.
  - body: { env?: string, bot_id: string, attribute_id: string }
- `POST https://api.mcp.ai/api/botstar/delete/cms/entity` — Tool to delete a CMS entity by ID. Use when you need to remove an entity from the bot's content management system.
  - body: { env?: string, bot_id: string, entity_id: string }
- `POST https://api.mcp.ai/api/botstar/delete/entity/fields` — Tool to delete entity field(s) from a CMS entity. Use when you need to remove fields from a CMS entity by their unique names.
  - body: { env?: string, bot_id: string, entity_id: string, unique_names?: string }
- `POST https://api.mcp.ai/api/botstar/delete/entity/item` — Tool to delete an entity item from a CMS entity. Use when you need to remove a specific item from a bot's CMS entity.
  - body: { env?: string, bot_id: string, entity_id: string, entity_item_id: string }
- `POST https://api.mcp.ai/api/botstar/get/bot` — Tool to get your bot by bot ID. Use when you need detailed bot information including ID, name, and team name.
  - body: { bot_id: string }
- `POST https://api.mcp.ai/api/botstar/get/bot/app/id` — Tool to retrieve the BotStar application ID (`appId`). Use when initializing or reinitializing the live chat widget.
  - body: { bot_id?: integer, bot_name?: string }
- `POST https://api.mcp.ai/api/botstar/get/cms/entity` — Tool to get a specific CMS entity by ID. Returns entity details including fields configuration. Use when you need to retrieve metadata about a CMS entity structure.
  - body: { env?: string, bot_id: string, entity_id: string }
- `POST https://api.mcp.ai/api/botstar/get/entity/item` — Tool to retrieve a specific item from a CMS entity with all field values. Use when you need to get detailed information about a single entity item.
  - body: { env?: string, bot_id: string, entity_id: string, entity_item_id: string }
- `POST https://api.mcp.ai/api/botstar/list/bot/attributes` — Tool to get all bot attributes from BotStar. Returns array of bot attributes with id, name, desc, value, and data_type. Use when you need to retrieve or inspect all attributes configured for a bot.
  - body: { env?: string, bot_id: string }
- `POST https://api.mcp.ai/api/botstar/list/bots` — Tool to get your list of bots. Use when you need to retrieve all bots associated with your account. Returns an array of bots with their id, name, and team_name.
  - body: { page?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/botstar/list/cms/entities` — Tool to retrieve all CMS entities for a bot. Use when you need to access entity definitions, field configurations, or available entity schemas.
  - body: { env?: string, botId: string }
- `POST https://api.mcp.ai/api/botstar/list/entity/items` — Tool to retrieve all entity items with pagination support. Use when you need to list CMS entity items, with optional filtering by name and status.
  - body: { env?: string, name?: string, page?: integer, limit?: integer, bot_id: string, status?: string, entity_id: string }
- `POST https://api.mcp.ai/api/botstar/livechat/boot` — Tool to reinitialize the live chat widget with provided data. Use after initial load to reset or update widget configuration.
  - body: { mode?: string, user?: object, appId: string, block?: string, variables?: object }
- `POST https://api.mcp.ai/api/botstar/livechat/close` — Tool to hide the live chat window. Use when the chat widget is configured in livechat or popup mode.
- `POST https://api.mcp.ai/api/botstar/livechat/on/close` — Tool to register a callback when the chat window is closed. Use after the widget is initialized. Example prompt: "Register an onClose handler that logs 'Goodbye!' to the console."
  - body: { callback_code: string }
- `POST https://api.mcp.ai/api/botstar/livechat/on/open` — Tool to register a callback when the chat window is opened. Use after widget initialization.
  - body: { callback: string }
- `POST https://api.mcp.ai/api/botstar/livechat/open` — Tool to show the live chat window. Use after the widget has been bootstrapped with BotStarApi('boot') to programmatically open the chat window (mode must be 'livechat' or 'popup').
- `POST https://api.mcp.ai/api/botstar/livechat/update` — Tool to update user details on the current live chat session. Use when you need to modify user profile attributes during an active conversation.
  - body: { tags?: string[], email?: string, avatar?: string, gender?: string, user_id?: string, birthday?: string, last_name?: string, first_name?: string }
- `POST https://api.mcp.ai/api/botstar/publish/bot` — Tool to publish a bot to live. Use when you need to deploy changes to the production environment.
  - body: { bot_id: string }
- `POST https://api.mcp.ai/api/botstar/update/bot/attribute` — Tool to update a bot attribute in BotStar. Use when you need to modify the description or value of a bot attribute with optional multilingual support.
  - body: { env?: string, desc?: string, value?: string|integer|number, bot_id: string, attribute_id: string }
- `POST https://api.mcp.ai/api/botstar/update/cms/entity` — Tool to update a CMS entity in BotStar. Use when you need to modify the name or configuration of an existing CMS entity.
  - body: { env?: string, name: string, bot_id: string, entity_id: string }
- `POST https://api.mcp.ai/api/botstar/update/entity/fields` — Tool to update entity field(s) in BotStar CMS. Use when you need to modify the name or options of existing fields.
  - body: { env?: string, bot_id: string, fields: object[], entity_id: string }
- `POST https://api.mcp.ai/api/botstar/update/entity/item` — Tool to update a CMS entity item in BotStar. Use when you need to modify the name, status, or custom field values of an entity item.
  - body: { env?: string, name?: string, bot_id: string, status?: string, entity_id: string, custom_fields?: object, entity_item_id: string }
- `POST https://api.mcp.ai/api/botstar/webview/get/parameter` — Tool to retrieve a parameter value passed from the BotStar chatbot to the webview. Use inside onChatBotReady after your page loads in modal mode with bs:input meta tags.
  - body: { parameter_name: string }
- `POST https://api.mcp.ai/api/botstar/webview/send/response` — Tool to send data from the webview back to the BotStar chatbot. Use when you need to transmit responses or custom outputs from an open webview.
  - body: { outputs: object, response: string, outlet_name: string }

## Example prompts
- "What can I do in Botstar?"
- "Show me a summary of my Botstar account"

## More
- Page: https://mcp.ai/botstar
- Agent spec (llms.txt): https://mcp.ai/botstar/llms.txt
- Postman collection: https://mcp.ai/botstar/postman.json