io.github.TsvetanG2/cognigy-ai-mcp-management-server

Cognigy.AI Management MCP Server

Model Context Protocol server for managing Cognigy.AI virtual agents through the Management API

This is an independent, open-source MCP server and is not affiliated with, endorsed by, or sponsored by Cognigy or NiCE. It requires your own valid Cognigy.AI account and API key, used in accordance with Cognigy's commercial license terms. "Cognigy" and "Cognigy.AI" are trademarks of their respective owners.

What is this?

cognigy-ai-mcp-management-server is a local MCP server that enables AI coding assistants (Claude, Cursor, etc.) to build, configure, test, and operate Cognigy.AI conversational AI agents programmatically.

Instead of clicking through the Cognigy UI, you can now:

• Create and manage flows, nodes, and intents via natural language
• Run NLU training and regression tests automatically
• Deploy snapshots and packages across environments
• Configure LLMs, Knowledge AI, and integrations

Built for: Developers, solution architects, and SI partners who build on Cognigy.AI.

Requirements

• Node.js 20.0.0 or higher
• Cognigy.AI account with API access (Trial, SaaS, or on-premises)
• API Key generated from Cognigy UI (My Profile → API Keys)

Installation

# 1. Install the Cognigy REST API client (required peer dependency)
npm install @cognigy/rest-api-client

# 2. Install this MCP server
npm install -g cognigy-ai-mcp-management-server

Important: The @cognigy/rest-api-client package is licensed under "Cognigy Proprietary License". By installing it, you agree to Cognigy's license terms.

Configuration

Set environment variables before running:

# Required: Your Cognigy API endpoint
export COGNIGY_BASE_URL=https://api-trial.cognigy.ai

# Required: Your API key (never commit this!)
export COGNIGY_API_KEY=your-api-key-here

# Optional: Default project for operations
export COGNIGY_DEFAULT_PROJECT_ID=your-project-id

Common Base URLs:

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

All Tools

This server provides 132 MCP tools organized by domain:

Key Features

• Safe by default: All mutating tools use dryRun: true by default
• Async-aware: Long-running operations poll until completion
• Security: API keys only in memory, secrets automatically redacted
• Pagination: All list operations support limit and skip

Development & Testing

Live API Testing

# Create .env from template
cp .env.example .env
# Edit .env with your credentials

# Run development server
npm run dev

Build

npm run build    # Compile TypeScript
npm test         # Run test suite (49 tests)
npm run lint     # Check code style

Regenerate Types (optional)

If you need to update the generated types from a newer Cognigy API:

npm run update:spec   # Download latest OpenAPI spec
npm run gen:types     # Regenerate TypeScript types

Important: Dependencies

This package requires @cognigy/rest-api-client as a peer dependency. This means:

1. You must install it separately (see Installation above)
2. You accept Cognigy's license terms by installing their package
3. We do not bundle or redistribute any Cognigy code

You are responsible for:

• Reviewing and accepting Cognigy's proprietary license terms
• Having appropriate rights to use the Cognigy API
• Keeping your API credentials secure

The Cognigy REST API client is the official SDK maintained by Cognigy GmbH and is published on npm under "Cognigy Proprietary License".

License

This MCP server is released under the MIT License. See LICENSE for details.

Note: The MIT license applies only to this MCP server code. Dependencies (particularly @cognigy/rest-api-client) are subject to their own licenses.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow existing code patterns (Zod schemas, dryRun flags, etc.)
4. Add tests for new tools
5. Run npm test && npm run build before committing
6. Submit a Pull Request

Development Guidelines

• All tools must have Zod input validation
• Mutating tools must support dryRun flag (default: true)
• Tool descriptions should be LLM-friendly (1-2 sentences)
• Never log or expose API keys/secrets
• Test against mock server before live API

Support

• Issues: GitHub Issues
• Cognigy Docs: docs.cognigy.com
• MCP Spec: modelcontextprotocol.io

Built with Model Context Protocol SDK