Convocore MCP Server
Provides tools for managing Airtable connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's Airtable integration tools.
Provides tools for managing Calendly connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's Calendly integration tools.
Provides tools for managing Gmail connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's Gmail integration tools.
Provides tools for managing Google Calendar connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's calendar integration tools.
Provides tools for managing Google Drive connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's Drive integration tools.
Provides tools for managing Google Sheets connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's Sheets integration tools.
Provides tools for connecting Instagram through a no-login channel link and managing the resulting channel connection.
Provides tools for connecting Messenger through a no-login channel link and managing the resulting channel connection.
Provides tools to read Meta pages and disconnect Meta pages used for channel connections.
Provides tools for managing Shopify connections on agents, including assigning, updating, removing, diagnosing setup, and running the agent's Shopify integration tools.
Provides Twilio utilities for voice and SMS operations, alongside tools for agent phone lookup, outbound calls, SMS sending, and contacting leads.
Provides tools for connecting WhatsApp via a no-login link, managing WhatsApp numbers, templates, campaigns, and configuring AI reply rules and number settings.
Provides Zoho CRM record tools for listing, searching, COQL, getting, creating, updating, upserting, deleting, and notes, plus management of Zoho CRM and Zoho Mail connections on agents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Convocore MCP Server List my recent conversations and summarize the latest one."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 |
Convocore API | Backend at |
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 |
|
Leads CRM | 2 |
|
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 |
|
WhatsApp AI rules | 3 |
|
Campaigns | 2 |
|
Call logs | 2 |
|
Outbound calls & SMS | 4 |
|
Custom metrics | 2 |
|
Lead groups | 2 |
|
Folders | 2 |
|
Agent extras | 5 |
|
WhatsApp management | 6 |
|
Meta pages, SMS, email | 5 |
|
Integrations | 3 |
|
Zoho CRM records | 2 |
|
Contacts | 2 |
|
Agent backups | 2 |
|
Code tools & sharing | 2 |
|
Workspace | 3 |
|
Testing | 3 |
|
Discovery | 1 |
|
Scrape / embed / voice | many | scrape, embed code, voices, Twilio utils |
Interact (WS) | 1 | Drive one agent turn; supports |
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)
The host (Claude Desktop, Cursor, etc.) starts the server as a subprocess: e.g.
npx -y convocore-mcp,docker run …, ornode dist/index.js.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).On startup,
getConfig()reads env vars. IfWORKSPACE_SECRETis missing, the process throws and exits.The host sends
tools/listandtools/call. Each call is validated, thenConvocoreClientperformsfetch()to the REST API.
flowchart LR
Host[MCP host]
MCP[convocore-mcp stdio]
API[Convocore REST API v3]
Host <--> MCP
MCP --> APIRepository layout
Path | Purpose |
| MCP server, tool definitions (JSON Schema for hosts), Zod validation, tool dispatch |
| HTTP client: paths, methods, query strings, JSON bodies |
|
|
|
|
| Shared TypeScript types for config and agent payloads |
| Compiled output ( |
| Multi-stage image: build with pnpm, run |
| Example service (see Docker Compose note) |
| Sample Claude Desktop MCP entry |
| OpenAPI spec (reference for API shape) |
Environment variables
Variable | Required | Default | Meaning |
| Yes | — | Bearer token for the Convocore workspace (same as API key/secret from your dashboard). |
| No |
|
|
| No | — | Optional full REST base URL override. Useful for local dev, e.g. |
| No | — | Optional explicit override for only the |
| No | — | Workspace/org UUID ( |
| No | on | Set to |
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
| Base URL |
|
|
|
|
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 (
mcpAccesson the client). The client clicks Connect AI in their dashboard; the API mints agl_…connection token stored as a hash on the agency workspace (users/{workspaceId}/mcpClientConnections).The agency host accepts
gl_tokens only, andgl_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.
Option A: npx (recommended)
You don't have to install anything. Your MCP host (Claude Desktop, Cursor, etc.) runs the server on demand:
npx -y convocore-mcpSet 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.jsConnecting 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-mcpClaude Desktop
Config path:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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
npxdirectly, wrap it withcmd:{ "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 |
| Display name used in Claude |
| Add to Cursor — true one-click ( |
|
|
| Add to Claude — opens the official prefilled custom-connector modal |
|
|
| Optional local |
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 OAuthresource, 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=0disables 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 |
| POST |
|
| POST workflow | Preferred: explicit |
| GET |
|
| PATCH |
|
| GET+PATCH |
|
| DELETE |
|
| GET |
|
| GET |
|
| GET |
|
| POST |
|
| POST |
|
| GET |
|
| GET×N | Fan-out |
| MCP | Cursor list + bulk filter (not server SQL; |
| POST×N | Fan-out |
| GET×N | Fan-out |
| POST |
|
| GET |
|
| PATCH |
|
| GET |
|
| POST |
|
| PATCH |
|
| DELETE |
|
| DELETE |
|
| GET |
|
| GET |
|
| POST |
|
| POST×N or 1 | Fan-out / batch |
| POST |
|
| GET |
|
| GET |
|
| PATCH |
|
| GET+PATCH |
|
| DELETE |
|
| GET |
|
| HTTP ping or crawler |
|
| WSS |
|
| 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_urlfirst → pick colour + favicon URL →search_voicesongoogle-live/ultravoxfor accents → then this tool with explicit prompts and fullvoiceConfig.MCP builds
customThemeJSONString(nineColorPallet) fromprimaryColor(same lightness ramp as ConvocorehandleAutoGenPallet).After create, MCP calls
get_agentand returnsdata.agentas the full document (plusagentId).Prefer env
CONVOCORE_WORKSPACE_IDso MCP does not need to infer workspace fromlist_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_templateunless you intentionally need low-level manual field control.nodes: Convocore’s multi-step graph;nodes[0].instructionsis the main system prompt.additionalConfig: Plain object merged into theagentpayload (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: usecontentfor text.url: useurls(array), optionalscrapeContent.sitemap: usesitemapUrl, optionalmaxPages.
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-euor(default). Auto-derived fromCONVOCORE_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 underlyingEWSInteractModel.timeoutMs(default120000, max600000) — how long the MCP waits for the streamed turn before forcing the WebSocket closed.raw(defaultfalse) — 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 (overridessection).
Use this BEFORE:
Validating output from
interact_with_agentagainst a UI-Engine-enabled agent.Creating / updating an agent whose system prompt should teach the model to emit UI Engine messages — bake the relevant rules and
messageTypeshapes intonodes[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 (instructionsfield) that define default agent behavior.lightmode (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_docwithsourceType: url|sitemap+scrapeContent: true“Are these image/page links dead?” →
scrape_urlwithmode: "check"+urls: [...]“Scrape one URL for branding (colours/favicon)” →
scrape_urlwithmode: "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:latestCommon 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 |
| Install dependencies |
| Run |
|
|
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 publicprepublishOnly 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:latestTelemetry
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.
Links
Built for the Convocore community.
Available Tools
145 toolsadd_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_brandingADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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.
agent_gallery_templatesAInspect
The ready-made agent templates shown in the dashboard gallery. Actions: list (available templates with their templateId), create (templateId, optional title / description: creates a new agent from that template as-is). To build a custom agent for a specific business use create_agent_from_template instead.
Inputs: action (required), mode, title, templateId, +1 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_docsADestructiveIdempotentInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_toolsADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_channel_connect_linkAInspect
Create a private link the USER opens to connect WhatsApp, Messenger or Instagram to an agent. Connecting needs the user to log in with Meta in their own browser, so you cannot do it for them: create the link, show the returned url to the user as a clickable link, and tell them to come back and say when they are done. The page needs no Convocore login and expires (default 30 minutes). When the user says they finished, call get_agent_channels to confirm the channel is really connected before saying it works. messenger and instagram use the same page: the user picks a Facebook page; Instagram is connected when an Instagram account is linked to that page. whatsappConnectionMode: metaCloudApi (default, a number used only by the AI) or metaCoexistence (a number already used in the WhatsApp Business app, shared with the AI).
Inputs: agentId (required), channel (required), ttlMinutes, whatsappConnectionMode.
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_agentBDestructiveInspect
Delete a Convocore agent permanently
Inputs: agentId (required).
delete_agent_toolADestructiveIdempotentInspect
Permanently delete a Convocore agent HTTP tool by toolId. Does not delete MCP tools.
Inputs: toolId (required).
delete_agent_variableBDestructiveIdempotentInspect
Permanently delete a Convocore agent variable by variableId.
Inputs: variableId (required).
delete_conversationCDestructiveInspect
Delete a conversation
Inputs: agentId (required), convoId (required).
delete_conversation_noteADestructiveIdempotentInspect
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_docBDestructiveInspect
Delete a knowledge base document (VG agents only)
Inputs: docId (required), agentId (required).
disconnect_meta_pageADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_agentBRead-onlyIdempotentInspect
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_conversationsARead-onlyIdempotentInspect
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_conversationARead-onlyIdempotentInspect
Export a single conversation. Requires a paid workspace (hasEverPaid === true); billed against monthly export quota.
Inputs: agentId (required), convoId (required), format.
folders_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_summariesARead-onlyInspect
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_funnelARead-onlyIdempotentInspect
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_agentARead-onlyIdempotentInspect
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_logARead-onlyIdempotentInspect
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_channelsARead-onlyIdempotentInspect
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_cssARead-onlyIdempotentInspect
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_phoneARead-onlyIdempotentInspect
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_toolARead-onlyIdempotentInspect
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_usageBRead-onlyIdempotentInspect
Get agent usage statistics and credits consumed
Inputs: agentId (required), range.
get_agent_usage_bulkBRead-onlyIdempotentInspect
Fetch usage/credits for many agents in one call (fan-out). Max 20 agentIds. Optional shared date range.
Inputs: agentIds (required), range.
get_agent_variableARead-onlyIdempotentInspect
Get one Convocore agent variable by variableId. The value of an environment variable (isEnv) is masked.
Inputs: variableId (required).
get_channel_integration_specARead-onlyIdempotentInspect
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_connect_link_statusARead-onlyIdempotentInspect
Check a connect link created with create_channel_connect_link: pending (not opened), opened / redeemed (the user is on the page), connected, error or expired. To verify the channel itself use get_agent_channels.
Inputs: sessionId (required).
get_conversationCRead-onlyIdempotentInspect
Get details of a single conversation
Inputs: agentId (required), convoId (required).
get_conversations_bulkARead-onlyIdempotentInspect
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_docCRead-onlyIdempotentInspect
Get a single knowledge base document
Inputs: docId (required), agentId (required).
get_kb_docs_bulkARead-onlyIdempotentInspect
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_quotaARead-onlyIdempotentInspect
Get workspace KB document quota usage (GET /workspace/kb-docs/quota). Optional workspaceId; defaults to the authenticated workspace.
Inputs: workspaceId.
get_kb_statsBRead-onlyIdempotentInspect
Get knowledge base statistics for an agent (VG agents only)
Inputs: agentId (required).
get_pricing_infoARead-onlyIdempotentInspect
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_specARead-onlyIdempotentInspect
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_voiceARead-onlyIdempotentInspect
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_codeARead-onlyIdempotentInspect
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_rulesARead-onlyIdempotentInspect
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_guideARead-onlyIdempotentInspect
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_fileARead-onlyIdempotentInspect
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_readARead-onlyIdempotentInspect
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_testADestructiveInspect
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_writeADestructiveInspect
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
convoIdacross 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.bucketis auto-derived from CONVOCORE_API_REGION; only override if you really mean to talk to the other region.Set
raw: trueto 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: truefor test chats. PasstoolTest: { toolId, toolName, mode: validate|generate-and-test }to exercise one HTTP tool (or use dedicatedtest_agent_tool). PassvariablesOverrides/initNodesOptionsto 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 userun_agent_auto_test.
INTERPRETING THE RESPONSE:
When
uiEngineEnabled: false, the agent streamed plain Markdown — readassistantText.When
uiEngineEnabled: true, the agent streamed UI Engine snapshots — readuiEngineSnapshot(parsed final TurnProps) anduiEngineSummary(compact per-message summary).assistantTextmay 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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeBDestructiveInspect
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_agentsARead-onlyIdempotentInspect
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_toolsARead-onlyIdempotentInspect
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_variablesARead-onlyIdempotentInspect
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_notesARead-onlyIdempotentInspect
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_conversationsARead-onlyIdempotentInspect
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_docsARead-onlyIdempotentInspect
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_voicesARead-onlyIdempotentInspect
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_modelsARead-onlyIdempotentInspect
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_providersARead-onlyIdempotentInspect
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_readARead-onlyIdempotentInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_conversationsARead-onlyIdempotentInspect
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_docxARead-onlyIdempotentInspect
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_imageARead-onlyIdempotentInspect
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_pdfARead-onlyIdempotentInspect
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_spreadsheetARead-onlyIdempotentInspect
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_fileARead-onlyIdempotentInspect
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_numberADestructiveInspect
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_commandADestructiveInspect
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_urlARead-onlyIdempotentInspect
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_agentsARead-onlyIdempotentInspect
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_docsARead-onlyIdempotentInspect
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_toolsARead-onlyIdempotentInspect
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_voicesARead-onlyIdempotentInspect
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.
sleepARead-onlyIdempotentInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_requestADestructiveInspect
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_sharingADestructiveInspect
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_cssADestructiveInspect
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_toolBIdempotentInspect
Patch an existing Convocore agent HTTP tool by toolId. Pass only fields to change inside tool{}.
Inputs: tool (required), toolId (required).
update_agent_variableAIdempotentInspect
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_messagesADestructiveInspect
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_noteAIdempotentInspect
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_rulesAIdempotentInspect
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_settingsAIdempotentInspect
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_readARead-onlyIdempotentInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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_readARead-onlyIdempotentInspect
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_writeADestructiveInspect
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
Scored across 145 tools
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.
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.
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.
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
Connect AI clients to your Dactic work context through a hosted MCP service.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Host any HTTP API as MCP tools with a tamper-evident cross-agent settlement ledger.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a standardized MCP interface for interacting with HTTP tools and services, enabling unified API access and management.MIT
- AlicenseBqualityDmaintenanceConnects any MCP-compatible AI client to Letta.ai's stateful agents for agent conversations, memory management, and tool orchestration.1829 PyPI12MIT
- FlicenseNot gradedqualityDmaintenanceEnables LLM-powered agents to securely communicate with and orchestrate downstream microservices via FastAPI endpoints exposed as MCP tools.-
- AlicenseAqualityBmaintenanceEnables connecting over 1,000 apps once, self-hosted and with encrypted credentials, so that Claude, Codex, Cursor, Copilot and dozens of other AI agents can call their APIs as MCP tools. Agents authenticate with per-agent tokens to get ready-made tools for every connected app, including app-specific actions like searching mail or sending messages.1118 npm5MIT