Use this server to explore ConvoKit’s official integration documentation and plan platform-specific implementations.
List official ConvoKit guides, section indexes, source URLs, and snapshot date, optionally filtered by platform.
Search documentation sections for SDK methods, installation, authentication, errors, API routes, and UI behavior.
Read a guide’s section index and introduction, or fetch a specific section.
Retrieve exact documented code examples by guide, topic, and pagination.
Generate platform-specific integration plans with setup steps, backend token examples, and guide links for JavaScript, React, Vue, React Native, Flutter, Swift, or Android.
Provides ConvoKit integration guidance, setup plans, and code examples for adding chat and support features to Android applications.
Provides ConvoKit integration guidance, setup plans, and code examples for adding chat and support features to Flutter applications.
Provides ConvoKit integration guidance, setup plans, and code examples for adding chat and support features to JavaScript applications.
Provides ConvoKit integration guidance, setup plans, and code examples for adding chat and support features to React applications.
Provides guidance for adding the ConvoKit chat widget to Shopify themes and sites.
Provides ConvoKit integration guidance, setup plans, and Swift/SwiftUI code examples for adding chat and support features to Apple platform applications.
Provides guidance for adding the ConvoKit chat widget to Wix sites.
Provides guidance for adding the ConvoKit chat widget to WordPress sites.
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., "@ConvoKit MCP search the ConvoKit docs for how to authenticate users in a React app"
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.
Two MCP connections in one TypeScript package:
Connection | Purpose | Authentication |
Developer | Help coding assistants integrate ConvoKit using official SDK, UI, authentication, and REST guides | None |
App | Manage users, tokens, memberships, conversation metadata, and messages in one configured app | App credentials in server environment; separate bearer token for HTTP |
You need only the Developer connection to implement an integration. Add the App connection when your assistant should also configure or manage the app. There is no need for a separate MCP server for each SDK, UI framework, or existing REST API surface.
Both connections can run in one process, or in separate processes using the same package. The implementation uses the official MCP TypeScript SDK v2, supports local stdio and remote Streamable HTTP, and accepts the legacy 2025 MCP initialization exchange.
Connect directly to https://mcp.convokit.app/mcp/developer. No installation or credentials are required.
codex mcp add convokit_developer --url https://mcp.convokit.app/mcp/developerOr add this to ~/.codex/config.toml:
[mcp_servers.convokit_developer]
url = "https://mcp.convokit.app/mcp/developer"For Cursor, use examples/mcp-production.json in .cursor/mcp.json. The public setup guide is convokit.app/docs/mcp; Codex options are documented in the official MCP guide.
Requires Node.js 22.20 or later. Set your app's CONVOKIT_CLIENT_ID and CONVOKIT_CLIENT_SECRET in the local MCP process environment. Launch with:
npx -y github:ConvoKitApp/ConvoKit-MCP#v0.1.0 appThe first launch installs dependencies and builds the package. Allow up to two minutes; subsequent launches use npm's cache. The release is distributed from GitHub, not the npm registry.
Codex forwards the secret from the environment that launches it:
[mcp_servers.convokit_app]
command = "npx"
args = ["-y", "github:ConvoKitApp/ConvoKit-MCP#v0.1.0", "app"]
env_vars = ["CONVOKIT_CLIENT_SECRET"]
startup_timeout_sec = 120
[mcp_servers.convokit_app.env]
CONVOKIT_CLIENT_ID = "your-app-id"The dashboard's MCP integration tab provides app-specific Codex and JSON configurations. Keep credentials in a trusted local environment or private config outside source control. App management uses administrator credentials and can delete data; review your assistant's proposed changes.
npm ci
npm run buildCopy examples/mcp-local.json into your MCP client's server configuration. Replace /absolute/path/ConvoKit-MCP with this package's absolute path. The Developer connection is ready immediately; fill in your app's credentials to enable the App connection. Remove the App entry if you only need guides.
The local commands are:
node dist/cli.js developer
node dist/cli.js appThese speak MCP over stdin/stdout and are launched by your MCP client. Logs go to stderr. The default mode is developer.
Start the public Developer server:
npm startConnect your MCP client to http://127.0.0.1:3333/mcp/developer.
To enable the App endpoint, copy .env.example to .env and set:
CONVOKIT_CLIENT_ID=your-app-id
CONVOKIT_CLIENT_SECRET=your-server-only-secret
CONVOKIT_MCP_APP_TOKEN=your-distinct-random-access-token-at-least-32-charactersGenerate a new MCP token with:
node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"Load the environment explicitly:
node --env-file=.env dist/cli.js httpConnect to http://127.0.0.1:3333/mcp/app with Authorization: Bearer <CONVOKIT_MCP_APP_TOKEN>. The access token authenticates the MCP client; the server uses its separate ConvoKit app credentials for SDK calls. App credentials never appear in tool arguments or connection-info results.
Use examples/mcp-http.json as a starting point. MCP client configuration formats vary; clients must support custom bearer headers for this App endpoint. This version provides explicit token configuration, not a browser OAuth sign-in flow.
GET /health reports whether each connection is enabled. /mcp/app is unavailable unless configured. Partial HTTP app configuration fails startup. The public Developer endpoint needs no database or ConvoKit account.
Related MCP server: ProxyAI MCP
Tool | Use |
| List guides and their source URLs; optionally filter by platform |
| Find relevant documentation sections |
| Read an introductory section and section index, or select a section |
| Read exact documented snippets, filtered by topic and paginated |
| Get platform-specific setup steps, guide links, and backend token examples |
Supported platforms: javascript, react, vue, react-native, flutter, swift, android, and website (the paste-a-snippet chat widget for HTML, Wix, Shopify, and WordPress sites).
All 20 guides are also available as convokit://docs/<guide-id> resources. The integrate_convokit prompt accepts platform and goal and prepares a task grounded in the official guides.
Example requests to your assistant:
“Use ConvoKit to add support chat to this React application.”
“Find the SwiftUI example for read receipts.”
“Add the ConvoKit chat widget to our Shopify theme.”
“Show the authenticated backend token endpoint and adapt it to our session middleware.”
The checked-in src/content/guides.json snapshot is generated by rendering the landing-page documentation to Markdown. Code snippets retain their exact original text; source URLs, snapshot date, and a content hash accompany responses. The snapshot is bundled into both Node and Worker builds; runtime operation does not fetch arbitrary URLs or files.
After documentation changes, run:
npm run sync:docs
# Or specify another landing-page checkout:
node scripts/sync-docs.mjs /absolute/path/Convokit-LandingPageThe refresh command requires that landing-page checkout and its installed dependencies. Building and running the MCP package uses the already bundled snapshot and does not require sibling repositories. Refresh the snapshot when releasing documentation updates.
Tool | Use |
| Show the configured public app ID and API endpoint |
| Create or synchronize an app user |
| Update or delete an app user |
| Issue a scoped user JWT for an existing user |
| Change metadata or delete a conversation |
| Manage membership and READ / READ_WRITE roles |
| Edit text or delete a message; edits accept an optional revision |
Operations delegate to the published ConvoKitServerClient and use the backend's authorization and tenant checks. Delete operations carry MCP destructive annotations. User token results contain a sensitive, short lived JWT; app secrets and inbound MCP access tokens are never returned. API failures return status and code without echoing raw response bodies.
Upstream calls have a 15-second deadline and reject redirects so app credentials cannot be forwarded to a redirected endpoint.
Each App process is bound to one app. Multiple customers should run separate App instances with their own credentials, or use separate local stdio connections. A shared hosted service serving multiple customer apps would additionally need per-customer credential resolution, OAuth consent and scopes, and tenant isolation. This package does not implement account-wide dashboard, billing, end-user chat sessions, or realtime event subscriptions.
CONVOKIT_API_URL optionally overrides the managed API endpoint for local testing or self-hosting; the default is the SDK's https://api.convokit.app. Tools cannot change the app or endpoint.
One public Developer deployment can serve all integrators. Deploy App instances separately when they use different customer credentials. Two endpoints do not require two repositories or two deployments.
The production Worker serves only /mcp/developer and /health. It never imports the App server or has customer app credentials. The documentation is public, so this deployment allows browser CORS from all origins. Long-lived change subscriptions are disabled because the corpus is immutable within a deployment.
npm run worker:check
npm run worker:dry-run
npm run worker:deploy -- --var RELEASE_SHA:$(git rev-parse HEAD)
node scripts/smoke.mjs https://mcp.convokit.app/mcp/developer/health reports the release commit, version, snapshot date, and source hash. Wrangler uses the configured deployment account; forks should update the account and Worker name before deploying. See Workers configuration and the SDK HTTP handler.
For an external listener, set HOST=0.0.0.0 and CONVOKIT_MCP_ALLOWED_HOSTS to the hostnames your deployment serves. Put HTTPS in front of the service. Browser callers also require explicit full origins in CONVOKIT_MCP_ALLOWED_ORIGINS. Native MCP clients usually send no Origin header.
docker build -t convokit-mcp .
docker run --rm -p 3333:3333 \
-e CONVOKIT_MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
convokit-mcpThe container includes the documentation snapshot. To enable App management, supply the three App environment variables through your deployment's secret configuration. The service defaults to loopback outside Docker and restricts host headers, origins, and request sizes. It does not log request bodies or authorization headers.
npm run validateThe tests connect using the official MCP client over HTTP and stdio, cover modern and legacy exchanges, check documentation and code preservation, verify SDK request contracts, and test auth rejection, path encoding, revision forwarding, safe errors, host/origin checks, and body limits. Backend calls are mocked; no live customer data is modified.
Return exact code examples from an official guide. Filter by topic, or paginate with offset to find installation, token providers, chat UI, realtime, or media examples.
Inputs: guideId (required), limit, topic, offset.
Get a guide’s section index and introductory section, or read a specific section by sectionIndex. Full guides are also available as MCP resources.
Inputs: guideId (required), sectionIndex.
Plan a ConvoKit integration for JavaScript, React, Vue, React Native, Flutter, Swift, or Android, with backend token examples and links to the exact platform guides.
Inputs: platform (required), includeUi.
List official ConvoKit guides, section indexes, source URLs, and documentation snapshot date.
Inputs: platform.
Search documentation sections for SDK methods, installation, authentication, errors, API routes, and UI behavior. Use get_guide to read a returned sectionIndex.
Inputs: query (required), limit, platform.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Tools have distinct primary purposes, but list_guides and get_guide both can return section indexes, creating a minor overlap that could cause slight confusion when retrieving guide structure.
All tool names follow a consistent snake_case verb_noun pattern (list_guides, search_docs, get_guide, get_code_examples, get_integration_plan), making them predictable and easy to scan.
Five tools are well-scoped for a documentation retrieval server, covering the key operations without redundancy or bloat.
The surface covers discovery, search, reading, code examples, and integration planning, with full guides available as MCP resources, leaving no obvious dead ends for the stated purpose.
Work with shared spaces, threads, documents, skills, apps, automations, and connected tools.
Workspace messaging: conversations, contacts, agents, and connected lines through scoped OAuth.
Deploy apps from GitHub, read build/runtime logs, and manage your app's users from your AI agent.
Read, write, and combine connected apps and databases with shared code and per-person permissions.
