MCP in Claude, Codex and Cursor

MCP (Model Context Protocol) lets the AI you already use operate Cognizy: read conversations, search the knowledge base, create tasks, move deals, schedule posts. The tools come from the API itself, with the same rules as Cognizy's own agents. The full list is in MCP tools.

Before you start

1. Create a key in Settings › Integrations › API and webhooks with only the permissions the AI should have. To start, tick read access on the modules you use; open up writes later, module by module.
2. Choose how to connect:
   • Local (the @cognizy/mcp package, running on your computer with npx; needs Node 20 or newer): Claude Desktop, Claude Code, Codex and Cursor.
   • Hosted (https://mcp.cognizy.ai/mcp, nothing to install): clients that let you set a header, such as Claude Code and Cursor.

Claude Desktop

Edit the config file (on Mac, ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, %APPDATA%\Claude\claude_desktop_config.json) and restart the app:

{
  "mcpServers": {
    "cognizy": {
      "command": "npx",
      "args": ["-y", "@cognizy/mcp"],
      "env": { "COGNIZY_API_KEY": "paste-your-key-here" }
    }
  }
}

This config applies to every chat. For more than one company, add one entry per key (cognizy-store, cognizy-clinic…) and enable only the one you want in each chat.

Claude Code

Local:

claude mcp add --scope user cognizy -e COGNIZY_API_KEY=paste-your-key-here \
  -- npx -y @cognizy/mcp

Hosted:

claude mcp add --transport http cognizy https://mcp.cognizy.ai/mcp \
  --header "Authorization: Bearer $COGNIZY_API_KEY"

A key belongs to one company. To work with a different company in each project, use --scope local inside each folder with that company's key. claude mcp list shows which one is active.

Codex

The Codex app, CLI and IDE extension share ~/.codex/config.toml:

[mcp_servers.cognizy]
command = "npx"
args = ["-y", "@cognizy/mcp"]

[mcp_servers.cognizy.env]
COGNIZY_API_KEY = "paste-your-key-here"

Cursor

In ~/.cursor/mcp.json (or .cursor/mcp.json in the project). Local:

{
  "mcpServers": {
    "cognizy": {
      "command": "npx",
      "args": ["-y", "@cognizy/mcp"],
      "env": { "COGNIZY_API_KEY": "paste-your-key-here" }
    }
  }
}

Hosted:

{
  "mcpServers": {
    "cognizy": {
      "url": "https://mcp.cognizy.ai/mcp",
      "headers": { "Authorization": "Bearer paste-your-key-here" }
    }
  }
}

What to ask

• "How many conversations did we close last week? Split by channel."
• "Search the knowledge base for the return policy and sum it up in 3 lines."
• "List the deals stuck for more than 7 days in the Proposal stage."
• "Create a task on the Support board to call Maria tomorrow at 10am."
• "Schedule a post for Friday with the latest Izy Studio art." (goes to approval)

Permissions and approval

• The AI only sees the tools the key allows and the modules turned on for the company. Without the permission, the tool doesn't even show up.
• Whatever reaches the customer (sending a message, booking, cancelling, launching a campaign) doesn't run right away: it becomes a request an owner or admin approves in To review or in the AI Approvals tab. The AI gets an actionId and can follow it with get_pending_action_status or withdraw it with cancel_pending_action.
• Social posts go to approval unless the key has social:publish.
• Direct email sends are not an MCP tool: they belong to your backend, through the API. send_whatsapp_message only shows up for keys with whatsapp:send; don't give that permission to an AI unless that's what you want.

Limits

MCP calls the public API, so the key's limits apply: 60 calls per minute, 1,000 per hour and the company's monthly quota. Every call is logged in the key's activity.