MCP Server - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /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 or 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
• Data Protection & Analytics
• Transformer Functions

Specific Endpoint Settings

MCP Explorer

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.

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.

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:

4. Select the MCP Server Endpoint type.

5. Specify a unique name.

6. Save changes.

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

8. In the Configuration Information section, copy the URL in the MCP Server URL field.

9. Activate the Enable MCP Server toggle to start the server and allow clients to connect.

10. 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: <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: <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: <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