Verbalo MCP Integration Guide (AI-Ready)

Self-contained documentation for Cursor / Claude Code / custom agents to integrate with the Verbalo MCP server. This page is intentionally structured for direct machine consumption.

1) Integration Target

Server package path in repository: apps/mcp-server

Transport: stdio

Server name: verbalo-agent-config-mcp

Required env vars:

VERBALO_API_BASE_URL (example: https://app.verbalo.ai)
VERBALO_API_TOKEN (Bearer token from Verbalo account/API key flow)

2) Quick Start (for humans and AI)

Clone and build

git clone https://github.com/StarskoldVBS/Verbalo.git
cd Verbalo
npm install
npm run mcp:build

Run MCP server manually

export VERBALO_API_BASE_URL="https://app.verbalo.ai"
export VERBALO_API_TOKEN="<YOUR_TOKEN>"
npm run mcp:start

3) Cursor MCP Config

{
  "mcpServers": {
    "verbalo": {
      "command": "node",
      "args": ["/absolute/path/to/Verbalo/apps/mcp-server/dist/index.js"],
      "env": {
        "VERBALO_API_BASE_URL": "https://app.verbalo.ai",
        "VERBALO_API_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Alternative command: use npm run mcp:start via shell wrapper if preferred.

4) Claude Desktop MCP Config

{
  "mcpServers": {
    "verbalo": {
      "command": "node",
      "args": ["/absolute/path/to/Verbalo/apps/mcp-server/dist/index.js"],
      "env": {
        "VERBALO_API_BASE_URL": "https://app.verbalo.ai",
        "VERBALO_API_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

5) Tool Catalog (contract summary)

Tool	Purpose	Required args
`list_agents`	List all agents	none
`update_agent_name`	Rename agent	`agentId`, `name`
`list_profiles`	List profiles	none
`create_profile`	Create profile with snapshot	`name`, `snapshot`
`update_profile`	Update profile metadata	`profileId`
`delete_profile`	Delete profile	`profileId`
`list_profile_versions`	Get profile versions	`profileId`
`select_profile_version`	Apply profile version to agent	`profileId`, `agentId`
`upload_admin_prompt_markdown`	Set admin prompt from markdown	`agentId`, `markdown`
`set_admin_prompt_text`	Set admin prompt from plain text	`agentId`, `content`
`apply_profile_to_agent`	Apply profile (+optional version)	`profileId`, `agentId`
`list_tts_voices`	List voices by provider	`provider`
`set_tts_params`	Update TTS settings	`agentId`
`update_agent_settings`	Full settings patch	`agentId`, `payload`

6) AI Integration Playbook (copy-paste prompt)

You are integrating with Verbalo MCP server "verbalo-agent-config-mcp".

Rules:
1. Use only tools exposed by this MCP server.
2. First call list_agents and list_profiles.
3. If profile does not exist, call create_profile with a full snapshot.
4. Apply profile to the target agent via apply_profile_to_agent.
5. For admin prompts, use set_admin_prompt_text or upload_admin_prompt_markdown.
6. For voice setup, call list_tts_voices(provider) then set_tts_params.
7. Return final summary containing changed agentId, profileId, versionId, and provider.

Environment:
- VERBALO_API_BASE_URL=https://app.verbalo.ai
- VERBALO_API_TOKEN=<TOKEN>

7) Security and quality requirements

Use scoped API tokens per client workspace.
Never expose token in logs, prompts, screenshots, or artifacts.
Prefer read tools first, then mutating tools.
For bulk operations, apply step-by-step and verify each response.
If a call fails, return structured error and suggested retry action.

8) Why this format (forum + official guidance)

This page follows practical recommendations from MCP community writeups and official MCP/Anthropic docs: outcome-oriented tools, strict schemas, concise high-signal responses, explicit usage instructions, and context-efficient contracts.