BotUyo AI代理管理MCP服务

@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 setup

It 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/login commands below. Some clients (Cursor, VS Code) use the servers key instead of mcpServers.

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 terminal

The 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"

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 credentials

The 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 inputSchema lists the exact arguments (with required) and its description states role requirements and side effects. Discover the live catalog with the MCP tools/list request; you never need to hardcode tool names. A typical build flow is create_agent → update_agent (identity/voice) → upsert_stage (conversation graph) → update_enabled_tools / configure_agent_tool (capabilities) → publish_agent. Use example_agent to see a fully documented reference config, and audit_agent_family to validate before publishing.

Agents

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.

Conversation flow

Tools & capabilities

Knowledge base

Templates

Import / export

Avatar & media

Versioning

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.

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.

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

Roles

Channels & integrations: connect_channel / disconnect_channel / configure_integration / remove_integration additionally require owner or admin (a developer can 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 build

Test with MCP Inspector

Authenticate first (npx @botuyo/mcp login), then run:

npm run inspect

Contributing

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