## Documentation Index Fetch the complete documentation index at: [/llms.txt](https://docs.cognigy.com/llms.txt) Use this file to discover all available pages before exploring further. The MCP Server Endpoint is experimental and isn’t recommended for production use. This Endpoint may change or be removed in future releases. Use it only in development or staging environments. The MCP Server Endpoint allows external AI applications to use tools from an AI Agent in Cognigy.AI via the Model Context Protocol (MCP). Compatible clients, such as desktop AI assistants or custom MCP applications, can discover and execute these tools. Unlike standard Endpoints, the MCP Server Endpoint isn’t designed for conversational use. It doesn’t use NLU, process user messages, or perform real-time translation. Instead, it works as a tool server: clients discover the available tools and invoke them using structured requests. Cognigy.AI then executes the corresponding Flow logic and returns the results through the MCP protocol. ## Key Benefits - **Tool Access through MCP**. Tools configured under an [AI Agent](https://docs.cognigy.com/ai/agents/overview) or [LLM Prompt](https://docs.cognigy.com/ai/agents/develop/node-reference/service/llm-prompt) Node are available to MCP-compatible clients. - **Direct Flow Execution**. When a tool is called, Cognigy.AI executes the related Flow and returns the result through MCP. - **Standard Integration**. MCP provides a consistent interface for connecting external applications without custom APIs. ## Restrictions - The following tools are available via MCP: - Regular Tool - Knowledge Search - Send Email - Execute Workflow - Handover to AI Agent - Tool calls must finish within the configured timeout. The default timeout is 30 seconds. If you have an on-premises installation, you can change the default value via the `MCP_SERVER_TOOL_CALL_TIMEOUT` variable. - This Endpoint supports OAuth 2.0 and no-authentication modes. User-level authentication isn’t supported. ## Prerequisites - A Flow that contains either an AI Agent or LLM Prompt Node. - The AI Agent Node or LLM Prompt Node in the Flow must include at least one Tool Node. - Each Tool Node has a tool ID and a description. ## Generic Endpoint Settings - [Advanced: Mocking](https://docs.cognigy.com/ai/agents/test/mocking) - [Data Protection & Analytics](https://docs.cognigy.com/ai/agents/deploy/endpoints/data-protection-and-analytics) - [Transformer Functions](https://docs.cognigy.com/ai/for-developers/transformers/overview) ## Specific Endpoint Settings MCP Explorer | **Parameter** | **Description** | | --- | --- | | MCP Explorer | A link to test your tools and view connection details. It displays all exposed tools, including their names, descriptions, and parameters, and allows validation and testing of the configuration. The MCP Explorer also provides ready-to-use configuration snippets for Claude Desktop and Cursor, with a server key based on the Endpoint name. | AI Agent Selection This section allows you to select the Flow and AI Agent Node that will expose its tools via the Model Context Protocol (MCP). External AI clients can discover and call these tools through this endpoint. | **Parameter** | **Description** | | --- | --- | | Flow | The Flow that contains the selected AI Agent Node. | | Node | The AI Agent or LLM Prompt Node whose child Tool Nodes are exposed via MCP. Only tools defined as children of the selected Node are exposed to MCP clients. | | Exposed Tools | Displays all exposed tools. | Configuration Information This section provides the MCP Server URL and a list of all exposed tools, including their names, descriptions, and parameters. This information is required to configure MCP clients. | **Parameter** | **Description** | | --- | --- | | MCP Server URL | The dedicated MCP URL in the format `https://endpoint.cognigy.ai/mcp/v1/{token}/mcp`. This is the single entry point for all MCP traffic and must be kept confidential. | | Enable MCP Server | Activates the MCP Server functionality for the Endpoint. | ## How to Set Up The diagram shows the complete MCP workflow. First, make sure your Flow is set up correctly with an AI Agent Node and a Tool Node, according to the prerequisites. Then, the MCP client connects to the MCP Server Endpoint and calls a tool. This triggers the Flow execution. The result is returned through a session-based connection. ### Setup on the Cognigy.AI Side Configure an MCP Server Endpoint 1. In the left-side menu of your Project, click **Deploy > Endpoints**. 2. On the **Endpoints** page, click **\+ New Endpoint**. 3. In the **New Endpoint** section, do the following: 1. Select the **MCP Server** Endpoint type. 2. Specify a unique name. 3. Save changes. 4. In **AI Agent Selection**, select the Flow and the AI Agent Node or LLM Prompt whose tools you want to expose via MCP. Save changes. 5. In the **Configuration Information** section, copy the URL in the **MCP Server URL** field. 6. Activate the **Enable MCP Server** toggle to start the server and allow clients to connect. 7. Go to the **Authentication** section. From the **Authentication Type** list, select the authentication method for the MCP server: - **None** — no authentication is required to access the MCP server. Use this option for internal or trusted environments only. The option is selected by default. - **OAuth 2.0**— activate token-based authentication using OAuth 2.0. Use this option to verify that only authorized clients can access the MCP server. Configure the following fields: - **JWKS URI** — the URL of the JSON Web Key Set (JWKS) endpoint used to verify token signatures. You can find this URL in your identity provider’s OpenID Connect discovery document, typically at `/.well-known/openid-configuration`. For example, `https://your-idp.example.com/.well-known/jwks.json`. - **Issuer** — the expected token issuer. This value must match the `iss` claim in the JWT. You can find this value in your identity provider’s app settings, often labeled **Issuer URL** or **Authority**. For example, `https://your-idp.example.com`. - **Audience** — the intended recipient of the token. This value must match the `aud` claim in the JWT. You can find this value when registering your application with the identity provider such as the client ID or a custom API identifier. For example, `cognigy-mcp-client`. - **Required Scopes** — the OAuth scopes that the token must include to be granted access. Define these scopes in your identity provider when configuring the application or API permissions. For example, `cognigy:mcp`. - **Allowed Subject IDs** — this field is optional. A comma-separated list of subject identifiers (`sub` claim) permitted to access the server. You can find the subject ID in the JWT payload or in your identity provider’s user or service account settings. For example, `user-123, service-account-456`. If the field is empty, all subjects are allowed. - **Key Refresh Interval (minutes)** — this field is optional. The frequency at which the JWKS public keys are refreshed. Increase this value to reduce the number of requests to your identity provider. For example, `60`. ### Setup on the Third-Party Provider Side Configure an MCP Client The configuration depends on the MCP client you use. - Direct HTTP Integration - Claude Desktop - Cursor The MCP Server Endpoint supports the MCP Streamable HTTP transport. To integrate directly with the Endpoint, follow these steps: 1. Send an `initialize` request. ``` curl -i -X POST https://endpoint-dev.cognigy.ai/mcp/v1/{token}/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "test", "version": "1.0" } } }' ``` Replace `{token}` with the token from the MCP Server URL. 2. The response will include `mcp-session-id: `. Store the session ID for use in subsequent requests. 3. Request a list of available tools via `tools/list`: ``` curl -X POST https://endpoint-dev.cognigy.ai/mcp/v1/{token}/mcp \ -H "Content-Type: application/json" \ -H "mcp-session-id: " \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }' ``` The request returns the list of available tools with their parameters and descriptions. This allows the client to understand how to call each tool correctly. For example, the response may include tools like this: ``` { "jsonrpc": "2.0", "id": 2, "result": { "tools": [ { "name": "mcp", "description": "", "inputSchema": { "type": "object", "properties": {}, "required": [] } }, { "name": "SearchCognigyDocumentation", "description": "", "inputSchema": { "type": "object", "properties": {}, "required": [] } }, { "name": "unlock_account", "description": "This tool unlocks a locked user account.", "inputSchema": { "type": "object", "properties": { "email": { "type": "string", "description": "User's login email for their account." } }, "required": ["email"] } } ] } } ``` 4. Call tools using the `tools/call` method, providing the tool name and required arguments. For example, to call the `unlock_account` tool with the required `email` argument, send the following request: ``` curl -X POST https://endpoint-dev.cognigy.ai/mcp/v1/{token}/mcp \ -H "Content-Type: application/json" \ -H "mcp-session-id: " \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "unlock_account", "arguments": { "email": "user@example.com" } } }' ``` After a successful tool call, the MCP server returns the result in a structured MCP response. The response contains the output of the executed tool inside the result field. For example, if the tool completes successfully, it may return a text message such as `Resolved` in the content array. ``` { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "Resolved" } ] } } ``` To configure the MCP client in Claude Desktop, follow these steps: 1. In the Claude Desktop application, go to **Settings > Developer > Local MCP servers**. Click **Edit Config**. 2. Add the following configuration to `claude_desktop_config.json`: ``` { "mcpServers": { "my-endpoint-name": { "command": "npx", "args": [ "mcp-remote", "https://endpoint.cognigy.ai/mcp/v1/{token}/mcp" ] } } } ``` Replace `{token}` with the token from the MCP Server URL and `my-endpoint-name` with a name for your Endpoint. The MCP Explorer automatically generates a key based on the Endpoint name. 3. Close and reopen Claude Desktop. It automatically launches `mcp-remote`, connects to the MCP server, initializes the session, and loads the available tools. 4. In Claude Desktop, open the chat and ask the AI to perform a task that requires a tool. Claude Desktop will automatically call the appropriate MCP tool when needed. To configure the MCP client in Cursor, follow these steps: 1. In the root directory of your Cursor project, create the `.cursor/mcp.json` file. If the `.cursor` folder doesn’t exist, create it manually. 2. Add the following configuration to the `mcp.json` file: ``` { "mcpServers": { "my-endpoint-name": { "command": "npx", "args": [ "-y", "mcp-remote", "https://endpoint.cognigy.ai/mcp/v1/{token}/mcp" ] } } } ``` The `-y` flag lets `npx` run the package without asking for confirmation. Replace `{token}` with the token from the MCP Server URL and `my-endpoint-name` with a name for your Endpoint. The MCP Explorer automatically generates a key based on the Endpoint name. 3. Close and reopen Cursor. It automatically launches `mcp-remote`, connects to the MCP server, initializes the session, and loads the available tools. 4. Open the Cursor Chat in Agent mode. Ask the AI to perform a task that requires a tool. Cursor will automatically call the appropriate MCP tool when needed. ## Use Cases Access Knowledge Bases External AI clients can use MCP to query Cognigy knowledge bases through the Knowledge Search Tool. This approach enables real-time retrieval of relevant content, such as product information, policies, or support articles, directly from connected applications. Automate Business Tasks MCP clients can trigger operational workflows, such as CRM lookups, ticket creation, or email notifications. When a tool is called, the corresponding Flow is executed, allowing existing business logic to run without modification. Expose Internal Logic Existing Flows can be published as callable tools. This approach allows organizations to reuse and expose internal automation, decision logic, and AI Agent configurations as standardized tools available to external systems. Connect Custom Applications Custom AI applications, development environments, or third-party systems can integrate with Cognigy.AI through the MCP protocol. This approach enables structured tool calls and consistent result handling without building and maintaining custom APIs. ## Troubleshooting | **Issue** | **Cause** | **Solution** | | --- | --- | --- | | Tools Not Visible | The AI Agent Node doesn’t contain tool Nodes, or tools are missing a tool ID or description. The wrong Flow or Node may be selected. | Ensure the AI Agent Node includes Tool Nodes. Verify that each tool has a tool ID and description. Confirm the correct Flow and Node are selected in the Endpoint settings. | | Tool Call Times Out | The tool execution exceeds the default 30-second timeout. | If you have an on-premises installation, adjust the `MCP_SERVER_TOOL_CALL_TIMEOUT` configuration if a longer execution time is required. | | Connection Fails | The full MCP URL isn’t specified, or an incorrect path is configured. | Ensure you are using the complete URL in the format `/mcp/v1/{token}/mcp`. The Endpoint doesn’t respond on other paths. | | Session Expired | The MCP session has timed out due to inactivity. | Reinitialize the session by sending a new `initialize` request without a session ID. | | Authentication Failed | The Bearer token is missing, expired, or doesn’t include the required scopes. | Verify that the token is valid and includes the scopes configured in the **Required Scopes** field. Re-authenticate if the token has expired. | | The **Run Test** Button in the MCP Explorer isn’t Active | A reverse proxy or security layer is changing the Content Security Policy (CSP) headers set by the MCP Explorer page. | The MCP Explorer sets its own CSP headers using nonce-based script allowlisting. Make sure upstream proxies or security tools don’t remove or change these headers. Contact your platform administrator if CSP changes are needed.