@cognizy/mcp

Let AI assistants operate your Cognizy workspace. Connect Claude Desktop, Cursor, ChatGPT, or any MCP client to read conversations, search your knowledge base, query analytics, manage tasks, and orchestrate scheduling/campaigns — with full audit logging and an approval flow for customer-facing actions.

84 tools across 12 domains. Read-only by default. Customer-facing inbox writes require human approval before they execute; direct WhatsApp sends are queued immediately for delivery.

Quick start

1. Generate an API key in Cognizy

In the dashboard: Settings → Developers → API Keys → Create. Pick the scopes you need (see Scopes below) and copy the cgz_live_… token.

2. Add to your MCP client

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cognizy": {
      "command": "npx",
      "args": ["-y", "@cognizy/mcp"],
      "env": {
        "COGNIZY_API_KEY": "cgz_live_your_key_here"
      }
    }
  }
}

Cursor — same shape in ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{
  "mcpServers": {
    "cognizy": {
      "command": "npx",
      "args": ["-y", "@cognizy/mcp"],
      "env": { "COGNIZY_API_KEY": "cgz_live_..." }
    }
  }
}

Claude Code (CLI):

claude mcp add --scope user cognizy npx -- -y @cognizy/mcp \
  --env COGNIZY_API_KEY=cgz_live_...

3. Restart the client

The Cognizy tools show up in the tool picker. Try asking:

"List my Cognizy agents."

"How many conversations did I close last week? Group by channel."

"Search my knowledge base for refund policy."

Deployment modes

Self-hosted (stdio) — recommended for individuals

The config above runs the server on your machine via npx. Zero infrastructure, fastest to set up, your API key never leaves your laptop.

Hosted (HTTP) — no install required

Point your client at https://mcp.cognizy.ai/mcp directly:

{
  "mcpServers": {
    "cognizy": {
      "url": "https://mcp.cognizy.ai/mcp",
      "headers": { "Authorization": "Bearer cgz_live_..." }
    }
  }
}

Use this when the client doesn't support stdio (web playgrounds, custom integrations) or when you want session continuity across machines.

Available tools

53 tools, grouped by domain. Each tool requires the matching scope on the API key.

Read-only (23)

| Domain | Tools | |---|---| | Agents | list_agents | | Conversations | search_conversations, get_conversation, list_messages | | Knowledge base | search_knowledge_base (semantic, pgvector), list_knowledge_bases, get_knowledge_base, list_documents, get_document | | Contacts | search_contacts, get_contact | | Analytics | get_analytics | | Tasks | list_task_boards, get_task_board, list_tasks, get_task | | Scheduling | list_booking_pages, list_appointments, get_appointment | | Campaigns | list_campaigns, get_campaign, get_campaign_analytics | | Lead-capture funnels | list_marketing_funnels, get_marketing_funnel, list_funnel_leads, get_funnel_lead_timeline, analyze_marketing_funnel, list_funnel_rules, get_stage_cadence | | Sales | list_sales_pipeline_stages, list_sales_deals, get_sales_deal, analyze_sales_pipeline | | WhatsApp | list_whatsapp_instances |

Direct writes (22) — execute immediately, audited

Low-risk, reversible. Don't reach the customer.

| Domain | Tools | |---|---| | Knowledge base | create_knowledge_base, add_document, bulk_add_documents (up to 200), update_document, delete_document | | Tasks | create_task, delete_task, update_task, move_task, assign_task, unassign_task, add_task_comment, add_task_label, remove_task_label, add_checklist_item, toggle_checklist_item, delete_checklist_item | | Contacts | add_tag_to_contact, remove_tag_from_contact | | Lead-capture funnels | Create/configure funnels, stages, rules and cadences; create, move, update or delete funnel leads | | Sales | Create/configure sales stages; create, move, update or delete deals | | Conversations | add_tag_to_conversation, remove_tag_from_conversation, assign_conversation |

Direct WhatsApp write (1) — queued for delivery immediately

| Tool | What it does | |---|---| | send_whatsapp_message | Queues a text message directly through the selected connected WhatsApp instance. Requires whatsapp:send; no dashboard approval and no inbox conversation. |

Approval-gated writes (7) — queued, OWNER/ADMIN approves

Customer-facing. Each call returns 202 with an actionId instead of executing. An organization admin reviews the action in the Cognizy dashboard before it fires.

| Tool | What it does | TTL | |---|---|---| | send_message_to_contact | Send a WhatsApp/Email/Instagram/Messenger message | 4h | | book_appointment | Schedule a new appointment | 24h | | cancel_appointment | Cancel an existing appointment | 24h | | reschedule_appointment | Move an appointment to a new time | 24h | | launch_campaign | Launch a DRAFT campaign to its audience | 1h | | get_pending_action_status | Poll the status of a queued action | — | | cancel_pending_action | Drop a pending action you created | — |

Approval notifications fan out to OWNER + ADMIN members of the org via the dashboard's notification bell, email with deep-link, and a header badge counter.

Scopes

Scopes are enforced by the Cognizy API per request. Create your key with only what you need.

| Scope | Unlocks | |---|---| | agents:read | list_agents | | conversations:read / :write | conversation read/write tools | | messages:read / :write | message read + send_message_to_contact | | contacts:read / :write | contact read + tagging | | knowledge-base:read / :write | KB read + create/update/delete documents | | analytics:read | get_analytics | | tasks:read / :write | task read + all task mutations | | scheduling:read / :write | scheduling read + book/cancel/reschedule | | campaigns:read / :write | campaign read + launch_campaign | | marketing-funnels:read / :write | lead-capture funnels, leads, rules, cadences and deterministic insights | | sales:read / :write | sales stages, deals and deterministic sales insights | | webhooks:manage | (used by REST API, not MCP today) | | whatsapp:read | list_whatsapp_instances | | whatsapp:send | send_whatsapp_message |

