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.

---

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
• 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.git

cd convocore-mcp pnpm install pnpm run build export WORKSPACE_SECRET="your_workspace_secret_here" export CONVO