Skip to main content
Glama
Convocore MCP Server

Convocore MCP Server

by Moe03

Convocore MCP Server

A Model Context Protocol (MCP) server that connects AI assistants (Claude Desktop, Cursor, and other MCP hosts) to the Convocore HTTP API. The host spawns this process, talks to it over stdio (standard input/output), and gains many tools for agents, conversations, knowledge bases (including mass URL ingest), and single-URL scraping.

npm version Docker Hub License: MIT Convocore MCP connector – tool definition quality and endpoint health on Glama


What this project is

Piece

Role

MCP

A protocol so clients (e.g. Claude) can list and call tools with structured arguments and get text (or other) results back.

This server

A small Node.js app using @modelcontextprotocol/sdk: it registers tools, validates arguments with Zod, and proxies calls to Convocore’s REST API with your workspace bearer token.

Convocore API

Backend at https://{region}-api.vg-stuff.com/v3 (see Regions). Your WORKSPACE_SECRET is sent as Authorization: Bearer ….

This repository is not a chat UI. It is the bridge between an MCP-capable assistant and Convocore.


Related MCP server: Letta MCP Server

What the server exposes (capabilities)

The server declares tools only (no MCP resources or prompts in code). Each successful tool call returns MCP content with a single text part whose body is pretty-printed JSON (JSON.stringify(result, null, 2)) from the Convocore API response.

Area

Tools

Purpose

Agents

~12

CRUD, list, search, export/import, clone, usage, CSS, patch prompt

Conversations

~12

CRUD, list, export, assign, bulk/query, channel send

Knowledge base

~14

CRUD, patch, bulk get/create/delete, URL ingest, search, images, quota

Orgs / agency / clients

6

orgs_read/write, agency_read/write, clients_read/write

Leads CRM

2

leads_read / leads_write (list, export, import, magic import, …)

Agent HTTP tools

5

list/get/create/update/delete Convocore agent tools (not MCP tools)

Agent variables

5

list/get/create/update/delete agent variables

Channels

4

get_agent_channels, create_channel_connect_link, get_connect_link_status, disconnect_meta_page — connect WhatsApp / Messenger / Instagram through a no-login link

WhatsApp AI rules

3

get_whatsapp_ai_rules, update_whatsapp_ai_rules, update_whatsapp_number_settings — when the AI replies on WhatsApp

Campaigns

2

campaigns_read / campaigns_write — outbound call campaigns (create, edit, start/stop, restart, delete)

Call logs

2

call_logs_read / call_logs_write — list, get, export, create, edit, delete

Outbound calls & SMS

4

get_agent_phone, start_outbound_call, send_sms, contact_leads

Custom metrics

2

custom_metrics_read / custom_metrics_write — define metrics and read their data

Lead groups

2

lead_groups_read / lead_groups_write — list, create, assign, rename, delete

Folders

2

folders_read / folders_write — agent folders

Agent extras

5

get_agent_audit_log, send_handoff_reminder, generate_conversation_summaries, agent_gallery_templates, notification_email

WhatsApp management

6

whatsapp_numbers_read/write, whatsapp_templates_read/write, whatsapp_campaigns_read/write

Meta pages, SMS, email

5

meta_pages_read, sms_numbers_read/write, email_channel_read/write

Integrations

3

integrations_read / integrations_write / integrations_test — every connection (Google Calendar, Outlook Calendar, Google Sheets, Airtable, Shopify, Calendly, Zoho CRM, Gmail, Outlook mail, Zoho Mail, Google Drive), assign / update / remove on agents, diagnose an agent's setup, and inspect or run the agent's real integration tools

Zoho CRM records

2

zoho_crm_records_read / zoho_crm_records_write — list, search, COQL, get; create, update, upsert, delete, notes

Contacts

2

contacts_read / contacts_write — cross-channel identities

Agent backups

2

agent_backups_read / agent_backups_write — backup, restore, revert prompt, prompt caching

Code tools & sharing

2

code_tools, tool_sharing

Workspace

3

workspace_read / workspace_write, generate_lead_funnel

Testing

3

test_agent_tool, test_agent_tool_request, run_agent_auto_test

Discovery

1

search_mcp_tools — find the right tool without guessing

Scrape / embed / voice

many

scrape, embed code, voices, Twilio utils

Interact (WS)

1

Drive one agent turn; supports toolTest + variablesOverrides

Specs

3

UI Engine, channel integration, pricing


Light mode

The tools in the rows from "Campaigns" down to "Agent extras" (and every list tool) take mode:

  • compact (default): every record and field, but long text is cut and bulky blobs (transcripts, page content, histories) are replaced by a size marker.

  • full: the complete API response.


How it runs (transport and lifecycle)

  1. The host (Claude Desktop, Cursor, etc.) starts the server as a subprocess: e.g. npx -y convocore-mcp, docker run …, or node dist/index.js.

  2. Communication uses StdioServerTransport: JSON-RPC messages on stdin/stdout. Do not write logs to stdout; the server logs to stderr (e.g. Convocore MCP Server running on stdio).

  3. On startup, getConfig() reads env vars. If WORKSPACE_SECRET is missing, the process throws and exits.

  4. The host sends tools/list and tools/call. Each call is validated, then ConvocoreClient performs fetch() to the REST API.

flowchart LR
  Host[MCP host]
  MCP[convocore-mcp stdio]
  API[Convocore REST API v3]
  Host <--> MCP
  MCP --> API

Repository layout

Path

Purpose

src/index.ts

MCP server, tool definitions (JSON Schema for hosts), Zod validation, tool dispatch

src/convocore-client.ts

HTTP client: paths, methods, query strings, JSON bodies

src/agent-theme-palette.ts

hexToHsl / handleAutoGenPallet — builds nineColorPallet for customThemeJSONString

src/config.ts

WORKSPACE_SECRET, CONVOCORE_API_REGION, optional CONVOCORE_WORKSPACE_ID, resolved baseUrl

src/types.ts

Shared TypeScript types for config and agent payloads

dist/

Compiled output (pnpm run build / tsc) — what npm publishes

Dockerfile

Multi-stage image: build with pnpm, run node dist/index.js (alternative distribution)

docker-compose.yml

Example service (see Docker Compose note)

claude_desktop_config.example.json

Sample Claude Desktop MCP entry

openapi.json

OpenAPI spec (reference for API shape)


Environment variables

Variable

Required

Default

Meaning

WORKSPACE_SECRET

Yes

—

Bearer token for the Convocore workspace (same as API key/secret from your dashboard).

CONVOCORE_API_REGION

No

eu-gcp

eu-gcp or na-gcp; selects API host (see below).

CONVOCORE_API_BASE_URL

No

—

Optional full REST base URL override. Useful for local dev, e.g. http://localhost:5000/v3. Overrides CONVOCORE_API_REGION when set. The /interact WebSocket URL is derived from this (scheme swapped to ws/wss, path replaced with /interact) unless CONVOCORE_INTERACT_WS_URL is also set.

CONVOCORE_INTERACT_WS_URL

No

—

Optional explicit override for only the /interact WebSocket URL, e.g. ws://localhost:5000/interact. Set this when you want REST traffic on prod but WebSocket traffic on a local debug server (or vice-versa). Used verbatim — supply scheme, host, port, and path.

CONVOCORE_WORKSPACE_ID

No

—

Workspace/org UUID (agent.ownerID). When set, MCP avoids heavy GET /agents scans used only to infer the workspace id.

CONVOCORE_TELEMETRY

No

on

Set to 0 to turn off anonymous usage telemetry. See Telemetry.

The server reads WORKSPACE_SECRET, CONVOCORE_API_REGION, optional CONVOCORE_API_BASE_URL, optional CONVOCORE_INTERACT_WS_URL, optional CONVOCORE_WORKSPACE_ID, and optional CONVOCORE_TELEMETRY / CONVOCORE_TELEMETRY_DEBUG / DO_NOT_TRACK. Any other variables in compose files or docs are ignored unless you wire them yourself.

API regions and base URLs

CONVOCORE_API_REGION

Base URL

eu-gcp

https://eu-gcp-api.vg-stuff.com/v3

na-gcp

https://na-gcp-api.vg-stuff.com/v3

For local development, set CONVOCORE_API_BASE_URL=http://localhost:5000/v3 to redirect both REST and WebSocket, or set CONVOCORE_INTERACT_WS_URL=ws://localhost:5000/interact to redirect only the /interact WebSocket while REST keeps using the regional host.


Authentication

Every request from ConvocoreClient includes:

  • Authorization: Bearer <WORKSPACE_SECRET>

  • Content-Type: application/json

Non-OK responses: body is parsed as JSON; message is thrown as an error when present, otherwise a generic status message. Keep WORKSPACE_SECRET out of prompts, screenshots, and shared configs; use env vars or your host’s secret mechanism.

Gray-label client connections

Agencies can let a whitelabel client connect Claude, ChatGPT or Cursor to only the agents assigned to that client, under the agency's brand, on a neutral host (https://mcp-project.vg-stuff.com/mcp, extra hosts via GRAY_LABEL_MCP_HOSTS).

  • The agency turns on AI assistant access for the client (mcpAccess on the client). The client clicks Connect AI in their dashboard; the API mints a gl_… connection token stored as a hash on the agency workspace (users/{workspaceId}/mcpClientConnections).

  • The agency host accepts gl_ tokens only, and gl_ tokens work only there. The API scopes every call to the client's agents (client.widgetIDs ∪ org.widgetIDs, read live) and refuses workspace-level routes; this server also narrows the tool list and checks agent ids.

  • Server name, instructions, tool text, results, errors and the OAuth Connect page carry the agency brand ({Agency} - {Client}), never the platform's. Scope and brand refresh every minute on open sessions; revoking a connection or turning access off stops it.


Quick start

Prerequisites

  • A Convocore workspace secret (WORKSPACE_SECRET).

  • Optional: correct region (eu-gcp / na-gcp).

  • Node.js 20+ (ships with npx). Docker is optional and only needed for the container workflow.

You don't have to install anything. Your MCP host (Claude Desktop, Cursor, etc.) runs the server on demand:

npx -y convocore-mcp

Set WORKSPACE_SECRET (and optionally CONVOCORE_API_REGION) in the host's env block — see the Claude Desktop example below.

The first invocation downloads the package (a few seconds); subsequent runs are cached by npm.

Option B: Docker

docker run -i --rm \
  -e WORKSPACE_SECRET="your_workspace_secret_here" \
  -e CONVOCORE_API_REGION="eu-gcp" \
  moe003/convocore-mcp:latest

-i keeps stdin open so the MCP host can speak JSON-RPC to the container.

Option C: Local Node (development)

git clone https://github.com/moe003/convocore-mcp.git
cd convocore-mcp
pnpm install
pnpm run build
export WORKSPACE_SECRET="your_workspace_secret_here"
export CONVOCORE_API_REGION="eu-gcp"
node dist/index.js

Connecting MCP hosts

Gemini CLI

Install the extension (uses the hosted server; the first tool call opens a browser to sign in with your Convocore account):

gemini extensions install https://github.com/Moe03/convocore-mcp

Claude Desktop

Config path:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

npx (recommended):

{
  "mcpServers": {
    "convocore": {
      "command": "npx",
      "args": ["-y", "convocore-mcp"],
      "env": {
        "WORKSPACE_SECRET": "your_workspace_secret_here",
        "CONVOCORE_API_REGION": "eu-gcp"
      }
    }
  }
}

Windows note: if Claude Desktop fails to spawn npx directly, wrap it with cmd:

{
  "mcpServers": {
    "convocore": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "convocore-mcp"],
      "env": {
        "WORKSPACE_SECRET": "your_workspace_secret_here",
        "CONVOCORE_API_REGION": "eu-gcp"
      }
    }
  }
}

After saving the config, fully quit and relaunch Claude Desktop. The convocore server should appear in the MCP server list and the tools become available in chat.

Docker (alternative): pull the image first to avoid first-run timeout in the host:

docker pull moe003/convocore-mcp:latest
{
  "mcpServers": {
    "convocore": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "WORKSPACE_SECRET=your_workspace_secret_here",
        "-e", "CONVOCORE_API_REGION=eu-gcp",
        "moe003/convocore-mcp:latest"
      ]
    }
  }
}

Local Node (development): use an absolute path to dist/index.js:

{
  "mcpServers": {
    "convocore": {
      "command": "node",
      "args": ["/absolute/path/to/convocore-mcp/dist/index.js"],
      "env": {
        "WORKSPACE_SECRET": "your_workspace_secret_here",
        "CONVOCORE_API_REGION": "eu-gcp"
      }
    }
  }
}

Cursor and other clients

Any client that supports stdio MCP servers can use the same command + args + env pattern as above. The recommended command/args is npx + ["-y", "convocore-mcp"]; Docker and local Node also work. Set the same environment variables.

Dashboard one-click install (hosted MCP)

For a workspace dashboard button, call the hosted helper with the MCP URL, region, and workspace secret:

curl -sS -X POST https://mcp.convocore.ai/v1/install-links \
  -H 'Content-Type: application/json' \
  -d '{
    "mcpUrl": "https://mcp.convocore.ai/mcp",
    "workspaceSecret": "vg_…",
    "region": "na-gcp",
    "workspaceName": "Acme Agency"
  }'

Response highlights — connector / install name defaults to Convocore {workspaceName} (e.g. Convocore Acme Agency) for Claude, Cursor, and other hosts:

Field

Use

name

Display name used in Claude connectorName, Cursor deeplink name, Claude Desktop key

cursor.deeplink

