MCP tools - Animam Documentation

The Animam MCP server exposes 25 tools. Each requires a scope granted to your API token (see Installation).

Tenant & branding

`get_tenant`

Get the current tenant configuration (bot persona, branding, limits) Required scope: settings:read No parameters.

`update_tenant`

Update tenant settings: bot persona (name, tone, lore), visual branding (avatar, colors), widget UX (teaser message, pulse, auto-open), domains, content policy. Required scope: settings:write

Parameter	Type	Required	Description
`botName`	string	No	Bot display name (max 50 chars)
`botTitle`	string	No	Bot role title
`botLore`	string	No	Bot background story
`botTone`	`FORMAL` / `NEUTRAL` / `FRIENDLY` / `PLAYFUL` / `TECHNICAL`	No
`useTutoiement`	boolean	No	Use tu instead of vous
`allowEmojis`	boolean	No
`botAvatar`	string	No	Bot avatar image URL (https, max 500 chars; null to clear)
`avatarType`	`DEFAULT` / `UPLOAD` / `LIBRARY` / `GENERATED`	No	Avatar source type
`primaryColor`	string	No	Hex color #RRGGBB
`secondaryColor`	string	No	Hex color or null
`showAiBadge`	boolean	No
`teaserText`	string	No	Widget teaser bubble message shown on first visit (null = i18n default by locale)
`autoOpen`	boolean	No	Auto-open the chat after a delay (default false)
`autoOpenDelay`	number	No	Seconds before auto-open / pulse (3-120, default 20)
`bubblePulse`	boolean	No	Pulse the bubble when the teaser appears (default true)
`allowedDomains`	array	No	CORS whitelist for widget embedding. Empty array = allow all origins. Supports exact (app.example.com), bare domain (example.com), and wildcard (*.example.com).
`contentPolicy`	`SFW_STRICT` / `SFW` / `MODERATE` / `UNFILTERED`	No	Content safety level (default: SFW)

External MCP tools

`get_mcp_tools`

Get the current external MCP server configuration (URL, max tools) Required scope: settings:read No parameters.

`update_mcp_tools`

Configure an external MCP server whose tools will be auto-discovered and available in chat. Set mcpToolsUrl to null to disconnect. Required scope: settings:write

Parameter	Type	Required	Description
`mcpToolsUrl`	string	No	MCP server URL (HTTPS required). Set to null to disconnect.
`mcpToolsApiKey`	string	No	Bearer token sent to the MCP server (encrypted at rest). Set to null to remove.
`mcpToolsMaxTools`	number	No	Max tools to import (1-20, default: 10)

Segments

`list_segments`

List all segments (contexts) for the tenant Required scope: segments:read No parameters.

`get_segment`

Get details of a specific segment Required scope: segments:read

Parameter	Type	Required	Description
`slug`	string	Yes

`update_segment`

Update a segment prompt, welcome message, or form config Required scope: segments:write

Parameter	Type	Required	Description
`slug`	string	Yes
`name`	string	No
`systemPrompt`	string	No
`welcomeMessage`	string	No
`formConfig`	object	No	Contact form configuration
`isActive`	boolean	No

`create_segment`

Create a new segment Required scope: segments:write

Parameter	Type	Required
`slug`	string	Yes
`name`	string	Yes
`systemPrompt`	string	Yes
`welcomeMessage`	string	No
`isDefault`	boolean	No

Knowledge base (corpus)

`list_corpus`

List knowledge base entries Required scope: corpus:read

Parameter	Type	Required	Description
`segmentSlug`	string	No	Filter by segment

`get_corpus`

Get full content of a corpus entry Required scope: corpus:read

Parameter	Type	Required	Description
`id`	string	Yes

`create_corpus`

Add a new knowledge base entry Required scope: corpus:write

Parameter	Type	Required	Description
`title`	string	Yes
`content`	string	Yes	Markdown content
`segmentSlug`	string	No
`priority`	number	No

`update_corpus`

Update a corpus entry Required scope: corpus:write

Parameter	Type	Required
`id`	string	Yes
`title`	string	No
`content`	string	No
`priority`	number	No
`isActive`	boolean	No

`delete_corpus`

Delete a corpus entry Required scope: corpus:write

Parameter	Type	Required	Description
`id`	string	Yes

Bots (Builder / Agency)

`list_bots`

List all your chatbot projects with stats and pool usage (Builder/Agency) Required scope: settings:read No parameters.

`create_bot`

Create a new chatbot project. Returns slug, API key, endpoints, and widget code. Required scope: settings:write

Parameter	Type	Required	Description
`name`	string	Yes	Project name
`slug`	string	No	URL slug (auto-generated if omitted)
`botName`	string	No	Bot display name (default: Alice)
`botTitle`	string	No	Bot role title
`botTone`	`FORMAL` / `NEUTRAL` / `FRIENDLY` / `PLAYFUL` / `TECHNICAL`	No
`botLore`	string	No	Bot background story
`primaryColor`	string	No	Hex color #RRGGBB

`delete_bot`

Delete a chatbot project (irreversible) Required scope: settings:write

Parameter	Type	Required	Description
`slug`	string	Yes

`get_bot_stats`

Get analytics overview for a specific bot (conversations, messages, satisfaction, timeline) Required scope: stats:read

