# TsvetanG2/cognigy-ai-mcp-management-server [Health: Active]

**Category:** 🗣️ Conversational AI  
**Repository:** https://github.com/TsvetanG2/cognigy-ai-mcp-management-server  
**GitHub Stars:** 2  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tsvetang2-cognigy-ai-mcp-management-server

## Description
Management and automation server for the Cognigy.AI conversational AI platform, exposing 132 tools across flows, agents, snapshots, NLU, functions, and deployment. Published to the official MCP Registry. npx mcp-cognigy

## Tools
Capabilities this server exposes over MCP:

- **list_projects** — Lists all Cognigy.AI projects accessible by your API key. Use this to discover available projects before working with flows, intents, or other resources.
- **list_flows** — Lists all flows in a Cognigy.AI project. Flows are conversation logic containers. Use this to discover flows before reading or modifying them.
- **get_flow** — Gets detailed metadata about a specific Cognigy.AI flow. Returns flow configuration, locale info, and timestamps. Use this to inspect a flow before modifying it.
- **get_flow_settings** — Gets the settings/configuration of a Cognigy.AI flow. Returns NLU settings, thresholds, and other flow-level configurations. Use this before updating flow settings.
- **get_latest_log_entries** — Gets the latest execution log entries from a Cognigy.AI project. Use this for debugging flow execution, viewing errors, or monitoring agent behavior.
- **get_nodes** — Lists all nodes in a Cognigy.AI flow. Nodes are the building blocks of conversation logic (Say, Question, If, Code, etc.). Use this to explore flow structure before reading specific nodes or modifying the flow.
- **get_node** — Gets detailed configuration of a specific node in a Cognigy.AI flow. Returns the node's type, label, config fields, and settings. Use this to inspect node behavior before modifying it.
- **search_nodes** — Searches for nodes in a Cognigy.AI flow by text content. Finds nodes containing the search term in their configuration (messages, conditions, code, etc.). Use this to locate specific content within large flows.
- **get_node_descriptors** — Gets all available node types (blueprints) that can be created in a Cognigy.AI flow. Returns node type definitions including their fields, appearance, and constraints. Use this to understand what nodes can be added to a flow.
- **list_intents** — Lists all intents in a Cognigy.AI flow. Intents are the NLU triggers that match user utterances to flow logic. Use this to explore NLU configuration before training or modifying intents.
- **get_intent** — Gets detailed configuration of a specific intent in a Cognigy.AI flow. Returns the intent's conditions, rules, confirmation sentences, and settings. Use this to inspect NLU behavior before modifying.
- **list_endpoints** — Lists all endpoints in a Cognigy.AI project. Endpoints are channel connectors (Webchat, REST, Voice, etc.) that expose flows/agents to users. Use this to discover deployed channels.
- **get_endpoint** — Gets detailed configuration of a specific Cognigy.AI endpoint. Returns channel settings, flow/agent binding, and runtime configuration. Use this to inspect endpoint behavior.
- **inject_context** — Injects context data into a Cognigy.AI session. Context is shared state accessible by flow nodes. Use this to set user data, preferences, or state before/during conversations.
- **reset_context** — Resets the context for a Cognigy.AI session, clearing all stored state. Use this to start a fresh conversation or clear user data during testing.
- **get_conversations** — Gets conversations for specific contacts in a Cognigy.AI project. Returns conversation history including inputs, outputs, and metadata. Use this to analyze user interactions.
- **get_conversation** — Gets conversation details for a specific Cognigy.AI session. Returns all inputs/outputs, timestamps, and metadata for the session. Use this to analyze a complete conversation thread.
- **get_transcript** — Assembles a human-readable transcript for a Cognigy.AI session. Shows the conversation flow between user and bot in chronological order. Use this for reviewing conversation quality or debugging.
- **list_snapshots** — Lists all snapshots in a Cognigy.AI project. Snapshots are versioned backups of project configuration used for deployment and rollback. Use this to see available versions.
- **get_snapshot** — Gets detailed information about a specific Cognigy.AI snapshot. Returns name, description, hash, and packaging status. Use this to inspect a version before deployment.
- **get_snapshot_resources** — Lists resources (flows, locales, NLU connectors, LLMs) contained in a Cognigy.AI snapshot. Use this to inspect what a snapshot contains before restoring or to compare versions.
- **list_tasks** — Lists async tasks in Cognigy.AI. Tasks track long-running operations like snapshot creation, training, and imports. Use this to monitor background job status.
- **get_task** — Gets detailed status of a specific Cognigy.AI async task. Returns progress, status, and failure reason if applicable. Use this to poll long-running operations to completion.
- **create_node** — Creates a new node in a Cognigy.AI flow. MUTATING: This modifies the flow. Use dryRun=true (default) to validate first. Nodes are the building blocks of conversation logic (Say, Question, If, Code, etc.).
- **update_node** — Updates an existing node in a Cognigy.AI flow. MUTATING: This modifies the node. Use dryRun=true (default) to validate first. Only provided fields are updated; others remain unchanged.
- **delete_node** — Deletes a node from a Cognigy.AI flow. MUTATING & DESTRUCTIVE: This permanently removes the node. Use dryRun=true (default) to validate first. Child nodes may also be affected.
- **move_node** — Moves a node to a new position in a Cognigy.AI flow. MUTATING: This reorganizes the flow structure. Use dryRun=true (default) to validate first. Moving nodes affects execution order.
- **generate_node_output** — Uses Cognigy's generative AI to create content for Say nodes. Generates either plain text messages or rich Adaptive Cards based on a natural language prompt. Returns content you can use with create_node or update_node.
- **create_intent** — Creates a new intent in a Cognigy.AI flow for NLU recognition. MUTATING: This modifies the flow. Use dryRun=true (default) to validate first. After creating, use train_intents to train the NLU model.
- **update_intent** — Updates an existing intent in a Cognigy.AI flow. MUTATING: This modifies the intent. Use dryRun=true (default) to validate first. After updating, call train_intents to retrain the NLU model.
- **delete_intent** — Deletes an intent from a Cognigy.AI flow. MUTATING & DESTRUCTIVE: This permanently removes the intent and its example sentences. Use dryRun=true (default) to validate first. After deleting, call train_intents to retrain.
- **train_intents** — Trains the NLU model for a Cognigy.AI flow. MUTATING: This triggers model training. Use dryRun=true (default) to validate first. Training is async - this tool polls until completion or timeout.
- **list_sentences** — Lists example sentences (training data) for a Cognigy.AI NLU intent. Use this to review training data quality before training.
- **create_sentence** — Creates a new example sentence for Cognigy.AI NLU intent training. MUTATING: This modifies the intent's training data. Use dryRun=true (default) to validate first. After creating, call train_intents to retrain.
- **generate_sentences** — Uses Cognigy AI to generate example sentences for an intent. The generated sentences are NOT automatically added - use create_sentence to add them. Useful for quickly expanding NLU training data.
- **list_playbooks** — Lists all playbooks in a Cognigy.AI project. Playbooks are automated test scenarios with steps and assertions for testing conversational flows.
- **get_playbook** — Gets detailed Cognigy.AI playbook configuration including all steps and assertions. Use this to understand what a playbook tests before running it.
- **run_playbook** — Runs a Cognigy.AI playbook test scenario against a flow. MUTATING: This executes test assertions. Use dryRun=true (default) to validate first. Returns pass/fail results with assertion details.
- **list_playbook_runs** — Lists Cognigy.AI playbook run history showing pass/fail status, timestamps, and run metadata. Use this to review test results over time.
- **get_playbook_run** — Gets detailed results of a Cognigy.AI playbook run including step-by-step assertion outcomes. Use this to analyze test failures and debug conversation flows.
- **generate_nlu_scores** — Scores a test utterance against a Cognigy.AI flow's trained NLU intents. Returns ranked intent matches with confidence scores. Use this to test NLU recognition before deployment.
- **score_utterance** — Scores a test utterance against a Cognigy.AI flow's trained NLU intents. Returns the best matching intent with confidence score. Use this to quickly test if an utterance would be recognized correctly.
- **run_regression** — Runs all Cognigy.AI playbooks in a project as a regression test suite. MUTATING: This executes tests. Use dryRun=true (default) to preview. Returns pass/fail summary with failing playbooks highlighted.
- **audit_nlu** — Audits Cognigy.AI NLU quality for a flow. Identifies intents with too few training sentences, disabled intents, and optionally checks for overlapping intents. Use this before deployment to ensure NLU quality.
- **create_snapshot** — Creates a snapshot of a Cognigy.AI project. Snapshots capture the entire project configuration (flows, intents, endpoints, etc.) for backup or deployment. MUTATING: Set dryRun=false to create. Async operation - polls until complete.
- **delete_snapshot** — Deletes a snapshot from a Cognigy.AI project. DESTRUCTIVE & IRREVERSIBLE: The snapshot and all its data will be permanently removed. Use dryRun=true (default) to validate first. Async operation.
- **create_snapshot_download_link** — Creates a temporary download link for a Cognigy.AI snapshot. The link can be used to download the snapshot as a file for backup or transfer to another environment. Links are time-limited.
- **restore_snapshot** — Restores a snapshot to its Cognigy.AI project, replacing the current configuration. DESTRUCTIVE: Current project state will be overwritten with the snapshot's state. Use dryRun=true (default) to validate first. Async operation.
- **package_snapshot** — Packages a Cognigy.AI snapshot for download or transfer. Creates a downloadable package from the snapshot. Use create_snapshot_download_link after packaging to get the download URL. MUTATING: Set dryRun=false to package. Async operation.
- **upload_snapshot_package** — Uploads a snapshot package file to a Cognigy.AI project. Use this to restore a previously downloaded snapshot or transfer a snapshot between environments. MUTATING: Set dryRun=false to upload. Async operation.
- **list_packages** — Lists packages in a Cognigy.AI project. Packages are portable bundles of resources (flows, intents, etc.) that can be transferred between projects or environments.
- **get_package** — Gets detailed information about a Cognigy.AI package including its name, description, and contained resources.
- **create_package** — Creates a package from selected resources in a Cognigy.AI project. Packages bundle flows, endpoints, and other resources for transfer between projects. MUTATING: Set dryRun=false to create. Async operation.
- **delete_package** — Deletes a package from a Cognigy.AI project. DESTRUCTIVE & IRREVERSIBLE: The package will be permanently removed. Use dryRun=true (default) to validate first. Async operation.
- **merge_package** — Merges a package into a Cognigy.AI project, importing selected resources. Use localeMapping to map package locales to project locales. MUTATING: Set dryRun=false to merge. Async operation.
- **upload_package** — Uploads a package file to a Cognigy.AI project. Use this to import a previously downloaded package or transfer resources between environments. MUTATING: Set dryRun=false to upload. Async operation.
- **create_package_download_link** — Creates a temporary download link for a Cognigy.AI package. The link can be used to download the package file for backup or transfer. Links are time-limited.
- **diff_snapshots** — Compares two Cognigy.AI snapshots and shows what changed (added, removed, modified resources). Useful for reviewing changes before deployment or understanding what a snapshot update will affect.
- **promote_snapshot** — Promotes a Cognigy.AI snapshot for deployment by packaging it and generating a download link. Use this to prepare a snapshot for transfer to another environment. MUTATING: Set dryRun=false to package. Async operation.
- **clone_flow** — Clones a Cognigy.AI flow within the same project. Creates an exact copy of the flow including all nodes, intents, and configurations. The cloned flow gets an auto-generated name. MUTATING: Set dryRun=false to clone.
- **list_connections** — Lists Cognigy.AI connections (external service integrations like databases, APIs, etc.). Connections store credentials securely. Use this to find available connections for a project or organization.
- **get_connection** — Gets detailed information about a specific Cognigy.AI connection. Returns connection metadata and schema. NOTE: Secret values are REDACTED for security - this tool only shows field names, not actual credentials.
- **create_connection** — Creates a new Cognigy.AI connection for external service integration. Connections securely store credentials like API keys, passwords, and tokens. MUTATING: Set dryRun=false to create.
- **update_connection** — Updates an existing Cognigy.AI connection. Use this to change connection name or update credential values. MUTATING: Set dryRun=false to update.
- **delete_connection** — Deletes a Cognigy.AI connection. WARNING: This is destructive and cannot be undone. Flows using this connection will break. MUTATING: Set dryRun=false to delete.
- **list_llms** — Lists Cognigy.AI large language model configurations. LLMs are used for generative AI features like Knowledge AI, AI Agents, and node output generation. Shows provider, model type, and connection info.
- **get_llm** — Gets detailed configuration of a specific Cognigy.AI large language model. Returns provider settings, model type, connection details, and fallback configuration.
- **create_llm** — Creates a new Cognigy.AI large language model configuration. LLMs power Knowledge AI, AI Agents, and generative features. Requires a connection with provider credentials. MUTATING: Set dryRun=false to create.
- **update_llm** — Updates an existing Cognigy.AI large language model configuration. Use this to change name, description, credentials, or provider settings. MUTATING: Set dryRun=false to update.
- **delete_llm** — Deletes a Cognigy.AI large language model configuration. WARNING: Features using this LLM will stop working. MUTATING: Set dryRun=false to delete.
- **clone_llm** — Clones a Cognigy.AI large language model configuration. Creates a copy with the same settings that can be modified independently. MUTATING: Set dryRun=false to clone.
- **test_llm_connection** — Tests the connection to a Cognigy.AI large language model provider. Validates that the credentials are correct and the provider is reachable. Use this to verify LLM setup before using it in flows.
- **list_nlu_connectors** — Lists Cognigy.AI NLU connectors. NLU connectors enable integration with external NLU services like Dialogflow, LUIS, Watson, or custom solutions for intent recognition.
- **get_nlu_connector** — Gets detailed configuration of a specific Cognigy.AI NLU connector. Returns type, settings, and connection details for external NLU service integration.
- **create_nlu_connector** — Creates a new Cognigy.AI NLU connector for external NLU service integration. Supports Dialogflow, LUIS, Watson, Alexa, Lex, and custom code connectors. MUTATING: Set dryRun=false to create.
- **update_nlu_connector** — Updates an existing Cognigy.AI NLU connector. Use this to change name or update type-specific settings. MUTATING: Set dryRun=false to update.
- **delete_nlu_connector** — Deletes a Cognigy.AI NLU connector. WARNING: Endpoints using this connector will lose NLU functionality. MUTATING: Set dryRun=false to delete.
- **list_knowledge_stores** — Lists Cognigy.AI Knowledge AI stores. Knowledge stores are containers for RAG (Retrieval-Augmented Generation) content used by AI Agents to answer questions from your data.
- **get_knowledge_store** — Gets detailed configuration of a specific Cognigy.AI knowledge store. Returns store settings, language, embedding model, and source counts.
- **create_knowledge_store** — Creates a new Cognigy.AI knowledge store for RAG content. Knowledge stores contain sources (documents) that AI Agents can search to answer questions. MUTATING: Set dryRun=false to create.
- **update_knowledge_store** — Updates an existing Cognigy.AI knowledge store. Use this to change name or description. MUTATING: Set dryRun=false to update.
- **delete_knowledge_store** — Deletes a Cognigy.AI knowledge store and ALL its sources and chunks. WARNING: This is destructive and cannot be undone. AI Agents using this store will lose access. MUTATING: Set dryRun=false to delete.
- **list_knowledge_sources** — Lists knowledge sources in a Cognigy.AI knowledge store. Sources are documents (PDFs, web pages, text files) that have been ingested and chunked for RAG retrieval.
- **get_knowledge_source** — Gets detailed information about a specific Cognigy.AI knowledge source. Returns source metadata, processing status, chunk count, and ingestion details.
- **create_knowledge_source** — Creates a new Cognigy.AI knowledge source for RAG content ingestion. Sources can be URLs, uploaded files, or manual text. Content is automatically chunked and embedded. MUTATING: Set dryRun=false to create.
- **update_knowledge_source** — Updates an existing Cognigy.AI knowledge source. Use this to change name or description. MUTATING: Set dryRun=false to update.
- **delete_knowledge_source** — Deletes a Cognigy.AI knowledge source and all its chunks. WARNING: This is destructive. The document content will no longer be searchable. MUTATING: Set dryRun=false to delete.
- **list_knowledge_chunks** — Lists knowledge chunks in a Cognigy.AI knowledge store. Chunks are the actual text segments used for RAG retrieval, created by splitting source documents.
- **get_knowledge_chunk** — Gets the full content of a specific Cognigy.AI knowledge chunk. Returns the complete text, metadata, and source information. Use this to inspect what content is being used in RAG searches.
- **create_knowledge_chunk** — Creates a new Cognigy.AI knowledge chunk manually. Use this to add specific text segments that should be searchable via RAG. The chunk will be embedded automatically. MUTATING: Set dryRun=false to create.
- **update_knowledge_chunk** — Updates an existing Cognigy.AI knowledge chunk. If text is changed, the chunk will be re-embedded. MUTATING: Set dryRun=false to update.
- **delete_knowledge_chunk** — Deletes a Cognigy.AI knowledge chunk. The content will no longer be searchable via RAG. MUTATING: Set dryRun=false to delete.
- **list_knowledge_connectors** — Lists Cognigy.AI knowledge connectors for automated content ingestion. Connectors can pull content from external sources like SharePoint, Confluence, or custom APIs.
- **get_knowledge_connector** — Gets detailed configuration of a specific Cognigy.AI knowledge connector. Returns connector type, schedule, connection settings, and run status.
- **create_knowledge_connector** — Creates a new Cognigy.AI knowledge connector for automated content ingestion from external sources like SharePoint or Confluence. MUTATING: Set dryRun=false to create.
- **update_knowledge_connector** — Updates an existing Cognigy.AI knowledge connector. Use this to change settings or name. MUTATING: Set dryRun=false to update.
- **delete_knowledge_connector** — Deletes a Cognigy.AI knowledge connector. Stops automated content ingestion from the external source. MUTATING: Set dryRun=false to delete.
- **run_knowledge_connector** — Triggers a Cognigy.AI knowledge connector to run immediately. Pulls content from the external source and creates/updates knowledge chunks. MUTATING: Set dryRun=false to run.
- **list_functions** — Lists Cognigy.AI Functions. Functions are custom code modules that can be triggered to run computations, integrations, or scheduled jobs outside of flow execution.
- **get_function** — Gets detailed configuration of a specific Cognigy.AI Function. Returns the function code, settings, and runtime configuration.
- **create_function** — Creates a new Cognigy.AI Function. Functions are custom code modules for integrations, scheduled jobs, or computations. MUTATING: Set dryRun=false to create.
- **update_function** — Updates an existing Cognigy.AI Function. Use this to change code, name, or parameters. MUTATING: Set dryRun=false to update.
- **delete_function** — Deletes a Cognigy.AI Function. WARNING: This is destructive. Flows calling this function will fail. MUTATING: Set dryRun=false to delete.
- **list_function_instances** — Lists running and completed instances of a Cognigy.AI Function. Shows execution history, status, and results.
- **get_function_instance** — Gets detailed information about a specific Cognigy.AI Function instance. Returns execution status, timing, input parameters, and output/error.
- **trigger_function** — Triggers a Cognigy.AI Function to run immediately. Creates a new function instance that executes the function code. MUTATING: Set dryRun=false to trigger.
- **stop_function_instance** — Stops a running Cognigy.AI Function instance. Use this to cancel a long-running or stuck function. MUTATING: Set dryRun=false to stop.
- **list_extensions** — Lists Cognigy.AI Extensions. Extensions are custom node packages that add new capabilities to flows (e.g., integrations, custom actions).
- **get_extension** — Gets detailed information about a specific Cognigy.AI Extension. Returns package info, available nodes, connections schemas, and settings.
- **delete_extension** — Deletes a Cognigy.AI Extension. WARNING: Flows using nodes from this extension will break. MUTATING: Set dryRun=false to delete.
- **update_extension** — Updates Cognigy.AI Extension settings like trusted code flag. Use this to enable/disable full Node.js API access. MUTATING: Set dryRun=false to update.
- **upload_extension** — Uploads a new Cognigy.AI Extension from a URL. The extension package must be a .tar.gz file. This is an async operation that polls until complete. MUTATING: Set dryRun=false to upload.
- **update_extension_package** — Updates a Cognigy.AI Extension with a new package version from a URL. Use this to upgrade an extension to a new version. MUTATING: Set dryRun=false to update.
- **list_contact_profiles** — Lists Cognigy.AI contact profiles. Contact profiles store user data across sessions (name, preferences, conversation history metadata).
- **get_contact_profile** — Gets detailed information about a specific Cognigy.AI contact profile. Returns stored user data, goals, and profile metadata.
- **create_contact_profile** — Creates a new Cognigy.AI contact profile. Contact profiles persist user data across sessions for personalization. MUTATING: Set dryRun=false to create.
- **update_contact_profile** — Updates an existing Cognigy.AI contact profile. Use this to modify stored user data or GDPR consent. MUTATING: Set dryRun=false to update.
- **delete_contact_profile** — Deletes a Cognigy.AI contact profile. WARNING: This permanently removes all stored user data for this profile. MUTATING: Set dryRun=false to delete.
- **remove_contact_id** — Removes a contact ID from a Cognigy.AI contact profile. Use this when a user identifier should no longer be associated with a profile. MUTATING: Set dryRun=false to remove.
- **merge_contact_profiles** — Merges two Cognigy.AI contact profiles into one. The source profile data is merged into the target, and all contact IDs are combined. Use when the same user has multiple profiles. MUTATING: Set dryRun=false to merge.
- **unmerge_contact_profiles** — Splits a merged Cognigy.AI contact profile back into separate profiles. Use when profiles were incorrectly merged. MUTATING: Set dryRun=false to unmerge.
- **export_contact_profile** — Exports all data for a Cognigy.AI contact profile. Use this for GDPR data access requests. Returns all stored profile data in a portable format.
- **get_contact_profile_schema** — Gets the contact profile schema for a Cognigy.AI project. The schema defines what custom fields can be stored in contact profiles.
- **set_contact_profile_schema** — Sets the contact profile schema for a Cognigy.AI project. Defines what custom fields can be stored in contact profiles. MUTATING: Set dryRun=false to update.
- **get_conversation_metrics** — Gets Cognigy.AI conversation counter metrics. Returns aggregated conversation counts for a project or entire organization over a time period.
- **get_call_metrics** — Gets Cognigy.AI call counter metrics (Voice Gateway). Returns aggregated call counts for a project or entire organization over a time period.
- **get_knowledge_query_metrics** — Gets Cognigy.AI Knowledge AI query metrics. Returns aggregated knowledge search/RAG query counts for a project or entire organization.
- **update_analytics_record** — Updates Cognigy.AI analytics records for a session. Use this to add custom tracking properties to conversation analytics. MUTATING: Set dryRun=false to update.
- **list_audit_events** — Lists Cognigy.AI audit events. Audit events track all changes made to resources (flows, intents, endpoints, etc.) by users. Useful for compliance and debugging.
- **get_audit_event** — Gets detailed information about a specific Cognigy.AI audit event. Returns the full change details including before/after values.
- **list_handover_providers** — Lists Cognigy.AI handover providers. Handover providers enable live agent escalation (e.g., Salesforce, Genesys, RingCentral).
- **get_handover_provider** — Gets detailed information about a specific Cognigy.AI handover provider. Returns provider type, configuration, and connection settings.
- **create_handover_provider** — Creates a new Cognigy.AI handover provider for live agent escalation. Configure providers like Salesforce, Genesys, or RingCentral. MUTATING: Set dryRun=false to create.
- **update_handover_provider** — Updates an existing Cognigy.AI handover provider. Use this to change settings or enable/disable the provider. MUTATING: Set dryRun=false to update.
- **delete_handover_provider** — Deletes a Cognigy.AI handover provider. WARNING: Endpoints using this provider will no longer be able to escalate to live agents. MUTATING: Set dryRun=false to delete.
- **list_handover_services** — Lists available Cognigy.AI handover services. Handover services are the supported integrations for live agent escalation.
- **get_handover_service** — Gets detailed information about a specific Cognigy.AI handover service. Returns service type, configuration schema, and supported features.
- **search_resources** — Searches across all Cognigy.AI resources in the organization. Finds flows, intents, endpoints, functions, playbooks, and more by name or content. Powerful for discovering resources across projects.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "cognigy-ai-mcp-management-server": {
    "command": "npx",
    "args": ["cognigy-ai-mcp-management-server"],
    "env": {
      "COGNIGY_BASE_URL": "",
      "COGNIGY_API_KEY": "",
      "COGNIGY_DEFAULT_PROJECT_ID": ""
    }
  }
}
```

**Requires environment variables:** `COGNIGY_BASE_URL`, `COGNIGY_API_KEY`, `COGNIGY_DEFAULT_PROJECT_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# Cognigy.AI Management MCP Server

