BotUyo MCP Server
Summary: This server lets an AI assistant create, configure, publish, and maintain BotUyo AI agents end-to-end within an authenticated tenant — no cloning or building required.
Agents: list, inspect (full config/status), create, partially update (identity, voice, channels, widget), delete (with name confirmation), and publish/unpublish; plus a read-only
example_agentreference config.Conversation flow:
upsert_stageto create/update named stages and their graph connections, with per-channel flow overrides.Tools & capabilities: browse available tools and the full catalog, replace an agent's enabled tools, and create/update/view/remove tool configs including multi-instance virtual tools.
Knowledge base: list documents, ingest URLs by scraping/indexing, associate document IDs to agents, delete documents and their chunks.
Templates: list industry templates and spin up a new agent from one with hydrated business data.
Import/export: dump an agent's full config to editable JSON (auto-saved locally) and re-import it as a full replace from file or inline.
Avatar & media: list free 3D avatars, assign a catalog or custom
.glb/.vrmavatar, and upload local images as avatar/logo.Versioning: list saved snapshots and roll an agent back to a previous version.
Account: switch the active tenant (or list available tenants/sub-tenants) for the session.
Permissions: read tools need
viewer+; write/publish needdeveloper+; destructive actions require explicit confirmation flags.Note: this schema exposes 34 tools, a subset of the 48 documented in the README (agent families, channels, and integrations tools are absent here).
Enables monitoring and management of BotUyo AI agents integrated with Instagram communication channels.
Allows for the configuration and activation of the SearchKnowledgeBase tool, enabling agents to query integrated knowledge sources.
Enables monitoring and management of BotUyo AI agents integrated with Telegram communication channels.
Enables monitoring and management of BotUyo AI agents integrated with WhatsApp communication channels.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BotUyo MCP Server Create a support agent named Alex and enable the knowledge base tool"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@botuyo/mcp — BotUyo MCP Server
Create and manage BotUyo AI agents directly from your AI coding tools — no cloning, no building.
Quickstart
For the next release's schema discovery, configuration updates, virtual tools and navigation example, see Tool contracts. The new contracts require the matching backend.
The fastest way — one command configures your editor and logs you in:
npx @botuyo/mcp setupIt auto-detects your editor (Cursor, VS Code / Antigravity, Claude Desktop), writes the MCP config, and walks you through authentication.
Manual setup
1. Add the BotUyo server to your MCP client config:
{
"mcpServers": {
"botuyo": {
"command": "npx",
"args": ["-y", "@botuyo/mcp"]
}
}
}No API key goes in the config — authentication is handled by the
auth/logincommands below. Some clients (Cursor, VS Code) use theserverskey instead ofmcpServers.
Client | Config file |
Cursor |
|
VS Code / Antigravity |
|
Claude Desktop |
|
Windsurf |
|
2. Authenticate once — saves a token to ~/.botuyo/credentials.json:
npx @botuyo/mcp auth # browser OAuth (recommended)
# or
npx @botuyo/mcp login # email + password in the terminalThe running MCP server picks up your session automatically — no restart needed. Tokens last 7 days; re-run auth or login to refresh.
Start building agents
Once connected, ask your AI assistant things like:
"Create a new agent called 'Soporte' for my tenant" "Update Mar's objective to focus on sales" "Add a welcomeStage that greets guests in Spanish" "Enable the EscalateToHuman and SearchKnowledgeBase tools on Mar" "Publish the agent"
Related MCP server: Agent5ive MCP Server
CLI commands
npx @botuyo/mcp setup # Configure your editor + authenticate (recommended)
npx @botuyo/mcp auth # Login via browser (OAuth)
npx @botuyo/mcp login # Login via email + password
npx @botuyo/mcp tenants # List your tenants
npx @botuyo/mcp switch-tenant # Switch the active tenant
npx @botuyo/mcp whoami # Show the current session
npx @botuyo/mcp logout # Clear stored credentialsThe server resolves your JWT from BOTUYO_TOKEN, falling back to ~/.botuyo/credentials.json. The backend URL defaults to https://api.botuyo.com (override with BOTUYO_API_URL).
Available tools
The server exposes 48 tools. Read tools (list_*, get_*, export_*, audit_*) need viewer+; write/publish tools need developer+; channel & integration connect/configure need admin+ (see Roles).
For AI assistants / IDE agents: every tool is self-describing — its
inputSchemalists the exact arguments (withrequired) and itsdescriptionstates role requirements and side effects. Discover the live catalog with the MCPtools/listrequest; you never need to hardcode tool names. A typical build flow iscreate_agent→update_agent(identity/voice) →upsert_stage(conversation graph) →update_enabled_tools/configure_agent_tool(capabilities) →publish_agent. Useexample_agentto see a fully documented reference config, andaudit_agent_familyto validate before publishing.
Agents
Tool | Description |
| List all agents in the tenant |
| Get an agent's full config (identity, stages, enabled tools) |
| Channel connection status + admin link to connect missing channels |
| Create a new agent |
| Update identity (tone, language, objective, custom instructions) |
| Soft-delete an agent (irreversible; requires explicit confirmation) |
| Publish or unpublish an agent (live vs draft) |
| Return a fully documented example agent config (read-only reference) |
Agent families
A family is one logical agent with a shared base config plus multiple variants (each variant stores only its overrides and is materialized into a real agent) — ideal for a single assistant offered in several levels or flavors.
Tool | Description |
| List agent families in the tenant |
| Get a family's shared base + all its variants |
| Create a family with a shared base and an initial set of variants |
| Replace the shared base (re-materializes every variant) |
| Add a new variant (materialized into a draft agent) |
| Update a variant's label / overrides / handoff targets / order |
| Remove a variant (cannot remove the entry variant) |
| Publish the family and all its member agents |
| Delete a family and all its agents (irreversible; requires confirmation) |
| Export a portable family JSON (base + variants) to a local file |
| Replace a family's base + variants from JSON (full replace), or create a new family from a folder/payload |
| Read-only config-quality audit of one family ( |
Conversation flow
Tool | Description |
| Create or update a named stage in the agent's conversation graph |
Tools & capabilities
Tool | Description |
| List tools available to your tenant (core + custom) |
| Enable/disable tools on an agent |
| Full tool catalog with metadata (configurable, multi-instance, schema, required integrations) |
| Create/update a tool's config on an agent (single or multi-instance) |
| List an agent's tool configs, grouped |
| View the full config of a specific tool on an agent |
| Remove a tool's configuration |
Knowledge base
Tool | Description |
| List knowledge base documents |
| Ingest a URL into the knowledge base |
| Link knowledge document IDs to an agent |
| Delete a knowledge document and all its chunks |
Templates
Tool | Description |
| List agent templates by industry |
| Create a new agent from a template |
Import / export
Tool | Description |
| Export an agent's full config as editable JSON |
| Replace an agent's full config from JSON (full overwrite) |
Avatar & media
Tool | Description |
| List the free 3D avatars in the catalog |
| Set a 3D avatar for an agent (catalog ID or custom .glb/.vrm URL) |
| Upload a local image to the CDN as an agent's avatar/logo |
Versioning
Tool | Description |
| List an agent's saved version snapshots |
| Roll back an agent to a previous version |
Channels
Connect messaging channels to the tenant with their secrets. Secrets are write-only — the server stores them and never returns their values; list_channels reports only which credential keys are set. Connect/disconnect require role owner or admin.
Tool | Description |
| List the tenant's channels + status. Never returns secret values — only |
| Connect a channel (WhatsApp, Telegram, Discord, Web, …) with its credentials. Validated against the provider API and stored server-side |
| Disconnect a channel by id (archives its open conversations) |
Passing secrets safely. connect_channel accepts the secret two ways:
credentials— literal values, e.g.{ "botToken": "123:ABC" }. Simplest, but the secret passes through the conversation/LLM.credentialsFromEnv(recommended for real secrets) — a map of credential key → environment variable name, e.g.{ "botToken": "MY_TG_TOKEN" }. The MCP server reads the value from its own environment (set it in your MCP client config), so the secret never appears in the chat.
Channels that require an interactive flow (WhatsApp/Instagram Embedded Signup QR/OAuth) still need admin.botuyo.com. Channels that authenticate with a static token (Telegram, Discord, WhatsApp Cloud API with an existing token, Web) can be connected here.
Integrations
Install and configure the tenant's external integrations (Shopify, PaseoLibre, Google Calendar, email SMTP, …) with their secrets, using the same write-only secret model as channels. Configure/remove require role owner or admin.
Tool | Description |
| List the integration catalog (available) + the tenant's installed integrations. Never returns secret values — only |
| Install or update an integration with its config/secret (validated against the provider, stored server-side). Accepts literal |
| Uninstall an integration by id |
Same two secret modes as connect_channel: literal config, or configFromEnv (map config key → env var name resolved from the MCP server environment, keeping the secret out of the chat).
Account
Tool | Description |
| Switch the active tenant for the session |
Roles
Role | Read | Write | Publish |
| ✅ | ✅ | ✅ |
| ✅ | ✅ | ✅ |
| ✅ | ✅ | ✅ |
| ✅ | ❌ | ❌ |
Channels & integrations:
connect_channel/disconnect_channel/configure_integration/remove_integrationadditionally require owner or admin (adevelopercan build agents but not wire up channel/integration secrets).
Channel Integrations
Channels that authenticate with a static secret — Telegram (bot token), Discord (bot token), WhatsApp Cloud API (existing access token), Web — can be connected directly via the connect_channel tool (see Channels). Channels that need an interactive flow (WhatsApp/Instagram Embedded Signup with QR scans or OAuth consent) must still be connected from admin.botuyo.com.
Use get_agent_status to check which channels are connected (it links to the admin panel for any missing channel), or list_channels for the tenant-wide channel list and status.
Build from source
git clone https://github.com/MarcoAR1/botuyo-mcp.git
cd botuyo-mcp
npm install
npm run buildTest with MCP Inspector
Authenticate first (npx @botuyo/mcp login), then run:
npm run inspectContributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
Please note that this project follows a Code of Conduct.
Security
To report a vulnerability, see SECURITY.md.
License
MIT © BotUyo
Available Tools
30 toolsassociate_knowledge_to_agentA
Associates (links) knowledge base document IDs to an agent. Replaces the current list of knowledgeDocumentIds on the agent. Use list_knowledge_documents to get valid document IDs.
Inputs: agentId (required), documentIds (required).
configure_agent_toolA
Crea o actualiza la config de un tool para un agente. Si la tool no está en enabledTools, la agrega automáticamente.
Dos modos:
Single-instance: configura una tool existente (ej.
send_email) con params fijos.Multi-instance: crea una instancia virtual con nombre propio basada en una tool real (requiere
baseTool). Ej:webhook_pedidosbasada encall_webhook.
Inputs: agentId (required), toolName (required), baseTool, params, +2 more.
create_agentA
Create a new agent for the tenant. The agent is created in "draft" status. Use update_agent to configure identity, stages, and tools afterward. Requires role: owner, admin, or developer.
Inputs: name (required), description, type.
create_from_templateA
Create a new agent from a pre-built template.
Templates contain pre-configured stages, connections (graph flow), tools, and channel overrides for specific industries. Business data (name, phone, email, services) is automatically hydrated into the template placeholders.
Use list_templates first to see available templates.
Requires role: owner, admin, or developer.
Inputs: templateId (required), businessName (required), contactPhone, contactEmail, +2 more.
delete_agentA
Delete an agent (soft delete). This action is IRREVERSIBLE — the agent will be deactivated and hidden.
⚠️ IMPORTANT: This tool requires explicit confirmation. You MUST set confirm to true AND provide the exact agent name in confirmName to proceed.
Requires role: owner, admin, or developer.
Inputs: agentId (required), confirm (required), confirmName (required).
delete_knowledge_documentB
Deletes a knowledge base document and all its chunks from the current tenant.
Inputs: documentId (required).
example_agentA
Returns a complete, documented example of an agent configuration JSON with ALL possible fields explained.
Use this as a reference when creating or editing agents. Every field includes a description of what it does, its type, valid values, and conditions. This is a read-only reference tool — it doesn't create or modify anything.
Useful for:
New users learning the agent config structure
Checking available fields before using import_agent_json
Understanding how stages, connections, channelFlows, and tools work together
Learning the widget theming system (cssVariables, darkCssVariables, animations, effects)
Understanding per-tool configuration (toolConfigs) with single and multi-instance patterns
Inputs: no named parameters.
export_agent_jsonA
Export the full agent configuration as clean, editable JSON.
Returns the complete agentConfig including identity, stages, connections (graph edges), channelFlows, enabledTools, channels, widgetConfig, voice, and all other settings. Also includes apiKey (read-only) for external integrations.
The exported JSON is automatically saved to a local file for easy editing:
Default: saves to ./agents/{agent-name}.json in the current working directory
Custom: use savePath to specify a different directory
Use import_agent_json to re-import after editing.
Inputs: agentId (required), savePath.
get_agentA
Get the full configuration of a specific agent, including identity (tone, language, objective, customInstructions), stages, and enabled tools.
Inputs: agentId (required).
get_agent_statusA
Get the channel connection status of an agent (WhatsApp, Instagram, Telegram, Web). Shows which channels are connected and provides a direct link to the admin panel to connect missing channels.
Inputs: agentId (required).
get_tool_configC
Ver el config completo de un tool específico de un agente (formato JSON).
Inputs: agentId (required), toolName (required).
get_tools_catalogC
Lista el catálogo completo de tools disponibles con su metadata: configurable, allowMultiInstance, configSchema, requiredIntegrations.
Inputs: filter.
import_agent_jsonA
Import/replace an agent's FULL configuration from a local JSON file or from a JSON object.
This is a FULL REPLACE operation — the entire agentConfig is overwritten with the provided config. For partial updates (changing just one field), use update_agent instead.
Null handling:
Fields set to null are stripped before saving (field is removed from the stored config)
Omitted fields are NOT preserved — this is a full replace, not a merge
Internal fields (model, temperature, summaryThreshold, voice.liveModel) are preserved automatically
Preferred workflow:
Use export_agent_json to save the agent config to a local file (auto-saved to ./agents/)
Edit the local file as needed
Use this tool with filePath pointing to that file to apply the changes
You can provide the config either via:
filePath: path to a local JSON file (preferred — reads the file from disk)
agentConfig: inline JSON object (fallback if no file)
If both are provided, filePath takes priority.
Requires role: owner, admin, or developer.
Inputs: agentId (required), filePath, agentConfig.
ingest_knowledge_urlA
Add a URL to the knowledge base. BotUyo will scrape the page content and index it for intelligent search. The document can then be associated to agents using associate_knowledge_to_agent.
Inputs: url (required), name, description, tags, +1 more.
list_agentsA
Lists all agents for the authenticated tenant. Returns id, name, description, status (draft/published), and how many tools each agent has enabled.
Inputs: no named parameters.
list_agent_versionsA
List version history for an agent. Returns all saved snapshots with version number, change source, and timestamp. Useful to see what changed and when before deciding to restore.
Inputs: agentId (required).
list_available_toolsA
List all tools available for this tenant. Returns both "core" tools (available to all tenants) and "tenant" tools (custom tools specific to your tenant). Use tool IDs when enabling tools with update_enabled_tools or configuring stage tools.
Inputs: no named parameters.
list_avatarsB
Lista los avatares 3D gratuitos disponibles en el catálogo. Muestra nombre, formato y categoría.
Inputs: no named parameters.
list_knowledge_documentsC
Lists all knowledge base documents for the current tenant. Returns document id, name, type, status, chunks count, and file size.
Inputs: limit, offset.
list_templatesA
List all available agent templates for quick agent creation.
Returns templates organized by industry vertical (beauty, clinic, restaurant, fitness, etc.). Each template includes pre-configured stages, connections (graph flow), tools, and channel overrides.
Use create_from_template to create an agent from any template.
Inputs: no named parameters.
list_tool_configsC
Lista las configs de tools de un agente agrupadas: configuradas (single y multi-instance), habilitadas sin config, y resumen de multi-instance.
Inputs: agentId (required).
publish_agentA
Publish or unpublish an agent. Published agents are live and handle incoming conversations. Unpublished agents are in "draft" status.
Requires role: owner, admin, or developer.
Inputs: agentId (required), publish (required).
remove_tool_configB
Elimina la configuración de un tool. Si es multi-instance, también la remueve de enabledTools automáticamente.
Inputs: agentId (required), toolName (required).
restore_agent_versionA
Restore an agent to a previous version (rollback). The current config is automatically saved as a new snapshot before restoring, so you can always undo a restore. Use list_agent_versions first to see available versions.
Requires role: owner, admin, or developer.
Inputs: agentId (required), version (required).
select_avatarC
Selecciona un avatar 3D para un agente. Puede ser del catálogo (por ID) o una URL custom (.glb/.vrm).
Inputs: agentId (required), avatarId, avatarUrl.
switch_tenantA
Switch the active tenant for this MCP session. If no tenantId is provided, lists all available tenants (including sub-tenants within organizations). If a tenantId is provided, switches to that tenant or sub-tenant. The switch takes effect immediately for subsequent tool calls.
Inputs: tenantId.
update_agentA
Update an agent's configuration with partial merge. Only the fields you provide are changed — everything else is preserved.
Field behavior:
Omitted field → not touched (keeps existing value)
Field with value → sets/overwrites that field
Field set to null → deletes that field from the agent config
Nested objects (identity, widgetConfig, voice, widgetConfig.cssVariables) are deep-merged: update_agent({ widgetConfig: { logoUrl: "https://..." } }) → only logoUrl changes, all other widgetConfig fields preserved
Arrays (channels, enabledTools) are replaced entirely: update_agent({ channels: ["web", "whatsapp"] }) → replaces the full channels array
Use this to configure WHO the agent is and HOW it looks. For defining WHAT the agent does in each conversation flow, use upsert_stage. For changing which tools the agent can call, use update_enabled_tools.
Requires role: owner, admin, or developer.
Inputs: agentId (required), name, description, identity, +4 more.
update_enabled_toolsA
Set which tools are enabled for an agent. This REPLACES the current list of enabled tools.
Use list_available_tools to see the valid tool IDs for your tenant first.
Requires role: owner, admin, or developer.
Inputs: agentId (required), toolIds (required).
upload_agent_mediaA
Upload a local image file to the CDN and assign it to an agent as avatar or logo.
Reads the file from the local filesystem, uploads it via the backend media API (Cloudinary), and updates the agent's widgetConfig with the resulting URL.
Supported formats: webp, png, jpg, jpeg, svg. Max size: 2MB.
Inputs: agentId (required), filePath (required), mediaType.
upsert_stageA
Create or update a named stage in an agent's conversation flow.
A stage defines what the agent does at a particular step in the conversation. Stages are nodes in a graph connected by edges (connections).
Examples of stage names: "welcomeStage", "salesStage", "hostStage", "checkoutStage"
The stage config is merged with existing stages — existing stages you don't specify are kept unchanged. Connections and channelFlows replace existing values when provided.
Requires role: owner, admin, or developer.
Inputs: agentId (required), stageName (required), stageConfig (required), connections, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools have distinct purposes, but some overlap exists that could cause confusion. For example, 'configure_agent_tool' and 'update_enabled_tools' both relate to tool management, and 'list_available_tools' vs 'get_tools_catalog' serve similar listing functions. Descriptions help clarify, but an agent might misselect between these pairs.
Naming conventions are mixed, with some tools using verb_noun patterns (e.g., 'create_agent', 'list_agents') and others using noun_verb or more descriptive phrases (e.g., 'associate_knowledge_to_agent', 'example_agent'). There's also inconsistency in language, with some tools in Spanish and others in English, which adds to the lack of a predictable pattern.
With 30 tools, the count feels excessive for an agent management server, leading to potential overwhelm and redundancy. While the domain is broad, many tools could be consolidated (e.g., multiple listing tools), making the set feel heavy and less focused than ideal for efficient agent use.
The tool set provides comprehensive coverage for agent lifecycle management, including creation, configuration, publishing, and version control. It also handles knowledge bases, templates, and media. Minor gaps might exist in advanced analytics or bulk operations, but core workflows are well-supported with no dead ends.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Build and manage AI-native customer support agents from Claude or any MCP client.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables management of Mistral AI agents through MCP tools including creating, listing, searching, viewing details, and deleting agents. Integrates with Mistral API to provide agent management capabilities through natural language interactions.1-
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible clients to interact with deployed Agent5ive agents as tools. Allows users to query agent purposes and send messages to leverage Agent5ive capabilities through natural language.MIT
- AlicenseAqualityDmaintenanceExposes Azure AI Foundry agents, workflows, and AI Search vector-database capabilities as MCP tools, enabling natural language interaction with agents, semantic search, and index management.102MIT
- FlicenseNot gradedqualityDmaintenanceA universal MCP hub that connects any AI agent to any tool, enabling agent interoperability with 50+ pre-built tools, custom tool creation, and tool discovery.-