Parameter	Type	Required	Description
`slug`	string	Yes	Bot slug
`days`	number	No	Period in days (default: 30)

`run_digest`

Run an on-demand Conversation Digest for a bot: stats + a skeptical AI analysis (notable conversations, actions claimed without a real tool call, tool failures, unmet demands, suggestions), emailed to the configured recipients. Counts against the plan’s monthly on-demand quota. Required scope: stats:read

Parameter	Type	Required	Description
`slug`	string	Yes	Bot slug
`days`	number	No	Analysis window in days (default: 7, max 31)

`list_notable_conversations`

List the persisted “notable” conversations (golden examples) surfaced by past digests — strong intents, leads, bot defects, trust moments — with summary, key quote and suggested action. Required scope: stats:read

Parameter	Type	Required	Description
`slug`	string	Yes	Bot slug
`limit`	number	No	Max items (default: 20, max 50)

`list_conversations`

Read the conversations the bot actually had — date, page, channel, status, message count, and the tool calls it really made (lead captured, meeting booked, quote sent). This is the tool that turns “an agent would capture intent” into a list of captured intents. Required scope: conversations:read

Parameter	Type	Required	Description
`slug`	string	No	Bot slug. Omit for the key’s own tenant (a demo has no children)
`limit`	number	No	Max conversations (default: 20, max 50)
`withMessages`	boolean	No	Include full transcripts (default: false)

This tool is part of the scope set handed to an agent with a demo — see Pre-sale surface.

`deploy_corpus`

Add a knowledge base entry to a bot. Push markdown content directly. Required scope: corpus:write

Parameter	Type	Required	Description
`slug`	string	Yes	Bot slug
`title`	string	Yes	Entry title
`content`	string	Yes	Markdown content
`segmentSlug`	string	No	Target segment (default: general)

Tools (configuration)

Configure your bot’s action tools by talking to your AI agent — the same gestures the dashboard exposes, now drivable over MCP. The agent reads the expected config format and emits it; Animam validates and applies it (single validated core).

Secrets never travel through the agent. Tool types that require a secret (VERIFIED_ACTION) or handle payments are not creatable over MCP — configure those in the dashboard. Any secret field in config is stripped. This follows the universal “no secrets in prompts” rule.

`list_tools`

List the bot’s configured tools (secrets masked). Required scope: tools:read

`create_tool`

Create a configurable tool. Allowed types: SUBMIT_FORM, GENERATE_QUOTE, RECOMMEND_PRODUCT, BOOK_MEETING, CHECK_AVAILABILITY, ESCALATE_TO_HUMAN, PREFILL_FORM, REMEMBER_FACT, EXPLORE_CORPUS. The config is per-type JSON. Required scope: tools:write

Parameter	Type	Required	Description
`name`	string	Yes	Tool name (snake_case)
`type`	string	Yes	One of the allowed types above
`description`	string	Yes	What the tool does (read by the agent to decide when to call it)
`config`	object	No	Per-type config. Example for `GENERATE_QUOTE`: `{ "pricing": { "currency": "EUR", "vat": 20, "items": [{ "sku": "site", "label": "Showcase site", "unit": 150000, "per": "flat" }] } }` (amounts in cents). Never include a secret.

`update_tool`

Update an existing tool by id (name, description, config, isActive). Required scope: tools:write

Parameter	Type	Required	Description
`toolId`	string	Yes	Tool id
`name`	string	No	New name
`description`	string	No	New description
`config`	object	No	New per-type config (secrets stripped)
`isActive`	boolean	No	Enable/disable

`delete_tool`

Delete a tool by id. Required scope: tools:write

Parameter	Type	Required	Description
`toolId`	string	Yes	Tool id

Chat

`chat_test`

Send a test message to a bot and get the response (non-streaming, test mode) Required scope: settings:read

Parameter	Type	Required	Description
`slug`	string	Yes	Bot slug
`message`	string	Yes	Test message to send
`segment`	string	No	Segment slug (default: general)

​Tenant & branding

​get_tenant

​update_tenant

​External MCP tools

​get_mcp_tools

​update_mcp_tools

​Segments

​list_segments

​get_segment

​update_segment

​create_segment

​Knowledge base (corpus)

​list_corpus

​get_corpus

​create_corpus

​update_corpus

​delete_corpus

​Bots (Builder / Agency)

​list_bots

​create_bot

​delete_bot

​get_bot_stats

​run_digest

​list_notable_conversations

​list_conversations

​deploy_corpus

​Tools (configuration)

​list_tools

​create_tool

​update_tool

​delete_tool

​Chat

​chat_test

Tenant & branding

`get_tenant`

`update_tenant`

External MCP tools

`get_mcp_tools`

`update_mcp_tools`

Segments

`list_segments`

`get_segment`

`update_segment`

`create_segment`

Knowledge base (corpus)

`list_corpus`

`get_corpus`

`create_corpus`

`update_corpus`

`delete_corpus`

Bots (Builder / Agency)

`list_bots`

`create_bot`

`delete_bot`

`get_bot_stats`

`run_digest`

`list_notable_conversations`

`list_conversations`

`deploy_corpus`

Tools (configuration)

`list_tools`

`create_tool`

`update_tool`

`delete_tool`

Chat

`chat_test`