Add to Cursor — true one-click (cursor://…/mcp/install with URL + Authorization + X-Convocore-Region in base64 config)

cursor.webFallback

https://cursor.com/en/install-mcp?… if the protocol handler is not registered yet

claude.installUrl

Add to Claude — opens the official prefilled custom-connector modal

claude.connectorUrl

/t/<base64url(secret)>/mcp?region=… (path keeps the secret after Claude strips ?token= from OAuth resource)

claudeDesktop

Optional local mcp-remote JSON for Claude Desktop config files

Why Claude needs ?token= (and OAuth on the host)

  • Cursor deeplinks embed headers in base64 — secret travels with the install.

  • Claude’s install URL only prefills name + connector URL. No header query params exist.

  • Claude then runs OAuth Dynamic Client Registration against the MCP host. Without /oauth/register + authorize/token, you get “Couldn't register with Convocore’s sign-in service”.

  • Hosted MCP implements that OAuth AS. Claude often strips ?token= from OAuth resource, so the secret is in the path (/t/…/mcp). Authorize shows a one-click Connect page (auto-submits) — no paste. Access tokens are the workspace secret, expires_in ≈ 10 years, plus refresh.

  • MCP transport sessions idle-evict after ~1 year by default (CONVOCORE_HOSTED_SESSION_IDLE_MS=0 disables eviction). Reconnect recreates a session with the same secret.

Security note: ?token= in a Claude connector URL is a pragmatic tradeoff (logs/history). Prefer Cursor headers when possible; rotate the workspace secret if a link leaks.

You can also build the same URLs client-side with buildInstallLinks from dist/install-links.js without calling the API.


HTTP API mapping (what each tool calls)

All paths are relative to baseUrl (e.g. https://eu-gcp-api.vg-stuff.com/v3).

Tool

Method

Path / pattern

create_agent

POST

/agents body { agent: { … } } (legacy/raw mode)

create_agent_from_template

POST workflow

Preferred: explicit systemPrompt / branding / merged voiceConfig; optional sourceUrl scrape + KB; then POST /agents; response includes full agent via follow-up get_agent

get_agent

GET

/agents/{agentId}

update_agent

PATCH

/agents/{agentId} body { agent: { … } }

patch_agent_prompt

GET+PATCH

get_agent then exact old_string→new_string on prompt/CSS field (Cursor StrReplace-style); PATCH only the changed fields

delete_agent

DELETE

/agents/{agentId}

list_agents

GET

/agents optional ?limit= when supported

search_agents

GET

/agents/search?workspaceId=…&page&limit&sortBy&starredOnly&search? (workspace resolved internally from MCP config/workspace secret context)

export_agent

GET

/agents/{agentId}/export-template

import_agent

POST

/agents/import-template

get_agent_usage

POST

/agents/{agentId}/usage body { range }

list_conversations

GET

/agents/{agentId}/convos?limit&cursor (cursor pagination; page>1 without cursor rejected)

get_conversations_bulk

GET×N

Fan-out GET /agents/{agentId}/convos/{convoId} (max 50 IDs, concurrency pool)

query_conversations

MCP

Cursor list + bulk filter (not server SQL; maxScan bound)

get_agent_usage_bulk

POST×N

Fan-out POST /agents/{agentId}/usage (max 20 agents)

get_kb_docs_bulk

GET×N

Fan-out GET /agents/{agentId}/kb/{docId} (max 30 docs)

create_conversation

POST

/agents/{agentId}/convos body { conversation }

get_conversation

GET

/agents/{agentId}/convos/{convoId}

update_conversation

PATCH

/agents/{agentId}/convos/{convoId} body { conversation }

list_conversation_notes

GET

/agents/{agentId}/convos/{convoId}/notes

add_conversation_note

POST

/agents/{agentId}/convos/{convoId}/notes body { text, authorName? }

update_conversation_note

PATCH

/agents/{agentId}/convos/{convoId}/notes/{noteId} body { text, authorName? }

delete_conversation_note

DELETE

/agents/{agentId}/convos/{convoId}/notes/{noteId}

delete_conversation

DELETE

/agents/{agentId}/convos/{convoId}

export_all_conversations

GET

/agents/{agentId}/convos/export?format=&limit=&cursor=&… (requires paid workspace / hasEverPaid)

export_conversation

GET

/agents/{agentId}/convos/{convoId}/export?format=

assign_conversation

POST

/agents/{agentId}/convos/{convoId}/assign body { assignToUserId, delegatedBy? }

create_kb_from_urls

POST×N or 1

Fan-out / batch POST /agents/{agentId}/kb with sourceType=url + scrapeContent

create_kb_doc

POST

/agents/{agentId}/kb body: KB fields

list_kb_docs

GET

/agents/{agentId}/kb?page&pageSize

get_kb_doc

GET

/agents/{agentId}/kb/{docId}

update_kb_doc

PATCH

/agents/{agentId}/kb/{docId}

patch_kb_doc

GET+PATCH

get_kb_doc then exact old_string→new_string on content/name (Cursor StrReplace-style)

delete_kb_doc

DELETE

/agents/{agentId}/kb/{docId}

get_kb_stats

GET

/agents/{agentId}/kb/stats

scrape_url

HTTP ping or crawler

mode=check (default): fast status for up to 20 URLs/images; mode=scrape: full page scrape (1 URL)

interact_with_agent

WSS

wss://{region}-gcp-api.vg-stuff.com/interact (single InteractObject in, streamed ChunkMessages out)

get_ui_engine_spec

n/a

Static reference — does not hit the API


Tool reference (parameters and notes)

Agent tools

create_agent_from_template — Preferred for from-scratch chat+voice agents. Workspace is resolved internally (no workspaceId input). Recommended explicit fields: title, systemPrompt, voiceConfig (must use speechGen.provider google-live or ultravox only — use search_voices on those providers), primaryColor (hex, from scrape_url colours when possible), widgetImageUrl (logo URL, e.g. favicon from scrape_url). Optional: voicePrompt (Gemini Live systemInstruction; omitted → reuse systemPrompt), description, themeType (light|dark, default light), sourceUrl (optional scrape wait + excerpt), createKbUrlDoc (requires sourceUrl when true), defaultLanguage (default multilingual), proactiveMessage, branding, chatBgURL, additionalConfig.

  • Workflow for the AI: scrape_url first → pick colour + favicon URL → search_voices on google-live / ultravox for accents → then this tool with explicit prompts and full voiceConfig.

  • MCP builds customThemeJSONString (nineColorPallet) from primaryColor (same lightness ramp as Convocore handleAutoGenPallet).

  • After create, MCP calls get_agent and returns data.agent as the full document (plus agentId).

  • Prefer env CONVOCORE_WORKSPACE_ID so MCP does not need to infer workspace from list_agents.

create_agent — Legacy direct mode for advanced/manual payload control. Required: title. Optional: description, theme, disabled, light, enableVertex, autoOpenWidget, voiceConfig, nodes, additionalConfig.

  • Prefer create_agent_from_template unless you intentionally need low-level manual field control.

  • nodes: Convocore’s multi-step graph; nodes[0].instructions is the main system prompt.

  • additionalConfig: Plain object merged into the agent payload (same level as other fields). Use for fields not listed explicitly.

get_agent — Required: agentId. Response includes agent JSON; main prompt is under nodes[0].instructions when present.

update_agent — Required: agentId. Optional: same agent fields as create; patch semantics depend on API. To change the main prompt, update nodes[0].instructions. For large prompts prefer patch_agent_prompt.

patch_agent_prompt — Cursor-style surgical edit. Required: agentId, old_string, new_string. Optional: replace_all, target (auto|nodes0|vg_instructions|vg_systemPrompt|proactiveMessage|customCSS — vg_* still writes nodes[0].instructions), sync_mirrors (default false; never PATCHes vg_instructions). Fails if old_string is missing or ambiguous (unless replace_all).

AI Funnel / lead scoring — funnelConfig + leadCollectionRules on create/update, or ownerNotifyEmails on create_agent_from_template. Runtime emails sales on hot leads. Do not attach a custom HTTP “notify sales” webhook tool.

delete_agent — Required: agentId. Permanent deletion on the API side.

list_agents — Optional: limit (capped fetch when API supports ?limit=). Prefer search_agents or CONVOCORE_WORKSPACE_ID for large workspaces instead of dumping every agent without a cap.

search_agents — Required: none. Optional: search, page (default 1), limit (default 50), sortBy (newest | oldest | alphabetical, default newest), starredOnly (default false). Workspace is resolved internally by MCP.

export_agent — Required: agentId. Returns template JSON for backup/migration.

import_agent — Required: agentTemplate, agentName. Optional: fromAgentId.

get_agent_usage — Required: agentId. Optional: range: { from, to } ISO date strings.

Conversation tools

list_conversations — Required: agentId. Optional: limit (default 20, max 20), cursor (from previous nextCursor). Response: data, hasMore, nextCursor, limit. For page 2+ pass cursor — do not bump page alone (API rejects page>1 without cursor). List reads the Postgres mirror; summary / capturedVariables are often missing on list rows.

get_conversations_bulk — Required: agentId, convoIds (1–50). Fan-out GETs; returns lean { ID, summary, ts, capturedVariables, userName, origin } plus failed[]. Chunk larger audits.

query_conversations — Required: agentId. Optional filters: origin, tsFrom/tsTo, capturedVariableExists, capturedVariableEquals, summaryContains, hasUserName, plus limit / maxScan. MCP-side scan (not SQL).

get_agent_usage_bulk — Required: agentIds (1–20). Optional shared range.

get_kb_docs_bulk — Required: agentId, docIds (1–30). Optional includeContent (default false).

create_conversation — Required: agentId, conversation. The API expects at least a ts (timestamp) in the conversation object; you may add userName, userEmail, etc. per your Convocore setup.

get_conversation — Required: agentId, convoId.

update_conversation — Required: agentId, convoId, conversation (partial fields).

Conversation notes — a timeline of human review notes per conversation (reviewNotes, oldest first; also returned by get_conversation). add_conversation_note / update_conversation_note / delete_conversation_note need agentId, convoId, text / noteId; authorName (optional) labels an API-key caller such as "Claude via MCP". Notes cannot be changed through update_conversation. Every change is recorded in the workspace Logs (who, IP, time). query_conversations accepts hasNotes and noteContains.

delete_conversation — Required: agentId, convoId.

export_all_conversations — Required: agentId. Optional: format (json|csv), limit, sort, fromTs, toTs, cursor, convoIds. Requires a paid workspace (hasEverPaid === true); billed against monthly export quota. Cursor pagination via nextCursor / hasMore.

export_conversation — Required: agentId, convoId. Optional: format — json or csv. Requires a paid workspace (hasEverPaid === true).

assign_conversation — Required: agentId, convoId, assignToUserId. Optional: delegatedBy.

Knowledge base tools

Tool descriptions in code note “VG agents only” — KB operations target /agents/{id}/kb and may only apply to supported agent types on the Convocore side.

create_kb_from_urls — Preferred for many pages. Required: agentId, urls (max 50). Optional: mode (per_url default | batch), name, tags, refreshRate (3d|7d|never), scrapeContent (default true), skipExisting (default true). Uses the KB router to scrape — do not pre-scrape with scrape_url / web fetch. Scraping is async; poll list_kb_docs / get_kb_doc.

create_kb_doc — Required: agentId, name, sourceType: doc | url | sitemap.

  • doc: use content for text.

  • url: use urls (array), optional scrapeContent.

  • sitemap: use sitemapUrl, optional maxPages.

Optional: metadata, tags, refreshRate — 3d | 7d | never (default never; matches Convocore API).

list_kb_docs — Required: agentId. Optional: page (default 1), pageSize (default 20).

get_kb_doc — Required: agentId, docId.

update_kb_doc — Required: agentId, docId. Optional: name, content, metadata, tags, refreshRate, url. For large bodies prefer patch_kb_doc.

patch_kb_doc — Cursor-style surgical edit. Required: agentId, docId, old_string, new_string. Optional: replace_all, field (content|name, default content).

delete_kb_doc — Required: agentId, docId.

get_kb_stats — Required: agentId.

Scrape tool

scrape_url — Provide url and/or urls (max 20).

  • mode: "check" (default): fast HTTP ping — status (200/404/…), ok, content-type, final URL after redirects. Use to verify images, logos, and page links before wiring them into an agent.

  • mode: "scrape": full Convocore crawler scrape of one URL (waits up to ~120s) for text/colours/favicon. Workspace resolved internally. Not for KB ingest (create_kb_from_urls).

Interact (WebSocket) tool

interact_with_agent is the only WebSocket-backed tool. It opens a single connection to wss://{region}-gcp-api.vg-stuff.com/interact, sends one InteractObject, and aggregates every streamed ChunkMessage (chunk / debug / action / metadata / sync_chat_history) into one MCP response. Authentication uses the same Authorization: Bearer <WORKSPACE_SECRET> header as REST.

Required: agentId, convoId.

Common optional:

  • prompt — User message. Special values: "start" (initial greeting), "@cancel:<reason>", "@rewind:<nodeId>" (v2/node agents).

  • bucket — voiceglow-eu or (default). Auto-derived from CONVOCORE_API_REGION (eu-gcp → voiceglow-eu, na-gcp → (default)); only override to deliberately cross regions.

  • messageType + visualPayload — for image turns.

  • replyTo — reply context for a previous message.

  • lightConvoData — userName, userEmail, userPhone, origin, capturedVariables, etc. Surfaced into the agent's system prompt where supported.

  • agentData / workspaceData / turnsHistory — overrides that skip Firestore loads.

  • disableUiEngine, disableRecordHistory, v2, isTest, isLLMStudio, kbPreview, agentProfileId, toolTest, formSubmissionMetadata, initNodesOptions — same flags as the underlying EWSInteractModel.

  • timeoutMs (default 120000, max 600000) — how long the MCP waits for the streamed turn before forcing the WebSocket closed.

  • raw (default false) — when true, the response includes every raw streamed chunk; when false, only the aggregated text + actions + metadata + final turns are returned (cheaper on tokens).

Response shape (default raw: false):

{
  "assistantText": "...",
  "uiEngineEnabled": false,
  "uiEngineSnapshot": null,
  "uiEngineSummary": [],
  "actions": [],
  "metadata": { "inputTokens": 0, "outputTokens": 0, "llmUsed": "...", "sources": [], "turns": [] },
  "turns": [],
  "closeCode": 1000,
  "closeReason": "",
  "durationMs": 1234,
  "timedOut": false,
  "chunkCount": 17
}

UI Engine handling

When the agent has vg_enableUIEngine: true (and the request did not pass disableUiEngine: true), the server streams JSON-stringified TurnProps snapshots instead of plain text. UI Engine snapshots are overwriting (each chunk is a full snapshot of the bot turn so far) — interact_with_agent parses them, keeps only the latest snapshot as uiEngineSnapshot, and produces a compact uiEngineSummary for quick scanning:

{
  "assistantText": "",
  "uiEngineEnabled": true,
  "uiEngineSnapshot": {
    "from": "bot",
    "ts": 1719931200,
    "messages": [
      { "from": "bot", "type": "text",   "item": { "type": "text",   "payload": { "message": "Pick one:" } } },
      { "from": "bot", "type": "choice", "item": { "type": "choice", "payload": { "buttons": [ { "name": "Pricing", "request": { "type": "text", "payload": { "message": "Tell me about pricing" } } } ] } } }
    ]
  },
  "uiEngineSummary": [
    { "index": 0, "type": "text",   "summary": "Pick one:",                 "webChannelOnly": false },
    { "index": 1, "type": "choice", "summary": "1 button: Pricing",         "webChannelOnly": false }
  ],
  "...": "..."
}

The eight UI Engine message types are text, choice, visual, cardV2, carousel, iFrame, form, input. form and input are emitted only on web channels (web-chat / text origin). Call get_ui_engine_spec before testing or building UI-Engine-enabled agents to load the full schema.

Cost note: every call runs a real agent turn (LLM + voice + tools) and consumes Convocore credits exactly like a normal chat. It is not a dry-run.

UI Engine spec tool

get_ui_engine_spec — Returns the full Convocore UI Engine schema. Static knowledge, no API call, no credits.

  • Required: none.

  • Optional: section — "all" (default) | "meta" | "envelopes" | "message_types" | "shared" | "rules" | "checklist" | "primer".

  • Optional: messageType — "text" | "choice" | "visual" | "cardV2" | "carousel" | "iFrame" | "form" | "input". When set, returns just that message-type schema (overrides section).

Use this BEFORE:

  1. Validating output from interact_with_agent against a UI-Engine-enabled agent.

  2. Creating / updating an agent whose system prompt should teach the model to emit UI Engine messages — bake the relevant rules and messageType shapes into nodes[0].instructions.


Convocore concepts: nodes and prompts

  • Each node can represent a step in a workflow.

  • The first node (nodes[0]) holds the primary instructions (instructions field) that define default agent behavior.

  • light mode (agent flag): described in-tool as no chat history retention for privacy.


Errors and validation

  • Invalid tool arguments: Zod validation fails → error with Invalid arguments: ….

  • Unknown tool name: thrown as Unknown tool: ….

  • API errors: thrown with the message from the JSON body when available.

  • Startup: missing WORKSPACE_SECRET → configuration error before the server connects.


Natural language examples (for end users)

After configuration, users can ask their assistant things like:

  • “List all my Convocore agents” → list_agents

  • “Create an agent for this website from scratch” → create_agent_from_template (preferred default)

  • “Export all conversations for agent … as CSV” → export_all_conversations

  • “Add many hotel/site pages to the KB” → create_kb_from_urls (KB router scrapes; do not web-fetch first)

  • “Add one URL / sitemap to the KB” → create_kb_doc with sourceType: url|sitemap + scrapeContent: true

  • “Are these image/page links dead?” → scrape_url with mode: "check" + urls: [...]

  • “Scrape one URL for branding (colours/favicon)” → scrape_url with mode: "scrape"

Exact tool choice and arguments are up to the host model; the tool descriptions in src/index.ts are what the model sees.


Docker

docker pull moe003/convocore-mcp:latest

Common tags (see Docker Hub for current list): latest, version tags such as 2.0.0 / 1.0.x as published by the maintainer.

Build locally:

docker build -t moe003/convocore-mcp:latest .

Docker Compose

The included docker-compose.yml runs the image with stdin open for MCP-style use. Set WORKSPACE_SECRET and optionally CONVOCORE_API_REGION in your environment or an .env file beside the compose file. Authentication is WORKSPACE_SECRET only (no separate API key variable is read by the server).


Development

Command

Action

pnpm install

Install dependencies

pnpm run build

Run tsc → dist/ and chmod the bin

pnpm run dev

tsc --watch

Dependencies: @modelcontextprotocol/sdk, zod, plus file-reader stack (mammoth, pdf-parse, xlsx, sharp, mime-types). Dev: typescript, @types/node, shx.

Publish to npm (maintainers)

pnpm install
pnpm run build
pnpm pack --dry-run     # sanity check the tarball
pnpm publish --access public

prepublishOnly re-runs the build automatically. Only dist/, README.md, and LICENSE are shipped (controlled by the files field in package.json).

Push Docker image (maintainers)

docker push moe003/convocore-mcp:latest

Telemetry

Like Next.js, convocore-mcp collects anonymous usage data to learn which tools are used and where they fail. It is on by default.

What is sent, per tool call: the tool name, whether it succeeded, a short error category (e.g. input_validation_error) plus, for failures only, a short error message with emails, URLs, IDs and numbers removed, the action of action-based tools (e.g. assign_to_agent), how long it took, the MCP client name and version (e.g. Claude Desktop, Cursor), the convocore-mcp version, Node.js version, OS platform, and a random id for the current server process.

What is never sent: tool arguments, tool results, prompts, agent content, contacts, conversations, or any file contents.

Events are batched and sent to the Convocore API in your own region (<base URL>/mcp/telemetry), authenticated with your workspace secret, so they are tied to your workspace and nothing else. Sending happens in the background and never slows down or fails a tool call.

Opt out by setting either variable in your MCP config's env:

"env": {
  "WORKSPACE_SECRET": "...",
  "CONVOCORE_TELEMETRY": "0"
}

DO_NOT_TRACK=1 is respected too. To see exactly what would be sent without sending anything, set CONVOCORE_TELEMETRY_DEBUG=1; events are printed to stderr.

The hosted server at mcp.convocore.ai runs on Convocore infrastructure and records the same events.


Contributing and license

Contributions are welcome via pull request.

MIT License — see the LICENSE file.



Built for the Convocore community.

Available Tools

145 tools
add_conversation_noteAInspect

Add a note to a conversation's notes timeline (visible to the workspace team and clients in the dashboard). Recorded in the workspace Logs with who, IP and time. Max 5000 characters. Prefer this over update_conversation, which cannot change notes.

Inputs: text (required), agentId (required), convoId (required), authorName.

agency_brandingA
Destructive
Inspect

Brand the caller's own whitelabel agency (client portal + login page), like the dashboard Agency settings. Never another agency; whitelabel clients cannot use it. get: current branding, login page and domain status (secrets and provider keys are never returned). update_branding { branding }: only the fields sent change — name, logoUrl (round avatar), darkLogoUrl, wideLogoUrl, wideLogoDarkUrl, faviconUrl, brandingText (markdown), primaryColorHex (#RRGGBB, builds the whole palette), themeType (light | dark), themeVariant (default | bordered | flat | faded), themeColorUsage (gradient | colorful | plain), googleFontStack (Google Fonts families in fallback order, e.g. ["Rubik","Almarai"] = Rubik for Latin/digits, Almarai for Arabic), googleFontWeights (default [400,500,700]), customCSS, defaultLanguage (e.g. "ar" — also sets right-to-left), allowedLanguages, mainWebsite, supportEmail, tosPage, privacyPolicyPage, enableClientSignup, disablePasswordLogin. All URLs must be https. update_login_page { loginPage }: merges into the login page — layout (centered | split), mediaSide (start | end: logical, start = left in LTR / right in RTL), mediaUrl, mediaFit (cover | contain), headline (≤120), subtext (≤300), textPlacement (overlay | below), background { type: theme | color | gradient | image, color, from, to, angle 0-360, imageUrl }, card { style: elevated | bordered | flat | glass, radius: sm | md | lg }, mobileMedia (stack | hide), logo (square | wide | none). Split layout without mediaUrl shows a gradient from the primary colour. reset: true clears it. upload_asset { kind, sourceUrl | base64 }: copies an image onto the Convocore CDN and returns its URL (then pass it to update_branding / update_login_page). kinds: logo, dark_logo, wide_logo, wide_logo_dark (≤1 MB png/jpg/webp/svg), favicon (≤256 KB png/ico/svg), login_media, login_background (≤2 MB webp/png/jpg/svg). Custom domains are claimed and verified on the dashboard only. Confirm the brand values with the user before changing a live portal. Actions: get — current branding, login page and domain status | update_branding — change logos, colour, fonts, language, CSS, links, signup/login options Needs: branding. | update_login_page — customise the client login page (layout, media, text, background, card) | upload_asset — put a logo / favicon / login image on the CDN and get its URL Needs: kind.

Inputs: action (required), kind, mode, reset, +4 more.

agency_readA
Read-onlyIdempotent
Inspect

Get the current agency account for this workspace secret (raw document). For branding (logo, colours, fonts, language, login page) use agency_branding get — it is typed and never returns secrets. Distinct from orgs_read (child organizations) and clients_read (end-user client accounts).

Inputs: no named parameters.

agency_writeA
Destructive
Inspect

Create (upsert with a name) or delete the agency account. To brand it (logo, colour, fonts, language, login page, assets) use agency_branding instead — it validates fields. Domain claims, verification flags, secrets and provider keys cannot be changed here (domains are verified on the dashboard). For org/client CRUD use orgs_write / clients_write.

Inputs: action (required), agency.

agent_backups_readA
Read-onlyIdempotent
Inspect

Read the backups and prompt history of an agent. Check here before a risky change, or to find a version to go back to. Actions: list — saved backups (id, date, author) | latest — the most recent backup | prompt_history — prompt-assistant history with the prompt snapshots that can be restored

Inputs: action (required), agentId (required), mode.

agent_backups_writeA
Destructive
Inspect

Back up or roll back an agent. Take a backup (create) BEFORE large edits with update_agent. restore and revert_prompt overwrite the current agent — confirm with the user and create a backup first. Actions: create — save a backup of the agent as it is now | restore — replace the agent with a saved backup Needs: backupId. | revert_prompt — put back an earlier version of the prompt only Needs: snapshotId. | set_prompt_caching — turn provider prompt caching on or off (cheaper, faster replies for long prompts) Needs: enabled.

Inputs: action (required), agentId (required), mode, enabled, +2 more.

assign_conversationBInspect

Assign a conversation to a user for manual delegation

Inputs: agentId (required), convoId (required), assignToUserId (required), delegatedBy.

bulk_create_kb_docsAInspect

Create up to 20 KB documents in one request. For many website URLs prefer create_kb_from_urls. For a single doc use create_kb_doc.

Inputs: docs (required), agentId (required).

bulk_delete_kb_docsA
DestructiveIdempotent
Inspect

Delete many KB documents in one call (POST .../kb/delete). Prefer over looping delete_kb_doc. Destructive and irreversible.

Inputs: docIds (required), agentId (required).

call_logs_readA
Read-onlyIdempotent
Inspect

Read voice call logs of the workspace (web, inbound and outbound calls). Actions: list (filter by agent, type, phone numbers, date range, search; paginated), get (one call by callLogId — transcript and latency data only with mode="full"), export (JSON or CSV of many calls; includeTranscripts=true to add transcripts). Chat conversations are in list_conversations, not here.

Inputs: action (required), mode, page, type, +13 more.

call_logs_writeA
Destructive
Inspect

Create, edit or delete a call log record. Actions: create (callLog needs agent_id, type web|inbound|outbound, start_time ISO, agent_phone_number and customer_phone_number — null for web calls), update (callLogId + callLog with only the fields to change; agent_id and start_time cannot change), delete (callLogId; permanent). This edits records only — to place a call use start_outbound_call.

Inputs: action (required), mode, callLog, callLogId.

campaigns_readA
Read-onlyIdempotent
Inspect

Read outbound call campaigns of an agent. Actions: list (paginated, with progress counters: totalLeads, contactedLeads, successfulCalls, missingCalls, onGoingCalls), get (one campaign by campaignId). To change campaigns use campaigns_write. WhatsApp broadcast campaigns are not covered.

Inputs: action (required), agentId (required), mode, page, +2 more.

campaigns_writeA
Destructive
Inspect

Create, edit, delete, start/stop or restart an outbound call campaign. Actions: create (campaign needs name + leadGroupName; created stopped unless enabled is true), update (partial: send only the fields to change in campaign), delete, enable (START dialing — places real phone calls to the lead group; resumes where it stopped), disable (stop), restart (start again from the first lead; resetConversations=true also clears earlier call conversations). Campaign fields: name, leadGroupName (a lead group name, or "all"), delayBetweenEachCall (seconds), concurrentSlots, initialPrompt, overrideInitialPrompt, postCallPrompt, postCallMetrics (custom metric ids), openTime / closeTime ("HH:mm" 24h), openDays (monday…sunday), timezone (IANA). The agent needs an assigned phone number before a campaign can start.

Inputs: action (required), agentId (required), mode, campaign, +2 more.

check_twilio_numberAInspect

Repair / re-sync the Twilio SMS/voice webhook configuration for a number (useful when call/SMS routing breaks). This does not check WhatsApp Cloud API health. Pass the full request body for /utils/twilio/check-number as an object — typically includes phoneNumber or phoneNumberSid.

Inputs: payload (required).

clients_readA
Read-onlyIdempotent
Inspect

Read Convocore client accounts (end-user workspaces under an agency/org). Actions: list, get, check_email. For action=list, default mode=compact (id/name/email/orgId). Use mode=full only when you need complete client objects; prefer action=get for one client. Not for organizations (use orgs_read) or CRM leads (use leads_read).

Inputs: action (required), mode, page, email, +3 more.

clients_writeA
Destructive
Inspect

Create/update/delete whitelabel client accounts (people who log into the client portal). Actions: create, update, delete. clientData fields are listed and described in the schema: login (email, dashboardPassword), which agents they see (widgetIDs), portal tabs (canAccess), channels / integrations they may use, org membership, permissions and notifications. For reads use clients_read.

Inputs: action (required), clientId, clientData.

clone_agentAInspect

Clone an existing Convocore agent with optional overrides and carryOver flags (kb, voiceConfig, uiEngineConfig). Never inherits branding or funnel recipients. Prefer this over manually recreating. Distinct from create_agent_from_template / import_agent.

Inputs: agentId (required), carryOver, overrides.

code_toolsA
Destructive
Inspect

Write, check and run CODE tools: JavaScript that runs inside the agent (no server needed), with declared input and output variables. For tools that call an HTTP API use create_agent_tool. Flow: validate → run with sample inputVars → save. Actions: validate — check syntax and the input/output contract without running Needs: code. | run — run the code once with sample inputs and return outputs / logs / errors Needs: code. | ai_edit — have AI rewrite the code for a request (returns code; does not save) Needs: agentId, code, userRequest. | save — create or update the code tool on the agent Needs: agentId, tool.

Inputs: action (required), code, mode, tool, +9 more.

contact_leadsAInspect

Call or text a LIST of leads in one go (real calls / real SMS, billed). channel=call queues an outbound call to each lead; channel=sms sends each lead a message (message required unless sendMode=agent). leads are lead objects from leads_read (they must carry a phone, e.g. userPhone). Max 500 per call. Confirm the audience with the user first. For scheduled, throttled dialing use a campaign (campaigns_write).

Inputs: leads (required), agentId (required), channel (required), from, +6 more.

contacts_readA
Read-onlyIdempotent
Inspect

Read contacts (identities): one person recognised across channels (WhatsApp, Instagram, web chat, calls…). A contact groups that person's conversations. Different from leads_read (the CRM lead list). Actions: list — contacts of the agent, with search | get — one contact profile with its channels and consent Needs: identityId. | timeline — every conversation of the contact across channels, in order Needs: identityId. | audit_log — merge / unmerge / consent history of the contact Needs: identityId.

Inputs: action (required), agentId (required), mode, page, +4 more.

contacts_writeA
Destructive
Inspect

Merge, split, update consent of, or delete a contact. merge and delete cannot be undone automatically — confirm with the user. Actions: merge — merge two contacts that are the same person Needs: sourceIdentityId, targetIdentityId. | unmerge — split conversations out of a contact Needs: identityId, convoIds. | set_consent — record the contact marketing consent Needs: identityId, consentStatus. | delete — delete the contact record Needs: identityId.

Inputs: action (required), agentId (required), mode, convoIds, +5 more.

create_agentAInspect

Create a Convocore agent (advanced/raw). Prefer create_agent_from_template for website/branded agents. Always node-based: enableNodes is forced true; put the main prompt in systemPrompt (or nodes[0].instructions) — do NOT use vg_instructions (API rejects that field). Default chat model is always claude-haiku-4-5-20251001 (Claude Haiku 4.5) on vg_defaultModel + nodes[0].llmConfig.modelId. UI Engine flags optional via vg_enableUIEngine*. Lead notify: use funnelConfig (AI Funnel + lead scoring + email recipients) — do NOT create custom HTTP webhook tools for sales alerts. Sets nodes[0].kb.enabled for auto RAG with maxChunks=3 and vgOptions.maxChunkSize=512 — still bake critical facts into systemPrompt. Do not raise chunk size or chunk count unless the user asks.

Inputs: title (required), light, nodes, theme, +19 more.

create_agent_from_templateAInspect

PRIMARY way to create chat+voice agents. Workspace is resolved internally from MCP configuration/workspace secret context (no workspaceId input). Uses strict template invariants: agentPlatform=vg, enableNodes=true, vg_enableUIEngine=true, vg_enableUIEngineForms=true + form notify, default funnelConfig (lead scoring + email notify), nodes[0].kb.enabled (auto RAG, maxChunks=3, vgOptions.maxChunkSize=512), nodes[0].toolsIds includes built-in web-search, chat model always claude-haiku-4-5-20251001 (Claude Haiku 4.5), standard prompt clauses. vg_* overrides blocked from additionalConfig. NON-SALES agents (registration, internal, support-only): pass leadCapture=false and appendStandardPromptClauses=false (and attachWebSearchTool=false if it must not browse) so no sales text, funnel or lead forms are added. CRITICAL: bake scraped ground-truth AND a labeled image catalog (after read_image on real photos) into systemPrompt — KB alone is not enough. Pass ownerNotifyEmails so the funnel can email sales. Do NOT invent HTTP notify-sales webhooks. Run 8–12 turn tests before declaring done. Response includes prototypeUrl / tryItUrl — ALWAYS paste that link for the user to try the agent. Pattern: https://app.convocore.ai/{eu|na}/prototype/{agentId}. NEVER invent app.convocore.ai/agents/...

Inputs: url, image, title, modelId, +25 more.

create_agent_toolAInspect

Add an HTTP/API tool to a Convocore agent. Requires tool.name + tool.description. INPUTS — either (a) tool.variablesIds: ids of existing agent variables (create_agent_variable first), or (b) tool.fields[]: each entry needs key (the argument name — NOT "name"), type (string|number|boolean), in (body|query|header|path), plus description and required. REQUEST — simple tools: method + serverUrl (inputs are sent by their "in" location). Exact request shape: tool.httpRequest = { enabled: true, method, url, headers, query, bodyType: "json", bodyTemplate, bodyTemplateMode: "exact" }. In bodyTemplate/headers/query/url reference a variable with {{var:VARIABLE_ID}}; a value that is only that token keeps its number/boolean type. Fixed values are written literally. SECRETS — store an API key as an environment variable (create_agent_variable with isEnv: true; the value lives in defaultValue) and reference it with {{var:ID}}. Env variables must NOT be listed in variablesIds: they are resolved automatically and never shown to the model. An unfilled optional input sends its defaultValue; an input with no value and no default blocks the call with "Unresolved request values". By default the new tool is attached to the start node (nodes[].toolsIds) so the model can call it; pass attachToStartNode: false to skip. Verify with test_agent_tool_request.

Inputs: tool (required), agentId (required), attachToStartNode.

create_agent_variableAInspect

Add a variable to a Convocore agent. Typical fields: key, type, defaultValue, description, in (body|query|header|path), required, isEnv, isGlobal. AI inputs: the model fills them; list their ids in a tool variablesIds. An optional input that is not filled sends its defaultValue. Environment variables (isEnv: true) hold fixed config/secrets: the value is stored in defaultValue, is never shown to the model, and is referenced in a tool request as {{var:VARIABLE_ID}} — do not add them to variablesIds. To keep a secret out of this chat, create it with a placeholder defaultValue and have the owner enter the real value in the dashboard: open the tool editor, type { in a request field (or use Variables), open the variable, keep ENV on and fill "Value". Responses mask env values.

Inputs: agentId (required), variable (required).

create_conversationBInspect

Create a new conversation for an agent

Inputs: agentId (required), conversation (required).

create_kb_docAInspect

Add one knowledge base source (VG agents). For many page URLs use create_kb_from_urls instead. For websites: sourceType=url with urls[] + scrapeContent=true (KB router scrapes). For whole-site: sourceType=sitemap + sitemapUrl + maxPages + scrapeContent=true. sourceType=doc only for raw text you already have — do not paste web-fetched HTML here.

Inputs: name (required), agentId (required), sourceType (required), tags, +7 more.

create_kb_from_urlsAInspect

PREFERRED for adding many website pages to an agent KB. Pass up to 50 URLs; the Convocore KB router scrapes them (scrapeContent=true). Do NOT web-fetch/scrape_url then paste content into create_kb_doc — that is slow and duplicates work. mode=per_url (default): one KB doc per URL. mode=batch: one API call with urls[]. For a whole site prefer create_kb_doc sourceType=sitemap. Scraping is async — poll list_kb_docs/get_kb_doc for status.

Inputs: urls (required), agentId (required), mode, name, +5 more.

create_kb_imageBInspect

Upload images into the agent KB (optional autoCaption). Backup after you already called read_image and labeled the photos in the system prompt — not a substitute for looking at them.

Inputs: images (required), agentId (required), targetDocName (required), tags, +1 more.

custom_metrics_readA
Read-onlyIdempotent
Inspect

Read the custom analytics metrics of an agent (values the AI extracts from each conversation or call, e.g. customer_satisfaction, booked_meeting). Actions: list, get (metricId), data (aggregated values for one metricKey in a time range: averages/sums for numbers, counts for boolean/enum/string), all_data (same for every metric). Time range defaults to the last 30 days; startTs/endTs are unix seconds. includeTimeSeries adds per-day points.

Inputs: action (required), agentId (required), mode, endTs, +6 more.

custom_metrics_writeA
Destructive
Inspect

Create, edit or delete a custom analytics metric on an agent. Actions: create (metric needs key + type + description; type enum also needs options), update (metricId + metric with only the fields to change; changing type can make old data inconsistent), delete (metricId; historical data stays but the metric stops being tracked). Metric: { key, type: number|boolean|enum|string, options?, description? }.

Inputs: action (required), agentId (required), mode, metric, +1 more.

delete_agentB
Destructive
Inspect

Delete a Convocore agent permanently

Inputs: agentId (required).

delete_agent_toolA
DestructiveIdempotent
Inspect

Permanently delete a Convocore agent HTTP tool by toolId. Does not delete MCP tools.

Inputs: toolId (required).

delete_agent_variableB
DestructiveIdempotent
Inspect

Permanently delete a Convocore agent variable by variableId.

Inputs: variableId (required).

delete_conversationC
Destructive
Inspect

Delete a conversation

Inputs: agentId (required), convoId (required).

delete_conversation_noteA
DestructiveIdempotent
Inspect

Delete one note. Any user with access may delete any note; a full copy is kept in the workspace Logs with who deleted it, from which IP and when. Only call when the user asked to delete that note.

Inputs: noteId (required), agentId (required), convoId (required), authorName.

delete_kb_docB
Destructive
Inspect

Delete a knowledge base document (VG agents only)

Inputs: docId (required), agentId (required).

disconnect_meta_pageA
Destructive
Inspect

Disconnect a Facebook page from an agent: the agent stops answering Messenger and Instagram for that page. pageId comes from get_agent_channels. Confirm with the user first. To connect a page use create_channel_connect_link.

Inputs: pageId (required), agentId (required).

email_channel_readA
Read-onlyIdempotent
Inspect

Read the email channel setup of the workspace: sending domains (with the DNS records to add and their verification state), inboxes (addresses agents answer) and recent email events. Actions: domains — sending domains | inboxes — inboxes and their assigned agent | recent_events — recent inbound / outbound email events

Inputs: action (required), mode, limit, orgId.

email_channel_writeA
Destructive
Inspect

Set up and operate the email channel. Flow: create_domain → the user adds the returned DNS records at their DNS provider → verify_domain → create_inbox (address = localPart@domain) assigned to an agent. send_human_reply sends a real email. Actions: create_domain — register a sending domain and get its DNS records Needs: domain. | refresh_domain — re-read the domain status Needs: domainId. | verify_domain — ask for DNS verification after the records were added Needs: domainId. | delete_domain — remove a sending domain (its inboxes stop working) Needs: domainId. | create_inbox — create an address on a verified domain Needs: domainId, localPart. | update_inbox — change display name, assigned agent, active flag or settings Needs: inboxId. | delete_inbox — delete an inbox Needs: inboxId. | send_human_reply — reply to an email conversation as a human, from the inbox Needs: inboxId, reply.

Inputs: action (required), mode, orgId, reply, +8 more.

export_agentB
Read-onlyIdempotent
Inspect

Export an agent template for backup or migration. For import/export, rely on these dedicated OpenAPI routes instead of trying to manually construct the template shape.

Inputs: agentId (required).

export_all_conversationsA
Read-onlyIdempotent
Inspect

Export conversations for an agent (Postgres mirror). Requires a paid workspace (hasEverPaid === true); billed against monthly export quota. Supports cursor pagination via cursor/nextCursor/hasMore, or selected mode via convoIds. Formats: json|csv.

Inputs: agentId (required), sort, toTs, limit, +4 more.

export_conversationA
Read-onlyIdempotent
Inspect

Export a single conversation. Requires a paid workspace (hasEverPaid === true); billed against monthly export quota.

Inputs: agentId (required), convoId (required), format.

folders_readA
Read-onlyIdempotent
Inspect

Read the agent folders of the workspace (the folders that group agents on the dashboard). Actions: list (all folders with their agentIDs), get (one folder by folderId, or by exact name).

Inputs: action (required), mode, name, folderId.

folders_writeA
Destructive
Inspect

Create, edit or delete agent folders and move agents in or out. Actions: create (folder needs name; optional color, icon, starred, parentFolderID, agentIDs), update (folderId + folder with only the fields to change — use this to rename), delete (folderId; removes the folder only, agents are kept), add_agent / remove_agent (folderId + agentId).

Inputs: action (required), mode, folder, agentId, +1 more.

generate_conversation_summariesA
Read-only
Inspect

Generate one-paragraph AI summaries for up to 25 conversations, in each conversation language. Simple form: agentId + convoIds (transcripts are loaded for you). Advanced: items [{ convoId, transcript }] with your own text. Returns the summaries only — it does not store them (use update_conversation to save one).

Inputs: mode, items, agentId, convoIds.

generate_lead_funnelA
Read-onlyIdempotent
Inspect

Draft lead-funnel steps (qualification stages and scoring) from an agent prompt with AI. Returns the suggested steps only — save them with update_agent funnelConfig. Pass the agent prompt text; get it from get_agent if needed. Actions: generate — suggest funnel steps

Inputs: action (required), agentPrompt (required), mode, userNotes, +1 more.

get_agentA
Read-onlyIdempotent
Inspect

Retrieve details of a specific Convocore agent. Main prompt is always nodes[0].instructions (enableNodes is true for agents created via this MCP). Legacy vg_instructions only if nodes are absent on a very old agent. ownerID is the workspaceId and is read-only. Response includes prototypeUrl / tryItUrl — share that public demo with the user (https://app.convocore.ai/{eu|na}/prototype/{agentId}). Never invent /agents/ links.

Inputs: agentId (required).

get_agent_audit_logA
Read-onlyIdempotent
Inspect

Read the change history of an agent: who changed what and when (newest first). Use it to explain an unexpected behaviour change or find when a setting was edited. Paginate by passing the ts of the last entry as cursorTs.

Inputs: agentId (required), mode, limit, cursorTs.

get_agent_channelsA
Read-onlyIdempotent
Inspect

Check which channels are connected to an agent: WhatsApp numbers and Facebook pages (Messenger, plus Instagram when an Instagram account is linked to the page). Use it to answer "is my WhatsApp / Instagram connected?" and to confirm a connection after the user finished a connect link. Credentials are never returned. For WhatsApp reply rules use get_whatsapp_ai_rules.

Inputs: agentId (required), mode.

get_agent_custom_cssA
Read-onlyIdempotent
Inspect

Read the agent's current customCSS field (the per-agent CSS override applied to the chat widget). Returns the raw CSS string (empty string if none set). Use this before editing so you can produce a merged result for update_agent_custom_css.

Inputs: agentId (required).

get_agent_phoneA
Read-onlyIdempotent
Inspect

Get the phone number(s) assigned to an agent for voice calls. Check this before start_outbound_call — an agent without a number cannot call.

Inputs: agentId (required), mode.

get_agent_toolA
Read-onlyIdempotent
Inspect

Get one Convocore agent HTTP tool by toolId (includes fields, serverUrl, method). Does not call the remote URL — use test_agent_tool_request for that.

Inputs: toolId (required).

get_agent_usageB
Read-onlyIdempotent
Inspect

Get agent usage statistics and credits consumed

Inputs: agentId (required), range.

get_agent_usage_bulkB
Read-onlyIdempotent
Inspect

Fetch usage/credits for many agents in one call (fan-out). Max 20 agentIds. Optional shared date range.

Inputs: agentIds (required), range.

get_agent_variableA
Read-onlyIdempotent
Inspect

Get one Convocore agent variable by variableId. The value of an environment variable (isEnv) is masked.

Inputs: variableId (required).

get_channel_integration_specA
Read-onlyIdempotent
Inspect

Return static Convocore channel-integration schema guidance for MCP clients. Use this before configuring or explaining WhatsApp, Facebook Messenger, Instagram, or SMS routing. It clarifies canonical storage locations, safe update fields, read-only/system-managed fields, credential masking, WhatsApp coexistence/AI behavior settings, Messenger/Instagram page mapping, and why Twilio SMS tools must not be used for WhatsApp Cloud API numbers. Static knowledge — does NOT hit the API.

Inputs: section.

get_conversationC
Read-onlyIdempotent
Inspect

Get details of a single conversation

Inputs: agentId (required), convoId (required).

get_conversations_bulkA
Read-onlyIdempotent
Inspect

Fetch lean summaries for many conversation IDs in one call (fan-out GETs with concurrency). Returns {ID, summary, ts, capturedVariables, userName, origin} per convo. Max 50 IDs per call — chunk larger audits. Workflow: list_conversations with cursor to collect IDs, then this tool (do NOT loop get_conversation).

Inputs: agentId (required), convoIds (required).

get_kb_docC
Read-onlyIdempotent
Inspect

Get a single knowledge base document

Inputs: docId (required), agentId (required).

get_kb_docs_bulkA
Read-onlyIdempotent
Inspect

Fetch many KB documents in one call (fan-out). Max 30 docIds. Default returns compact metadata + chunksPreview; set includeContent=true for full bodies.

Inputs: docIds (required), agentId (required), includeContent.

get_kb_quotaA
Read-onlyIdempotent
Inspect

Get workspace KB document quota usage (GET /workspace/kb-docs/quota). Optional workspaceId; defaults to the authenticated workspace.

Inputs: workspaceId.

get_kb_statsB
Read-onlyIdempotent
Inspect

Get knowledge base statistics for an agent (VG agents only)

Inputs: agentId (required).

get_pricing_infoA
Read-onlyIdempotent
Inspect

Return Convocore pricing information so the assistant can quote plans, add-ons, voice/chat cost rules of thumb, credit conversions, and per-model token prices to the user. Use section to narrow the response: "plans", "add_ons", "credits", "rules_of_thumb", "models", "voice_providers", "faq", or "all" (default). When section="models", optionally pass modelFilter (substring match on model name or provider, e.g. "gpt", "claude") to only return matching rows. Static knowledge — does NOT hit the API and does NOT consume credits. Always remind users that prices may change and direct them to https://convocore.ai/pricing for the live numbers.

Inputs: section, modelFilter.

get_ui_engine_specA
Read-onlyIdempotent
Inspect

Return the FULL Convocore UI Engine schema (the structured message format agents emit when vg_enableUIEngine: true). ALWAYS CALL THIS FIRST when: (a) testing a UI-Engine-enabled agent via interact_with_agent and you need to validate the output, OR (b) creating / updating an agent that should produce UI Engine output (so the system prompt teaches the LLM to emit valid text / choice / visual / cardV2 / carousel / iFrame / form / input / invoice / calendarBooking messages). Also documents agent feature flags (vg_enableUIEngineForms, vg_enableUIEngineInvoice, vg_enableUIEngineCalendarBooking, vg_uiEngineChannelConfig) used by update_agent to allow/deny which UI elements the agent may show. Returns: meta (streaming + channel-gating + agentFeatureFlags), envelopes (TurnProps / ChatMessage), messageTypes, shared types, rules, and a validationChecklist. Use section to narrow the response: "meta" | "envelopes" | "message_types" | "shared" | "rules" | "checklist" | "primer" | "all" (default). Use messageType to drill into a single message-type schema (e.g. "choice" or "form"). Static knowledge — does NOT hit the API and does NOT consume credits.

Inputs: section, messageType.

get_voiceA
Read-onlyIdempotent
Inspect

Fetch full metadata + a preview MP3 URL for a single voice. Use after the user picks one from search_voices / list_provider_voices, or when they paste a voice ID. Read-only — does NOT consume credits.

Inputs: voiceId (required), provider (required).

get_website_embed_codeA
Read-onlyIdempotent
Inspect

MUST CALL whenever the user asks to deploy/embed/add their agent to a website, get the widget script, iframe code, popup chat bubble, or 'where is the code'. Returns a ready-to-paste HTML snippet with the real agent ID and region filled in (popup, full-width inline, modal, or React voice-only example). Do NOT redirect the user to the dashboard Channels/Deployment tab instead of returning this code. If agentId is unknown, call list_agents first, then call this tool.

Inputs: agentId (required), mode, containerWidth, containerHeight.

get_whatsapp_ai_rulesA
Read-onlyIdempotent
Inspect

Read the WhatsApp "AI rules" of a Convocore agent: the rules that decide whether the AI replies to an inbound WhatsApp message (dashboard: Channels → WhatsApp → AI rules). Returns inboundEngagement (null when never configured — then the AI replies to everything except what the legacy per-number guards block), the defaults, every WhatsApp number assigned to the agent with its phoneId and AI settings (aiPaused, newContactsOnly, coexistenceSettings), and warnings for configurations that keep the AI silent. Meta credentials are never returned. Call this before update_whatsapp_ai_rules / update_whatsapp_number_settings.

Inputs: agentId (required).

get_widget_css_styling_guideA
Read-onlyIdempotent
Inspect

MUST CALL FIRST whenever the user asks to style/restyle/theme the Convocore (vg) chat widget — e.g. 'change the icons to black', 'make the header purple', 'recolor the send button', 'theme the widget dark', 'change the user bubble color', 'restyle the proactive teaser'. Returns the FULL authoritative styling guide (the same SYSTEM_PROMPT used by Convocore's server-side AI CSS generator) including: (a) the global output rules (always wrap in ```css, always !important, never invent class names), (b) the CRITICAL compound-element CASCADE rule for color/icon changes (.vg-foo, .vg-foo , .vg-foo svg, .vg-foo path { color + stroke }), (c) hard constraints (don't color .vg-message-inner-container-human, don't hide the input, etc.), (d) the COMPLETE class & id map (.vg- selectors for every part of the widget — header, footer input, send button, messages, proactive bubble, notices, cards, voice mode, live agents, etc.), (e) the NextUI/Tailwind color system, and (f) ready-made selector recipes mapping plain-English asks to selectors. If you pass agentId, the agent's current customCSS is appended so the model can refine/extend it instead of duplicating rules. After calling this, generate CSS that strictly follows the guide, then call update_agent_custom_css to persist it.

Inputs: agentId.

import_agentAInspect

Import an agent from a template produced by export_agent / the OpenAPI export-template route. The template shape is complex; do not invent it manually unless the user provides an exact exported object.

Inputs: agentName (required), agentTemplate (required), fromAgentId.

import_file_to_kbAInspect

End-to-end shortcut: read any supported file (PDF / DOCX / XLSX / CSV / TXT / MD / JSON / HTML) and create a Knowledge Base document on the target agent in one call. The file is parsed locally to text/markdown and pushed to the agent's KB via create_kb_doc with sourceType='doc'. Use pages for PDFs and sheet for spreadsheets to control what gets ingested. Images are NOT supported here (they need OCR or vision — use read_image instead).

Inputs: agentId (required), url, data, name, +6 more.

import_twilio_numberAInspect

Import a Twilio SMS/voice number you already own into the workspace (uses your Twilio account credentials). This is NOT a WhatsApp Cloud API connection; do not use it for waNumbers/Meta WhatsApp. Pass the full request body for /utils/import-twilio-number as an object — typically includes your Twilio account SID, auth token, the phone number, optional agentId and capabilities.

Inputs: payload (required).

inspect_fileA
Read-onlyIdempotent
Inspect

Cheap probe of a file (path / url / base64). Returns kind, mime, size, page count (PDF), sheet names (XLSX), line count (text), or pixel dimensions (image), plus an estimated token cost. ALWAYS call this first on anything larger than a few KB — use it to decide which read_* tool to call and which slice (pages / sheet / range) to request, so you don't blow the context window.

Inputs: url, data, path, mimeType.

integrations_readA
Read-onlyIdempotent
Inspect

See every integration of the workspace exactly like the dashboard Integrations page: Google Calendar, Outlook Calendar, Google Sheets, Airtable, Shopify, Calendly, Zoho CRM, Gmail, Outlook mail, Zoho Mail and Google Drive. Start with all_connections (every connection id, account, and which agents use it), then agent_integrations to see and debug what one agent has configured (it lists problems such as a missing calendar, a deleted connection or an inbox whose notifications stopped). resources lists what can be picked for an agent: calendars (google_calendar / outlook_calendar), spreadsheet tabs + header columns (google_sheets, pass sheetId), Airtable bases then tables + fields (pass baseId), Calendly event types, Zoho CRM modules, Shopify store check. A first connection (OAuth login) is always made by the user on the dashboard Integrations page; everything after that is done with integrations_write and integrations_test. Actions: all_connections — every connection of every integration, with the agents using each | agent_integrations — one agent's integrations, settings and detected problems Needs: agentId. | resources — calendars / sheet tabs + headers / Airtable bases, tables, fields / Calendly event types / Zoho modules / Shopify check Needs: type. | calendly_event_types — Calendly event types that can be offered by agents | outlook_connections — connected Outlook accounts | outlook_calendars — calendars of a connected Outlook account Needs: connectionId. | zoho_connections — connected Zoho CRM accounts | zoho_modules — Zoho modules (Leads, Contacts, Deals…) Needs: connectionId. | zoho_fields — fields of a Zoho module Needs: connectionId, moduleApiName. | zoho_agent_config — how an agent syncs with Zoho (lookup and field mapping) Needs: agentId. | zoho_assigned_agents — agents that use Zoho CRM

Inputs: action (required), mode, type, force, +10 more.

integrations_testA
Destructive
Inspect

Test an agent's integration tools with the agent's REAL runtime code and settings. inspect (no side effects): the exact tool names, descriptions and parameters the agent sees for that integration — use it to debug why the agent misuses a tool. run: executes one of those tools with the given args, exactly as if the agent called it, and returns its output or error. Safe checks first: google-calendar / outlook-calendar check-availability or lookup-events, google-sheets read / lookup, airtable read, shopify read, calendly list_event_types / check_availability. create / update / delete events, sheet writes and Airtable creates really happen — confirm with the user before running those. Actions: inspect — what the agent sees for this integration (names, descriptions, parameters) | run — run one tool with args, as the agent would

Inputs: action (required), toolId (required), agentId (required), args, +3 more.

integrations_writeA
Destructive
Inspect

Add, change or remove an integration on an agent, exactly like the dashboard. assign_to_agent also updates an existing setup (call it again with new settings); remove_from_agent removes it. settings by type — google_calendar / outlook_calendar: { connectionId, calendarId, calendarName?, timezone? ("Europe/London" or "GMT+1"), label?, description?, methods? (create-event, check-availability, lookup-events, update-event, delete-event), bookingMode? ("route" = caller picks one calendar, "union" = any free calendar), defaultCallerTimezone? ("" = same as calendar, "ask", or a zone), disableMeetLink? (google, in-person) } — up to 5 calendars per agent; remove one with { calendarId } or all with {}. google_sheets: { connectionId, sheetId, sheetTabName, method: "read" | "lookup" | "write", sheetName?, sheetDescription?, headerRowIndex?, headerDescriptions? {column: meaning}, identifierColumn?, identityFields? { phone, email, name, custom, customLabel } } — up to 5 sheets; remove one with { sheetId }. airtable: { connectionId, baseId, tableId?, method?, fieldDescriptions?, identifierField? }. shopify: { connectionId }. calendly: { connectionId }. zoho_crm: { config } (draft it with zoho_auto_configure; config.logTranscript keeps a note with the real messages, including human replies from WhatsApp/dashboard). gmail / outlook_mail / zoho_mail (the agent answers that inbox): { connectionId, whenToReply? (always | keywords | sentiment | manual), replyDelayMinutes?, replyRule?, humanNotifyRule?, replyLength? (short | medium | long | auto), replyTone?, keywords?, ignoreKeywords?, humanTakeoverEnabled?, humanTakeoverTimeoutMinutes?, notifyWorkspaceOwners? } — also starts inbound notifications. Get ids from integrations_read (all_connections, resources). After assigning, verify with integrations_read agent_integrations and integrations_test. Actions: assign_to_agent — add or update an integration on an agent Needs: agentId, type, settings. | remove_from_agent — remove an integration (or one calendar / sheet / inbox) from an agent Needs: agentId, type. | calendly_save_event_types — choose which Calendly event types agents may offer Needs: connectionId, selectedEventTypes. | calendly_assign_agents — give agents the Calendly booking ability Needs: connectionId, agentIds. | calendly_remove_agent — remove Calendly from an agent Needs: agentId. | google_calendar_disconnect — disconnect a Google Calendar account (confirm first; refused while agents use it unless force) Needs: connectionId. | outlook_disconnect — disconnect an Outlook account (confirm first) Needs: connectionId. | zoho_disconnect — disconnect a Zoho account (confirm first) Needs: connectionId. | zoho_auto_configure — let AI draft a Zoho sync config from the CRM fields (does not save) Needs: connectionId. | zoho_test_lookup — try a config against the CRM with a phone / email, without saving Needs: config. | zoho_save_agent_config — save the Zoho sync config on an agent Needs: agentId, config. | zoho_remove_agent — remove Zoho CRM from an agent Needs: agentId.

Inputs: action (required), mode, type, email, +12 more.

interact_with_agentAInspect

Run ONE agent turn over the Convocore /interact WebSocket and return the streamed result aggregated into a single response. Opens a WSS connection to wss://-gcp-api.vg-stuff.com/interact, sends one InteractObject (agentId + convoId + bucket + prompt + optional context), collects every chunk (text + UI-engine + actions + metadata + sync_chat_history) until the server closes (code 1000) or the timeout fires, then returns: { assistantText, uiEngineEnabled, uiEngineSnapshot, uiEngineSummary, actions, metadata, turns, closeCode, durationMs, timedOut, chunkCount, chunks? }.

USAGE:

  • Use the SAME convoId across turns to keep history; use a fresh one to start a new conversation.

  • prompt: "start" triggers the agent's initial greeting (no user message added).

  • prompt: "@cancel:<reason>" cancels an in-flight turn (rarely useful from a single MCP call).

  • prompt: "@rewind:<nodeId>" rewinds a node-based agent.

  • For images, set messageType="visual" and pass visualPayload.

  • bucket is auto-derived from CONVOCORE_API_REGION; only override if you really mean to talk to the other region.

  • Set raw: true to include every streamed chunk (debug frames, chunkIndex, every UI Engine snapshot, etc.) when you need the full trace. Default keeps the response token-cheap.

  • TESTING: set isTest: true for test chats. Pass toolTest: { toolId, toolName, mode: validate|generate-and-test } to exercise one HTTP tool (or use dedicated test_agent_tool). Pass variablesOverrides / initNodesOptions to trial variables without permanently changing them.

  • For a direct HTTP dry-run of a tool's serverUrl use test_agent_tool_request. For multi-turn suites use run_agent_auto_test.

INTERPRETING THE RESPONSE:

  • When uiEngineEnabled: false, the agent streamed plain Markdown — read assistantText.

  • When uiEngineEnabled: true, the agent streamed UI Engine snapshots — read uiEngineSnapshot (parsed final TurnProps) and uiEngineSummary (compact per-message summary). assistantText may be empty in this mode.

  • To force plain text on a UI-Engine-enabled agent for one turn, pass disableUiEngine: true.

UI ENGINE — TWO LAYERS YOU MUST KEEP STRAIGHT:

LAYER 1 — AGENT LLM OUTPUT CONTRACT (what the tested agent is INSTRUCTED to emit):

  • The agent's system prompt forces its LLM to output ONE JSON ARRAY of message objects: [ { "type": "text"|"choice"|"visual"|"cardV2"|"carousel"|"iFrame"|"form"|"input", "payload": {...} }, ... ]

  • The very first character MUST be "[" and the very last MUST be "]". No prose, no ```json fences, no leading/trailing newlines.

  • Preferred message order in the array: text intro -> card / carousel / visual -> iFrame (if video URL exists) -> choice buttons (CTAs).

  • Buttons / image URLs / iFrame URLs MUST come from KB or tool output. NEVER invent URLs. If KB has nothing, omit the button or fall back to text.

  • select / radio fields MUST include a non-empty options[] of { value, label }. If real options are unknown, use type "text" or "textarea" instead.

  • form / input messages WEB CHANNELS ONLY (web-chat / text). On voice / telephony / WhatsApp / SMS / messaging the server strips them.

  • WhatsApp extra rule: only use visual / cardV2 / carousel when you have a verified image URL from KB or a tool — otherwise use text only.

LAYER 2 — WIRE FORMAT (what arrives over the /interact WebSocket):

  • When chunk.ui_engine === true, chunk.chunk is a JSON-stringified TurnProps SNAPSHOT of the bot turn so far.

  • SNAPSHOTS ARE OVERWRITING — replace the in-progress turn with the latest parse, never concatenate.

  • Parsed shape: { from: "bot", ts, modelId?, messages: ChatMessage[] }.

  • Each ChatMessage wraps the agent's array entry: { from: "bot", type, ts, mid?, item: { type, payload } }. So agent emits [{ type, payload }, ...] -> wire wraps each as { ..., item: { type, payload } } inside messages[].

PAYLOAD SHAPES (item.payload): text -> { message } (Markdown supported). choice -> { buttons: [{ name, request: { type: "open_url"|"text", payload: { url|message } } }] }. visual -> { image } (URL ending in .png/.jpg/.jpeg/.webp/.gif/.svg/.avif/.bmp). cardV2 -> { title, imageUrl?, description?: { text }, buttons?: UiEngineButton[] }. carousel -> { cards: CardPayload[] }. iFrame -> { layout: "vertical"|"horizontal", url } (vertical = video embeds, horizontal = general web). form -> { title?, description?, fields: UiEngineInputField[], submitButton?, onSubmit: { type: "submit_form", message? } }. Web channels only. input -> { field: UiEngineInputField, submitOnEnter?, onSubmit: { type: "submit_input", message? } }. Web channels only. UiEngineInputField.type: text|email|password|number|tel|url|textarea|select|checkbox|radio|date|time|datetime-local|file.

WHEN ui_engine === false (or omitted): chunk.chunk is plain Markdown text — append to the in-progress assistant message. TO FORCE PLAIN TEXT on a UI-Engine-enabled agent for one turn: pass disableUiEngine: true on the InteractRequest.

SERVER SANITIZERS YOU SHOULD KNOW (so you do not get surprised when a message disappears):

  • form messages with zero valid fields are DROPPED.

  • input messages with an invalid field are DROPPED.

  • select / radio fields with empty / duplicate / missing-label options are DROPPED.

  • any field missing id or label is DROPPED.

For the FULL UI Engine schema (every payload field, validation rules, allowed enums) call get_ui_engine_spec first.

WARNING: This consumes Convocore credits exactly like a real agent turn (LLM + voice + tools). It is NOT a dry-run.

Inputs: agentId (required), convoId (required), v2, raw, +22 more.

lead_groups_readA
Read-onlyIdempotent
Inspect

List the lead groups of an agent with the number of leads in each. Groups are what campaigns target (campaign.leadGroupName). Optional tags only counts leads carrying at least one of the tags. To see the leads inside a group use leads_read with groupName.

Inputs: agentId (required), mode, tags.

lead_groups_writeA
Destructive
Inspect

Create, fill, rename or delete a lead group. Group names are stored lowercase. Actions: create (groupName + leads: new lead objects, e.g. [{ userName, userPhone, userEmail }] — a group exists only while it has leads), assign_leads (groupName + leadIds: move EXISTING leads into the group; groupName "all" removes them from any group), rename (groupName + newGroupName: moves every lead to the new name), delete (groupName: by default the leads are kept and just ungrouped; deleteLeads=true permanently deletes every lead in the group).

Inputs: action (required), agentId (required), groupName (required), mode, +4 more.

leads_readA
Read-onlyIdempotent
Inspect

Read CRM leads for an agent. Actions: list, get, export, export_filtered. For action=list, default mode=compact (id/name/email/phone/ts — no metaData blobs). Use mode=full only when you need complete lead objects; prefer action=get for one lead. Does not create/update — use leads_write. Not for client accounts (clients_read).

Inputs: action (required), agentId (required), mode, page, +11 more.

leads_writeB
Destructive
Inspect

Create/update/delete/import CRM leads. Actions: create, update, delete, delete_many, import_bulk, magic_import, clear_all, delete_group. Destructive: clear_all deletes every lead on the agent.

Inputs: action (required), agentId (required), lead, leads, +6 more.

list_agentsA
Read-onlyIdempotent
Inspect

List accessible agents. Default mode="compact" returns only short fields (id, title, description, theme, flags, timestamps) so responses stay token-cheap — use this to find recent agents. mode="full" returns complete agent documents (nodes/prompts/voice/etc.) and is heavy; prefer get_agent for one agent, or search_agents for filtered lookup. Compact defaults limit=25 when omitted.

Inputs: mode, limit.

list_agent_toolsA
Read-onlyIdempotent
Inspect

List HTTP/API tools saved on a Convocore agent (serverUrl integrations). These are NOT MCP tools. A saved tool is only callable when its id is also in a node toolsIds (see get_agent). For MCP catalog discovery use search_mcp_tools. To test a tool use test_agent_tool or test_agent_tool_request.

Inputs: agentId (required).

list_agent_variablesA
Read-onlyIdempotent
Inspect

List variables on a Convocore agent (env/global/system keys used in prompts and tools). Not MCP variables. Values of environment variables (isEnv) are masked. To trial overrides in a chat turn use interact_with_agent with variablesOverrides / initNodesOptions.

Inputs: agentId (required).

list_conversation_notesA
Read-onlyIdempotent
Inspect

List the human review notes on a conversation (a timeline, oldest first). Each note has id, text, createdAt (unix seconds), authorName/authorEmail and source (dashboard | api). get_conversation also returns them as reviewNotes. To find conversations by note, use query_conversations with hasNotes / noteContains.

Inputs: agentId (required), convoId (required).

list_conversationsA
Read-onlyIdempotent
Inspect

List conversations for an agent (newest first). Default mode=compact (id/ts/summary/user/origin — no messages). mode=full returns raw list rows. For message bodies use get_conversation or get_conversations_bulk. Cursor pagination: hasMore + nextCursor; do NOT bump page alone. Max limit=20.

Inputs: agentId (required), mode, page, limit, +1 more.

list_kb_docsA
Read-onlyIdempotent
Inspect

List knowledge base documents for an agent. Default mode=compact (id/name/status/urls — NO content bodies). Use mode=full only if you need every list field; prefer get_kb_doc for one document body.

Inputs: agentId (required), mode, page, pageSize.

list_provider_voicesA
Read-onlyIdempotent
Inspect

Browse the voice catalog for ONE specific provider with the same filter params as search_voices. Use when the user has already chosen a provider (e.g. "show me ElevenLabs male British voices"). Read-only — does NOT consume credits.

Inputs: provider (required), limit, accent, gender, +3 more.

list_voice_modelsA
Read-onlyIdempotent
Inspect

List the available TTS models for a given provider (e.g. "aura-2" for Deepgram, "eleven_multilingual_v2" for ElevenLabs). Use the returned modelId values with search_voices / list_provider_voices to filter the catalog. Read-only — does NOT consume credits.

Inputs: provider (required).

list_voice_providersA
Read-onlyIdempotent
Inspect

List every TTS voice provider Convocore supports (elevenlabs, deepgram, cartesia, rime-ai, openai, google-cloud, google-live (Gemini Live), ultravox, minimax, playht, azure). For each provider returns the workspace secret-key name (e.g. ELEVENLABS_API_KEY) and a requiresWorkspaceApiKey flag indicating whether the platform has a server-side fallback or the workspace must BYOK. Read-only — does NOT consume credits.

Inputs: no named parameters.

meta_pages_readA
Read-onlyIdempotent
Inspect

Diagnose a connected Facebook page (Messenger / Instagram). To list connected pages use get_agent_channels; to connect one use create_channel_connect_link. Actions: check_subscriptions — which webhook events the page is subscribed to — use when the agent does not receive Messenger / Instagram messages Needs: pageId. | get_profile — name and picture of a Messenger / Instagram user who messaged the agent Needs: userId.

Inputs: action (required), agentId (required), mode, origin, +2 more.

notification_emailAInspect

Manage an email address subscription to Convocore notification emails. The address owner must confirm with a 6-digit code. Actions: request_code (email: sends the code), verify_code (email + code: returns a token), set_subscription (token + subscribed true/false), unsubscribe (token). You cannot read the code yourself — ask the user for it.

Inputs: action (required), code, email, token, +1 more.

orgs_readA
Read-onlyIdempotent
Inspect

Read organizations and related membership. Actions: list, search, get, list_clients, list_agents, list_members_and_teams, list_agent_org_clients. List/search actions default mode=compact (short fields). Use mode=full only when you need complete objects; prefer action=get for one org. Does NOT create/update/delete — use orgs_write. For end-user client accounts use clients_read.

Inputs: action (required), mode, page, orgId, +3 more.

orgs_writeA
Destructive
Inspect

Create/update/delete organizations or assign/unassign an agent to an org. Actions: create, update, delete, assign_agent. For reads use orgs_write siblings orgs_read. Destructive: delete removes the org and associated clients.

Inputs: action (required), org, name, email, +4 more.

patch_agent_promptAInspect

Performs string replacements in the start-node prompt (or proactiveMessage / customCSS). USE THIS instead of update_agent when the prompt is large and you only need to change a specific section. If get_agent returns empty instructions, this tool REFUSES a surgical patch — it will NOT replace the whole prompt with new_string. Workflow: get_agent → copy the exact span into old_string → new_string is the replacement. Only omit old_string when the field is truly empty and new_string is the FULL prompt. target=auto patches the start node instructions. Never writes vg_instructions (API rejects it). sync_mirrors defaults false.

Inputs: agentId (required), new_string (required), target, old_string, +2 more.

patch_kb_docAInspect

Performs string replacements in a knowledge-base document — same idea as Cursor StrReplace for files. USE THIS instead of update_kb_doc when the document body is large and you only need to change a specific section. Workflow: get_kb_doc → copy the span into old_string (include enough surrounding context to make it unique) → new_string is the replacement → this tool patches content (or name) and PATCHes the KB doc. Prefer an exact copy from get_kb_doc; minor whitespace/line-ending drift is tolerated as a fallback. Prefer this over rewriting the entire content field. Only use replace_all=true when you intentionally want every occurrence changed.

Inputs: docId (required), agentId (required), new_string (required), old_string (required), +2 more.

query_conversationsA
Read-onlyIdempotent
Inspect

MCP-side filter over conversations (NOT a SQL analytics API). Cursor-pages list_conversations then bulk-gets details when filters need summary/capturedVariables/userName. Bounded by maxScan (default 200). Use for audits like summaryContains or capturedVariableExists. True server-side filters (hasQuote, eventDateWithin) need a future backend endpoint.

Inputs: agentId (required), tsTo, limit, origin, +8 more.

read_docxA
Read-onlyIdempotent
Inspect

Extract text from a .docx Word document (path / url / base64). Set asMarkdown=true to preserve headings, lists, links and bold/italic. Legacy .doc is NOT supported — convert to .docx first.

Inputs: url, data, path, mimeType, +1 more.

read_imageA
Read-onlyIdempotent
Inspect

Load an image (PNG / JPEG / WebP / GIF / SVG / TIFF / BMP / HEIC) from path / url / base64 and return it as a vision-ready MCP image content block so YOU can see the pixels. REQUIRED after scraping a website: call this with url= on every high-value product/room/treatment/team photo, then write what you saw + the exact URL into the agent systemPrompt catalog. Do not skip this and dump unlabeled URLs. Auto-normalizes: rasterizes SVG, downscales anything larger than maxDimension (default 2048px), and re-encodes to PNG (or JPEG when needed for size).

Inputs: url, data, path, mimeType, +1 more.

read_pdfA
Read-onlyIdempotent
Inspect

Extract text from a PDF (path / url / base64). Page-aware: pass pages as a string range like "1-3,5,7-9" or an explicit array to read only the pages you need. Output is split per page with --- page N --- headers. Auto-truncates if the result would exceed the per-call token budget. Always inspect_file first to learn totalPages.

Inputs: url, data, path, pages, +1 more.

read_spreadsheetA
Read-onlyIdempotent
Inspect

Read an Excel (.xlsx / .xlsm / .xls) or CSV file. Two-step pattern: (1) call WITHOUT sheet to list sheet names, (2) call again with sheet to read that sheet. Optional A1-style range (e.g. "A1:D50") and format ('markdown' default, or 'csv' / 'json'). headerRow=true (default) treats row 1 as keys when format='json'.

Inputs: url, data, path, range, +5 more.

read_text_fileA
Read-onlyIdempotent
Inspect

Read a plain-text file (.txt, .md, .json, .csv, .yaml, .log, code, etc.) from path / url / base64. Returns UTF-8 text plus a truncation flag and token estimate. Honors an optional maxBytes cap. For .docx use read_docx, for .pdf use read_pdf, for .xlsx use read_spreadsheet.

Inputs: url, data, path, maxBytes, +1 more.

release_twilio_numberA
Destructive
Inspect

Release (delete) a Twilio SMS/voice number from the workspace. This does not remove WhatsApp Cloud API waNumbers. Pass the full request body for /utils/twilio/release-number as an object — typically includes phoneNumber or phoneNumberSid.

Inputs: payload (required).

run_agent_auto_testAInspect

Start Convocore automated agent test suite (POST /auto-test/run). Modes include tools-only, with-tools, kb-only, full. Returns testId/status/score. Prefer this for broader regression; use test_agent_tool for a single tool.

Inputs: agentId (required), config.

run_commandA
Destructive
Inspect

Execute a shell command on the host machine where the MCP server is running and return stdout, stderr, and the exit code. Runs through the platform default shell (cmd.exe on Windows, /bin/sh on Unix). Use for simple system tasks like checking versions, listing files, or running short scripts. NOTE: this tool has full access to the host shell with the MCP process privileges — only run commands you trust.

Inputs: command (required), cwd, timeoutSeconds.

scrape_urlA
Read-onlyIdempotent
Inspect

Validate and/or scrape HTTP(S) URLs. DEFAULT mode=check: fast ping of one or many links/images (up to 20) — returns status (200/301/404/etc), ok, content-type, final URL after redirects. Use this to verify widget images, logos, CDN assets, booking links, or any URL before putting it on an agent. mode=scrape: full Convocore crawler scrape of ONE page (waits up to ~120s) for text/colours/favicon/images when building branded agents. After scrape, CHECK image URLs then call read_image on every important photo so you know what each picture is before putting it in the agent prompt. Default useProxy=false (~1 credit). CRITICAL — proxy: ONLY if a normal (useProxy=false) scrape fails/blocks AND the user explicitly confirms. Proxy is MUCH more expensive (~60 credits/page) and CONSUMES Convocore workspace credits. Requires useProxy=true + confirmExpensiveProxy=true. Never enable proxy proactively. Do NOT use scrape for KB ingest (use create_kb_from_urls). Workspace is resolved internally — never pass workspaceId.

Inputs: url, mode, urls, useProxy, +1 more.

search_agentsA
Read-onlyIdempotent
Inspect

Search/filter Convocore agents. Default mode=compact (short fields only). Use mode=full only when you need complete agent docs. Prefer list_agents (compact) for recent agents without a query.

Inputs: mode, page, limit, search, +2 more.

search_kb_docsA
Read-onlyIdempotent
Inspect

Semantic/vector search over an agent knowledge base (POST .../kb/search). Prefer this to list_kb_docs when looking for content by meaning. For CRUD use create_kb_doc / get_kb_doc / patch_kb_doc.

Inputs: agentId (required), vector, vectorDb, max_chunks, +5 more.

search_mcp_toolsA
Read-onlyIdempotent
Inspect

Search this MCP server's tool catalog by keyword/domain before calling other tools. Use when unsure which tool to pick among orgs/clients/leads/agent_tools/variables/kb/testing. detail=names|brief|schema. Does not call the Convocore API.

Inputs: query (required), limit, detail, domain.

search_voicesA
Read-onlyIdempotent
Inspect

Unified voice search across one or more TTS providers. Every result is normalized to { voiceId, name, provider, previewUrl, filters: { accent, gender, useCase, language } }. Use this when the user asks for a voice by gender / language / accent without caring which provider. Read-only — does NOT consume credits.

Inputs: limit, accent, gender, offset, +3 more.

send_channel_messageAInspect

Push an agent-initiated message onto the conversation channel (WhatsApp, Messenger, Instagram, Telegram, SMS, Discord). Does NOT run the LLM — text is sent as-is. Subject to provider rules (e.g. Meta 24h window). Do NOT use update_conversation_messages for channel delivery (that only updates stored history).

Inputs: agentId (required), convoId (required), message, options, +2 more.

send_handoff_reminderAInspect

Re-send the human-handoff notification for a conversation that is waiting for a human (emails the team again). userId is the conversation / end-user id. Sends a real email.

Inputs: userId (required), agentId (required).

send_smsAInspect

Send a REAL SMS from the agent's connected SMS number. sendMode=direct (default) sends message as written; sendMode=agent lets the agent write the text (message is then optional). mediaUrls sends MMS. Bills the workspace. For WhatsApp / Messenger / Instagram replies use send_channel_message instead.

Inputs: to (required), agentId (required), from, mode, +7 more.

sleepA
Read-onlyIdempotent
Inspect

Pause for the given number of seconds and then return. Useful when you need to wait between actions (e.g. polling a job, rate-limiting, giving an external system time to settle). Range: 0–300 seconds.

Inputs: seconds (required).

sms_numbers_readA
Read-onlyIdempotent
Inspect

Read the SMS numbers of an agent and search numbers that can be rented. Voice phone numbers are in get_agent_phone. Actions: list — SMS numbers connected to the agent Needs: agentId. | analytics — SMS volume and delivery analytics for the agent Needs: agentId. | rental_status — whether the agent has a rented platform number and its state Needs: agentId. | rental_available — whether number rental is offered in a country | search_available — numbers available to rent, filtered by country / area code / digits

Inputs: action (required), mode, limit, agentId, +4 more.

sms_numbers_writeA
Destructive
Inspect

Manage the SMS numbers of an agent. Connecting your own Twilio account and paying for a rented number are done on the dashboard (they need credentials / card details that must not go through chat). test_send sends a real SMS. Actions: remove — disconnect an SMS number from the agent Needs: phoneNumber. | assign_rental — attach an already-rented platform number to the agent Needs: phoneNumber. | release_rental — give up the rented number of the agent (it stops working; confirm first) | test_send — send a test SMS from the agent number Needs: testPhoneNumber.

Inputs: action (required), agentId (required), mode, message, +2 more.

start_outbound_callAInspect

Place a REAL outbound phone call now: the agent calls the "to" number from its assigned number and talks to whoever answers. Bills voice minutes. Confirm the number with the user first. For many leads at once use contact_leads or a campaign (campaigns_write).

Inputs: to (required), agentId (required), from, mode, +3 more.

sync_sms_twilio_numberAInspect

Assign a Twilio number to an agent for SMS handling. This is SMS only; WhatsApp routing uses waNumbers/{phoneId}, origin "whatsapp", and Meta Cloud API. Pass the full request body for /utils/twilio/sync-sms as an object — typically includes phoneNumber (or sid) and agentId.

Inputs: payload (required).

test_agent_toolAInspect

Test a Convocore agent HTTP tool via interact WebSocket toolTest mode (validate | generate-and-test). Runs through the agent runtime. For a direct HTTP dry-run against serverUrl use test_agent_tool_request. For multi-turn suites use run_agent_auto_test.

Inputs: toolId (required), agentId (required), toolName (required), mode, +3 more.

test_agent_tool_requestA
Destructive
Inspect

Fire a real HTTP request for a saved tool, bypassing the LLM. Tools with a custom HTTP request (httpRequest.enabled) are replayed exactly as the live runtime sends them: saved bodyTemplate, fixed values, headers, query and environment variables, with fieldOverrides used as the AI-input values (keyed by variable key). Environment variable values and auth headers are masked in the returned request preview. Legacy serverUrl tools are assembled from fields[]. Side effects on the remote API are possible — use carefully.

Inputs: toolId (required), timeoutMs, bodyOverride, fieldOverrides.

tool_sharingA
Destructive
Inspect

Copy a tool to other agents or share one tool across the workspace. A COPY is independent afterwards; a SHARED tool stays one tool used by many agents, so editing it changes all of them. Actions: copy — copy a tool to one agent Needs: toolId, targetAgentId. | copy_to_agents — copy a tool (and its variables) to many agents Needs: toolId, targetAgentIds, tool. | set_access — choose who can use the tool: private, whole workspace, chosen agents or client orgs Needs: toolId, agentId, tool, access. | publish_workspace — publish the tool to every agent of the workspace Needs: toolId, agentId, tool. | make_private — stop sharing: the tool belongs to one agent again Needs: toolId, agentId. | share — share an existing tool with the workspace or an org Needs: toolId, scope. | update_shared — edit a shared tool (affects every agent using it) Needs: toolId, tool. | unassign_shared — remove a shared tool from one agent Needs: toolId, agentId. | delete_shared — delete a shared tool for everyone (confirm first) Needs: toolId.

Inputs: action (required), mode, tool, orgId, +10 more.

update_agentAInspect

Update an existing Convocore agent (PATCH). For large prompt edits prefer patch_agent_prompt. Main prompt: use systemPrompt → start node instructions. NEVER send vg_instructions or vg_systemPrompt. Do NOT pass nodes[] unless you are changing nodes — omit it for title/UI/funnel/model updates. Partial nodes[] are GET-merged by id; a toolsIds-only start node cannot blank instructions, and toolsIds in a patch are only ever ADDED (tools attached on the dashboard are kept). To detach tools pass allowRemoveTools=true. Lead notify: funnelConfig (steps + notificationRules.recipients). UI Engine: vg_enableUIEngine* + vg_uiEngineChannelConfig. ownerID is read-only.

Inputs: agentId (required), light, nodes, theme, +19 more.

update_agent_custom_cssA
Destructive
Inspect

Overwrite the agent's customCSS field with new CSS that styles the chat widget. IMPORTANT: this REPLACES the existing customCSS value — always pass the FULL merged CSS (existing + your new rules), not just the delta. Workflow: (1) call get_widget_css_styling_guide to load selectors + rules, (2) optionally call get_agent_custom_css to read what's already there, (3) generate the merged CSS following the guide, (4) call this tool to persist. Pass an empty string to clear all customCSS for the agent.

Inputs: agentId (required), customCSS (required).

update_agent_toolB
Idempotent
Inspect

Patch an existing Convocore agent HTTP tool by toolId. Pass only fields to change inside tool{}.

Inputs: tool (required), toolId (required).

update_agent_variableA
Idempotent
Inspect

Patch an existing Convocore agent variable by variableId. Pass only fields to change. Never send back a masked env value as defaultValue — omit it to keep the stored value.

Inputs: variable (required), variableId (required).

update_conversationAInspect

Patch fields on the light conversation document. This does NOT replace the stored turn/message history. To replace transcript turns, use update_conversation_messages.

Inputs: agentId (required), convoId (required), conversation (required).

update_conversation_messagesA
Destructive
Inspect

Replace the stored message turn history for a conversation using PATCH /agents/{agentId}/convos/{convoId}/messages. This overwrites voiceglow/{agentId}/convos/{convoId}/convo/JSON_STRING with the provided turns array. Set updateConversationMetadata=true (default) to also refresh messagesNum, lastMessage, firstMessageTS, lastMessageTS, and lastModified on the light conversation doc. Because this is a full replacement, confirmReplace must be true.

Inputs: turns (required), agentId (required), convoId (required), confirmReplace (required), +2 more.

update_conversation_noteA
Idempotent
Inspect

Replace the text of one existing note. The previous text is kept in the workspace Logs with who edited it, from which IP and when.

Inputs: text (required), noteId (required), agentId (required), convoId (required), +1 more.

update_kb_docAInspect

Update a knowledge base document (VG agents only). For large document bodies prefer patch_kb_doc (Cursor-style exact old_string→new_string) instead of rewriting the entire content field.

Inputs: docId (required), agentId (required), url, name, +4 more.

update_whatsapp_ai_rulesA
Idempotent
Inspect

Change the WhatsApp "AI rules" of a Convocore agent — when the AI should or should not reply to inbound WhatsApp messages. Partial update: send only the fields to change; lists (triggerPhrases, participantList, availability.days) are replaced as a whole, so read them first with get_whatsapp_ai_rules to add or remove one entry. Decision order for each inbound message: availability schedule → participant list → thread ownership → trigger phrases → aiRule. Does NOT change what the agent says (use update_agent / patch_agent_prompt) and does NOT pause a number (use update_whatsapp_number_settings aiPaused). The response carries warnings when the saved combination would keep the AI silent — relay them to the user.

Inputs: rules (required), agentId (required).

update_whatsapp_number_settingsA
Idempotent
Inspect

Change the AI behaviour of ONE WhatsApp number assigned to a Convocore agent (get phoneId from get_whatsapp_ai_rules). Partial update: send only the fields to change. Use aiPaused to stop/resume all AI replies on the number, and coexistenceSettings for numbers shared with the WhatsApp Business app. Does not connect, reassign or remove numbers, and never touches Meta credentials. For reply conditions (phrases, AI rule, schedule, allow/deny list) use update_whatsapp_ai_rules.

Inputs: agentId (required), phoneId (required), settings (required).

usage_readA
Read-onlyIdempotent
Inspect

Read usage, credits and activity — everything the dashboard Usage and Analytics pages show — for the whole workspace and per agent. Read only. Time range: days back from now (default 30, max 400) or an explicit from / to (ISO date like 2026-10-01, or a full ISO datetime). overview: ONE call with credit balance, plan quota and limits, credits consumed in the range, tokens per model, the top agents (with names) and total activity (conversations, messages, calls, call minutes) — start here for "how is my usage". top_agents: agents ranked by credits consumed, with share of the total (topN up to 15). credits: current credit balance. quota: plan limits and current usage (conversations, messages, agents, KB…). workspace_usage: the Usage page — creditsCharged and creditsConsumed, input/output tokens per model, credits per agent with per-agent models, plus the chart list; add includeCharts for the chart data and includeLogs or logsPage for the credit usage log (what charged how much, and why). agent_usage (agentId): credits and tokens per model for one agent, plus call minutes. agent_analytics (agentId): that agent's analytics — loads, conversations, metrics, token usage, containment and human-handover stats. agents_analytics: activity totals for all agents (or agentIds), and per agent with includePerAgent (default true). clients_analytics: agency only — usage, leads and funnel per whitelabel client and per agent (clientIds to narrow). email_analytics (agentId): email channel analytics for one agent. WhatsApp and SMS analytics are in whatsapp_numbers_read / sms_numbers_read, voice calls in call_logs_read, knowledge-base quota in get_kb_quota.

Inputs: action (required), to, days, from, +9 more.

whatsapp_campaigns_readA
Read-onlyIdempotent
Inspect

List WhatsApp broadcast campaigns of an agent (template messages sent to a lead group) with sent / delivered / failed counts. Outbound CALL campaigns are in campaigns_read. Actions: list — paginated campaigns

Inputs: action (required), agentId (required), mode, page, +1 more.

whatsapp_campaigns_writeA
Destructive
Inspect

Create, edit, delete or send a WhatsApp broadcast campaign: an APPROVED template sent to every lead in a lead group. run sends real WhatsApp messages that Meta bills — always run with dryRun=true first and confirm the audience with the user. Campaign fields: name, leadGroupName (or "all"), phoneId (sending number), templateId, templateName, templateLanguage, templateCategory, variableMapping / headerVariableMapping (how lead fields fill {{1}}, {{2}}…), delayBetweenMessages (seconds, default 2), openTime / closeTime ("HH:mm"), timezone. Actions: create — create a campaign (stopped until run) Needs: campaign. | update — change fields of a campaign Needs: campaignId, campaign. | delete — delete a campaign Needs: campaignId. | run — send the campaign now (dryRun=true to preview) Needs: campaignId.

Inputs: action (required), agentId (required), mode, dryRun, +2 more.

whatsapp_numbers_readA
Read-onlyIdempotent
Inspect

Read details of the WhatsApp numbers connected to an agent. For a quick "is it connected" check use get_agent_channels; for reply rules use get_whatsapp_ai_rules. Actions: list — all numbers of the agent with status, mode and settings | details — live info from Meta: display name, quality rating, messaging limit tier, verification Needs: phoneId. | analytics — WhatsApp conversation and message analytics for the agent | voice_status — re-check with Meta whether WhatsApp voice calling is enabled on the number Needs: phoneId.

Inputs: action (required), agentId (required), mode, phoneId.

whatsapp_numbers_writeA
Destructive
Inspect

Manage a connected WhatsApp number. To CONNECT a new number use create_channel_connect_link (the user must log in with Meta). Confirm with the user before remove. Actions: remove — disconnect the number from the agent (the AI stops answering it) | reassign — move the number to another agent of the workspace Needs: newAgentId. | update_display_name — request a new display name on the WhatsApp business profile Needs: displayName. | set_voice_calling — turn inbound WhatsApp voice calling on or off for the number Needs: enabled.

Inputs: action (required), agentId (required), phoneId (required), mode, +3 more.

whatsapp_templates_readA
Read-onlyIdempotent
Inspect

List the WhatsApp message templates of a number (name, language, category, approval status, components). Templates are required to message a customer outside the 24-hour window and for broadcast campaigns. Actions: list — all templates of the WhatsApp Business account

Inputs: action (required), agentId (required), phoneId (required), mode.

whatsapp_templates_writeA
Destructive
Inspect

Create, edit or delete WhatsApp message templates. New and edited templates go to Meta for review before they can be used. Placeholders are {{1}}, {{2}}… in order. Actions: create — submit a new template; give bodyText or components Needs: name, category, language. | update — replace the components (and optionally category) of an existing template Needs: templateId, components. | delete — delete a template by name (all languages unless templateId is given) Needs: name.

Inputs: action (required), agentId (required), phoneId (required), mode, +6 more.

workspace_readA
Read-onlyIdempotent
Inspect

Read workspace-level data: activity and channel webhook logs (to debug "the bot did not reply"), credit balance and plan quota. Actions: logs — recent logs, filterable | log — one log entry in full Needs: logId. | log_timeline — every step of one inbound message, from webhook to reply Needs: traceId. | credits — credit balance | quota — plan limits and current usage

Inputs: action (required), kind, mode, page, +7 more.

workspace_writeA
Destructive
Inspect

Change workspace settings: name, photo and team members; form-submission notification emails on/off; the workspace's own AI provider keys. Actions: update_team_profile — change workspace name / photo / team (read the current team on the dashboard first: the list replaces the old one) | set_form_submit_emails — turn the workspace-wide "New form submitted" / rating notification emails on or off (default on); per-agent override is vg_uiEngineFormNotifyConfig.enabled Needs: formSubmitEmailsEnabled. | set_provider_keys — store the workspace own AI provider API keys. Keys typed in chat pass through this conversation: prefer the dashboard, and never repeat a key back Needs: keys.

Inputs: action (required), keys, mode, usersPerms, +4 more.

zoho_crm_records_readA
Read-onlyIdempotent
Inspect

Browse and search records in the connected Zoho CRM: leads, contacts, deals, accounts or any custom module. list pages through a module (perPage up to 200; pass info.nextPageToken as pageToken past 2000 records). search uses Zoho criteria, e.g. "(Lead_Status:equals:New)" or "((Lead_Source:equals:Chat)and(Created_Time:greater_than:2026-10-01T00:00:00+00:00))"; operators: equals, not_equal, starts_with, in, greater_than, less_than, between. query runs COQL for anything else, e.g. "select Last_Name, Email, Lead_Status from Leads where Lead_Status = 'New' order by Created_Time desc limit 200" (a where clause is required; limit max 2000, use "limit 200, 200" to page). Use integrations_read zoho_fields for the field API names and picklist values. Actions: list — one page of records of a module, newest first if sortBy=Created_Time sortOrder=desc Needs: moduleApiName. | search — records matching criteria / word / email / phone Needs: moduleApiName. | query — COQL SELECT for filters, sorting and counts search cannot do Needs: query. | get — one full record Needs: moduleApiName, recordId.

Inputs: action (required), cvid, mode, page, +14 more.

zoho_crm_records_writeA
Destructive
Inspect

Create, update, upsert or delete records in the connected Zoho CRM (leads, contacts, deals, accounts, custom modules), up to 100 per call, and add notes. Records use Zoho field API names, e.g. { "Last_Name": "Smith", "Email": "a@b.com", "Lead_Status": "New" }; picklist values must match exactly (integrations_read zoho_fields). The result has one entry per record (success, id, or the Zoho error code and field), so partial failures are visible. delete moves records to the Zoho recycle bin; confirm with the user before deleting or bulk-updating. Actions: create — create records Needs: records. | update — update records by id (only the fields given change) Needs: records. | upsert — insert or update by duplicateCheckFields; each result says insert or update Needs: records. | delete — delete records (confirm first) Needs: recordIds. | add_note — attach a note to a record Needs: recordId, title, content.

Inputs: action (required), moduleApiName (required), mode, orgId, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 145 tools

    Disambiguation3/5

    The descriptions are unusually explicit and often cross-reference the correct alternative, which helps distinguish many tools. However, the set contains several overlapping families: five ways to create an agent, many conversation retrieval/query/export tools, multiple KB ingestion tools, and duplicated usage/credit reporting paths. These overlaps make misselection likely at 145 tools even though the boundaries are documented.

    Naming Consistency3/5

    Most names are readable snake_case, but the server mixes several conventions: verb_noun CRUD (list_agents, create_kb_doc, delete_conversation) with resource_read/resource_write action buckets (orgs_read, leads_write, campaigns_read) and noun-only tools like code_tools and tool_sharing. The patterns are systematic by domain, but they are not uniform across the whole tool set.

    Tool Count1/5

    At 145 tools, the surface is far beyond a well-scoped 3-15 tool range and well into the extreme 50+ category. While Convocore is a broad platform, the sheer number of tools creates a heavy selection and maintenance burden.

    Completeness4/5

    The server covers lifecycle operations across agents, conversations, knowledge base, channels, integrations, CRM, campaigns, usage, and workspace settings. There are minor gaps, such as voice phone-number assignment largely being dashboard-only and domain verification being dashboard-only, but most core workflows have create/read/update/delete coverage.

    Related MCP Connectors

    Related MCP Servers