Convocore

Convocore MCP Server

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

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

What this project is

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

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.

Light mode

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

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

How it runs (transport and lifecycle)

1. The host (Claude Desktop, Cursor, etc.) starts the server as a subprocess: e.g. npx -y convocore-mcp, docker run …, or node dist/index.js.
2. Communication uses StdioServerTransport: JSON-RPC messages on stdin/stdout. Do not write logs to stdout; the server logs to stderr (e.g. Convocore MCP Server running on stdio).
3. On startup, getConfig() reads env vars. If WORKSPACE_SECRET is missing, the process throws and exits.
4. The host sends tools/list and tools/call. Each call is validated, then ConvocoreClient performs fetch() to the REST API.

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

Repository layout

Environment variables

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

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

Authentication

Every request from ConvocoreClient includes:

• Authorization: Bearer <WORKSPACE_SECRET>
• Content-Type: application/json

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

Gray-label client connections

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

• The agency turns on AI assistant access for the client (mcpAccess on the client). The client clicks Connect AI in their dashboard; the API mints a gl_… connection token stored as a hash on the agency workspace (users/{workspaceId}/mcpClientConnections).
• The agency host accepts gl_ tokens only, and gl_ tokens work only there. The API scopes every call to the client's agents (client.widgetIDs ∪ org.widgetIDs, read live) and refuses workspace-level routes; this server also narrows the tool list and checks agent ids.
• Server name, instructions, tool text, results, errors and the OAuth Connect page carry the agency brand ({Agency} - {Client}), never the platform's. Scope and brand refresh every minute on open sessions; revoking a connection or turning access off stops it.

Quick start

Prerequisites

• A Convocore workspace secret (WORKSPACE_SECRET).
• Optional: correct region (eu-gcp / na-gcp).
• Node.js 20+ (ships with npx). Docker is optional and only needed for the container workflow.

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-mcp

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

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

Option B: Docker

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

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

Option C: Local Node (development)

git clone https://github.com/moe003/convocore-mcp.gitcd convocore-mcppnpm installpnpm run buildexport WORKSPACE_SECRET="your_workspace_secret_here"export CONVOCORE_API_REGION="eu-gcp"node dist/index.js

Connecting MCP hosts

Gemini CLI

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

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

Claude Desktop

Config path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

npx (recommended):

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

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

json