A key with no scopes can authenticate but can't call any tool — this is intentional to keep the principle of least privilege easy to enforce.

Why the Send APIs aren't tools

Cognizy has two direct-send REST endpoints — /v1/public/whatsapp/messages and /v1/public/email/messages — that deliver to a customer immediately, with no inbox conversation and no review step. They exist for transactional traffic your own backend triggers: an order shipped, a password reset, an invoice.

They are deliberately absent from MCP. Everything here that reaches a customer goes through the approval flow, and an agent holding a key with email:send could push a thousand emails with nobody in the loop — precisely what send_message_to_contact queues an admin to prevent. A scope that bypasses review does not belong on a surface an LLM drives.

Use them from your backend with @cognizy/sdk:

await cognizy.email.send({
  to: '[email protected]',
  templateId: 'tpl_123',
  variables: { 'contact.firstName': 'Maria', 'order.id': '#1001' },
  idempotencyKey: 'order-1001-shipped',
});

If an agent should be able to message a customer, give the key messages:write and let send_message_to_contact route it through approval.

Example workflows

Knowledge base population from real conversations

"Look at the last 100 closed conversations. Group them by recurring themes. For each theme, write a short FAQ article and save it to a new knowledge base called 'AI-generated FAQ'."

The agent chains:

1. search_conversations (status=CLOSED, limit=100)
2. list_messages per conversation
3. (LLM analysis identifies themes)
4. create_knowledge_base
5. bulk_add_documents — all themes in one shot

The new content is searchable within seconds via search_knowledge_base and used by your in-app AI agent automatically.

Triage stuck tickets

"Find tasks in the Support board that are 'In Progress' and haven't been updated in 3 days. For each, set priority to URGENT, due tomorrow 5pm, assign to Mary, add the 'sla-risk' label, and post a comment tagging Mary."

Chain:

1. list_tasks (filter columnId + recent activity)
2. update_task × N
3. assign_task × N
4. add_task_label × N
5. add_task_comment × N

All audit-logged. Every step visible in the dashboard's API Activity panel.

Customer outreach with safety net

"Customer Wayter just asked about refund. Pull his last 5 messages, search the KB for refund policy, draft a personalised reply on WhatsApp, and queue it for my approval."

Chain:

1. search_contacts → find Wayter
2. list_messages → context
3. search_knowledge_base → policy
4. send_message_to_contact → returns 202, action queued

You get an email + bell notification. Open the dashboard, review the drafted message, click Approve. The message reaches the customer's WhatsApp. The execution result lands on the action with timestamp + delivery confirmation.

Security & audit

• Multi-tenant by construction. Every request is scoped to the organization that owns the API key. The MCP server never sees data from another tenant.
• Scopes enforced server-side. The MCP client can't bypass scopes; the Cognizy API rejects out-of-scope calls with 403.
• No state in the MCP server. Every tool call proxies to the Cognizy REST API. Auth, rate-limit, quota, and audit logging are all enforced there.
• API key in transit only. The key flows MCP client → MCP server → Cognizy API via x-api-key / Authorization: Bearer. The hosted MCP server doesn't persist it on disk.
• Audit log per call. Each /v1/public/* request lands in PublicApiAuditLog with org, key, method, path, status, duration, IP, UA, and error message. Visible per key under Settings → Developers → Activity.
• Approval flow protects against prompt injection. Customer-facing writes never execute inline — even if a malicious customer message tricks the AI into "send X to everyone", the action lands as PENDING and the admin sees exactly what would go out.

Configuration reference

| Env var | Default | Purpose | |---|---|---| | COGNIZY_API_KEY | (required) | The cgz_live_… key. Generate in dashboard. | | COGNIZY_API_URL | https://api.cognizy.ai/api | Override for self-hosted Cognizy deployments. | | COGNIZY_TIMEOUT_MS | 30000 | Per-request timeout. | | PORT | 3333 | HTTP mode only — port to listen on. |

Development

git clone https://github.com/cognizy/cognizy-mcp.git
cd cognizy-mcp
npm install
npm run build

# Run locally:
COGNIZY_API_KEY=cgz_live_... npm run dev:stdio   # stdio mode, hot-reload
COGNIZY_API_KEY=cgz_live_... npm run dev:http    # http mode on :3333

npm test

Tools live in src/tools/. Each tool is a defineTool({ name, description, scope, inputSchema, handler }) object. Add it to src/tools/index.ts to register.

Compatibility

• Node 20+ (the MCP SDK requires it).
• MCP protocol version 2025-03-26 (Streamable HTTP transport in hosted mode).
• Tested with Claude Desktop, Claude Code, and Cursor.

Roadmap

• Resources & Prompts (MCP primitives beyond tools) — pre-built playbooks like "weekly digest", "at-risk customers"
• WebSocket events — push notifications from Cognizy to the client when a customer replies, an SLA breaches, etc.
• More approval-gated executors — bulk_send_message, create_campaign_draft (approval-gated like every customer-facing write; the direct Send APIs stay REST/SDK-only)
• Per-action notification preferences (opt-out by type)

Links

• Package on npm
• GitHub repository
• Cognizy
• Model Context Protocol spec

License

MIT — see LICENSE.