[![CI](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/actions/workflows/ci.yml/badge.svg)](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/cognigy-ai-mcp-management-server)](https://www.npmjs.com/package/cognigy-ai-mcp-management-server)
[![npm downloads](https://img.shields.io/npm/dm/cognigy-ai-mcp-management-server)](https://www.npmjs.com/package/cognigy-ai-mcp-management-server)
[![node](https://img.shields.io/node/v/cognigy-ai-mcp-management-server)](https://www.npmjs.com/package/cognigy-ai-mcp-management-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Glama Score](https://glama.ai/mcp/servers/TsvetanG2/cognigy-ai-mcp-management-server/badges/score.svg)](https://glama.ai/mcp/servers/TsvetanG2/cognigy-ai-mcp-management-server)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.TsvetanG2/cognigy-ai-mcp-management-server)
[![MCP Badge](https://lobehub.com/badge/mcp/tsvetang2-cognigy-ai-mcp-management-server)](https://lobehub.com/mcp/tsvetang2-cognigy-ai-mcp-management-server)

![cognigy-ai-mcp-management-server](https://raw.githubusercontent.com/TsvetanG2/cognigy-ai-mcp-management-server/HEAD/docs/banner.png)

> 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](https://www.cognigy.com/) 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

```bash
# 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:

```bash
# 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:**
| Environment | Base URL |
|-------------|----------|
| Trial | `https://api-trial.cognigy.ai` |
| SaaS EU | `https://api-app.cognigy.ai` |
| SaaS US | `https://api-app-us.cognigy.ai` |
| Dedicated | `https://api-<company>.cognigy.cloud` |

## MCP Client Configuration

### Claude Desktop

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

```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"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project root:

```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"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```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](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/blob/master/TOOLS.md)

This server provides **132 MCP tools** organized by domain:

| Category | Tools | Description |
|----------|-------|-------------|
| **Projects & Flows** | 5 | List projects, flows, flow settings, logs |
| **Nodes** | 9 | CRUD operations, search, move, AI output generation |
| **Intents & NLU** | 10 | Intent management, training, scoring, audit |
| **Endpoints** | 2 | List and inspect endpoint configurations |
| **Sessions** | 2 | Inject/reset conversation context |
| **Conversations** | 3 | Fetch conversations, transcripts |
| **Playbooks & Testing** | 6 | Run playbooks, regression tests |
| **Snapshots** | 9 | Create, restore, package, diff, promote |
| **Packages** | 7 | Create, merge, upload, download |
| **Connections** | 5 | Manage API connections (secrets redacted) |
| **LLMs** | 7 | Configure generative AI providers |
| **NLU Connectors** | 5 | External NLU (Dialogflow, LUIS, etc.) |
| **Knowledge AI** | 21 | Stores, sources, chunks, connectors (RAG) |
| **Functions** | 9 | Custom code functions, instances |
| **Extensions** | 6 | Upload, configure, manage extensions |
| **Contact Profiles** | 11 | Profile CRUD, merge, export (GDPR) |
| **Analytics** | 4 | Conversation, call, knowledge metrics |
| **Audit** | 2 | Audit event logs |
| **Handover** | 7 | Live agent providers and services |
| **Search** | 1 | Organization-wide resource search |
| **Tasks** | 2 | Async task status tracking |

### 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

### Mock-first Development

Run against Prism mock server (no Cognigy account needed):

```bash
# Terminal 1: Start mock server
npm run mock

# Terminal 2: Run tests
npm test
```

### Live API Testing

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

# Run development server
npm run dev
```

### Build

```bash
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:

```bash
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](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/blob/HEAD/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](https://github.com/TsvetanG2/cognigy-ai-mcp-management-server/issues)
- **Cognigy Docs:** [docs.cognigy.com](https://docs.cognigy.com)
- **MCP Spec:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

---

Built with [Model Context Protocol](https://modelcontextprotocol.io) SDK