{  "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:

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

• Cursor deeplinks embed headers in base64 — secret travels with the install.
• Claude’s install URL only prefills name + connector URL. No header query params exist.
• Claude then runs OAuth Dynamic Client Registration against the MCP host. Without /oauth/register + authorize/token, you get “Couldn't register with Convocore’s sign-in service”.
• Hosted MCP implements that OAuth AS. Claude often strips ?token= from OAuth resource, so the secret is in the path (/t/…/mcp). Authorize shows a one-click Connect page (auto-submits) — no paste. Access tokens are the workspace secret, expires_in ≈ 10 years, plus refresh.
• MCP transport sessions idle-evict after ~1 year by default (CONVOCORE_HOSTED_SESSION_IDLE_MS=0 disables eviction). Reconnect recreates a session with the same secret.

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

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

HTTP API mapping (what each tool calls)

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

Tool reference (parameters and notes)

Agent tools

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

• Workflow for the AI: scrape_url first → pick colour + favicon URL → search_voices on google-live / ultravox for accents → then this tool with explicit prompts and full voiceConfig.
• MCP builds customThemeJSONString (nineColorPallet) from primaryColor (same lightness ramp as Convocore handleAutoGenPallet).
• After create, MCP calls get_agent and returns data.agent as the full document (plus agentId).
• Prefer env CONVOCORE_WORKSPACE_ID so MCP does not need to infer workspace from list_agents.

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

• Prefer create_agent_from_template unless you intentionally need low-level manual field control.
• nodes: Convocore’s multi-step graph; nodes[0].instructions is the main system prompt.
• additionalConfig: Plain object merged into the agent payload (same level as other fields). Use for fields not listed explicitly.

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

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

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

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

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

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

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

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

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

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

Conversation tools

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

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

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

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

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

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

get_conversation — Required: agentId, convoId.

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

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

delete_conversation — Required: agentId, convoId.

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

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

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

Knowledge base tools

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

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

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

• doc: use content for text.
• url: use urls (array), optional scrapeContent.
• sitemap: use sitemapUrl, optional maxPages.

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

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

get_kb_doc — Required: agentId, docId.

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

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

delete_kb_doc — Required: agentId, docId.

get_kb_stats — Required: agentId.

Scrape tool

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

• mode: "check" (default): fast HTTP ping — status (200/404/…), ok, content-type, final URL after redirects. Use to verify images, logos, and page links before wiring them into an agent.
• mode: "scrape": full Convocore crawler scrape of one URL (waits up to ~120s) for text/colours/favicon. Workspace resolved internally. Not for KB ingest (create_kb_from_urls).

Interact (WebSocket) tool

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

Required: agentId, convoId.

Common optional:

• prompt — User message. Special values: "start" (initial greeting), "@cancel:<reason>", "@rewind:<nodeId>" (v2/node agents).
• bucket — voiceglow-eu or (default). Auto-derived from CONVOCORE_API_REGION (eu-gcp → voiceglow-eu, na-gcp → (default)); only override to deliberately cross regions.
• messageType + visualPayload — for image turns.
• replyTo — reply context for a previous message.
• lightConvoData — userName, userEmail, userPhone, origin, capturedVariables, etc. Surfaced into the agent's system prompt where supported.
• agentData / workspaceData / turnsHistory — overrides that skip Firestore loads.
• disableUiEngine, disableRecordHistory, v2, isTest, isLLMStudio, kbPreview, agentProfileId, toolTest, formSubmissionMetadata, initNodesOptions — same flags as the underlying EWSInteractModel.
• timeoutMs (default 120000, max 600000) — how long the MCP waits for the streamed turn before forcing the WebSocket closed.
• raw (default false) — when true, the response includes every raw streamed chunk; when false, only the aggregated text + actions + metadata + final turns are returned (cheaper on tokens).

Response shape (default raw: false):

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

UI Engine handling

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

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

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

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

UI Engine spec tool

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

• Required: none.
• Optional: section — "all" (default) | "meta" | "envelopes" | "message_types" | "shared" | "rules" | "checklist" | "primer".
• Optional: messageType — "text" | "choice" | "visual" | "cardV2" | "carousel" | "iFrame" | "form" | "input". When set, returns just that message-type schema (overrides section).

Use this BEFORE:

1. Validating output from interact_with_agent against a UI-Engine-enabled agent.
2. Creating / updating an agent whose system prompt should teach the model to emit UI Engine messages — bake the relevant rules and messageType shapes into nodes[0].instructions.

Convocore concepts: nodes and prompts

• Each node can represent a step in a workflow.
• The first node (nodes[0]) holds the primary instructions (instructions field) that define default agent behavior.
• light mode (agent flag): described in-tool as no chat history retention for privacy.

Errors and validation

• Invalid tool arguments: Zod validation fails → error with Invalid arguments: ….
• Unknown tool name: thrown as Unknown tool: ….
• API errors: thrown with the message from the JSON body when available.
• Startup: missing WORKSPACE_SECRET → configuration error before the server connects.

Natural language examples (for end users)

After configuration, users can ask their assistant things like:

• “List all my Convocore agents” → list_agents
• “Create an agent for this website from scratch” → create_agent_from_template (preferred default)
• “Export all conversations for agent … as CSV” → export_all_conversations
• “Add many hotel/site pages to the KB” → create_kb_from_urls (KB router scrapes; do not web-fetch first)
• “Add one URL / sitemap to the KB” → create_kb_doc with sourceType: url|sitemap + scrapeContent: true
• “Are these image/page links dead?” → scrape_url with mode: "check" + urls: [...]
• “Scrape one URL for branding (colours/favicon)” → scrape_url with mode: "scrape"

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

Docker

docker pull moe003/convocore-mcp:latest

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

Build locally:

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

Docker Compose

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

Development

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 installpnpm run buildpnpm pack --dry-run     # sanity check the tarballpnpm publish --access public

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

Push Docker image (maintainers)

docker push moe003/convocore-mcp:latest

Telemetry

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

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

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

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

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

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

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

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

Contributing and license

Contributions are welcome via pull request.

MIT License — see the LICENSE file.

Links

• Convocore API / product docs
• Model Context Protocol
• npm — convocore-mcp
• Docker Hub — moe003/convocore-mcp
• Issues
• Convocore support

Built for the Convocore community.