Install the Cortex MCP server - Download, install, and configure the MCP server on your local machine or a container. - Administrator Guide - Cortex - Cortex - Security Operations

Cortex MCP server
Product
Cortex
Creation date
2025-11-03
Last date published
2025-11-04
Category
Administrator Guide
Abstract

Download, install, and configure the MCP server on your local machine or a container.

With the Cortex MCP Server, you can use natural language in your MCP client to investigate and manage cases and issues. The MCP Server can be run within a Docker container or a Poetry virtual environment. .

This documentation contains instructions for configuring and using the Cortex MCP server. More detailed setup instructions are provided in a README file included in the download.

These instructions use Claude Desktop, but you can use any client that supports MCP.

Prerequisites

If you are running the Cortex MCP server in a Poetry virtual environment, you must have Python 3.13 or higher.

If you plan to run the Cortex MCP server in a Docker container, you must have Docker installed.

Step 1: Create an API key

Note

The MCP Server uses public APIs to communicate and is limited by the license quotas available in your tenant. This is particularly relevant when running XQL queries. For more information on running XQL query APIs, see Run XQL query APIs.

  1. Select Settings → Configurations → Integrations → API Keys → New Key.

  2. In the Role tab, perform for the following:

    1. Under Security Level, select Standard.

    2. Under Role, select the desired level of access for this key. You can select from predefined roles or custom roles. Roles are available according to what was defined in either the Cortex Gateway or the tenant's Access Management. You can view the configuration of the role selected by expanding the sections under Components.

      Note

      It is critical to avoid assigning excessive permissions when creating an API key for the Cortex MCP Server. Since the key has both read and write capabilities, overly broad permissions can lead to unintended actions and potentially compromise your environment. Ensure the key follows the principle of least privilege and is granted only the minimum required access.

    3. (Optional) Under Comment, provide a comment that describes the purpose of the API key.

    4. (Optional) If you want to define a time limit on the API key authentication, select Enable Expiration Date, and select the expiration date and time. You can track the expiration date of each API key in the API Keys page. In addition, a API Key Expiration notification appears in the Notification Center one week and one day prior to the defined expiration date.

  3. (Optional) If Scope-Based Access Control (SBAC) is enabled for the tenant, click Scope, and under Scope Definition, select the scope areas that you want to limit the user role to access for this API.

  4. Click Generate to generate the API key.

  5. Copy the generated API key and click Done.

    Important

    To configure the Cortex MCP Server, you need the Cortex API URL, Cortex API key, and Cortex API key ID. You will not be able to view the API key again after you complete this step. Ensure that you copy the API key before closing the notification.

Step 2: Download and install the Cortex MCP server

  1. Go to Settings → Configurations → Integrations → Cortex MCP Server.

  2. Download MCP File

  3. (Optional) Download the checksum file and run a command such as shasum (Linux/macOS) or certutil (Windows) to verify the integrity and authenticity of the file. For example: shasum -a 256 -c cortex-checksum.zip.sha256.

  4. Extract the .zip file.

  5. Follow the detailed instructions in the README.md file located in the top directory. Instructions are provided for both Docker and Poetry and include the following:

    Docker

    • Create an .env file with the environment variables.

      Note

      When using Docker, we recommend using an .env file to set the Cortex API credentials as environment variables. While the credentials can be provided in the MCP client configuration settings, the .env file provides safer handling of API credentials and makes your configuration easily reproducible.

    • Build and run the Docker container.

    Poetry

    • Install Poetry.

    • Create and activate a virtual environment.

    • Install project dependencies.

    • Provide the required variables in the Python runtime environment.

Step 3: Run the Docker container or start the server in the Poetry virtual environment

Note

By default, stdio (standard input/output) is used. You can also configure Streamable HTTP, to send requests directly to the tenant instead of through the MCP client. Streamable HTTP can be useful for testing in the browser without a MCP client and to bypass limits that may be in place for your MCP client. For Docker, you can include the Streamable HTTP variables in the .env file. You can also include it as a flag when you start the server in the Python virtual environment.

Docker

docker run --env-file .env -it cortex-mcp

Poetry virtual environment

python src/main.py

When using the Poetry virtual environment, you can also start the server using the CLI command python src/cli.py start [OPTIONS, where [OPTIONS] includes the API key id, API key, the Cortex PAPI server URL, and the log level.

Use the CLI

From the CLI, you can run three commands.

  • start: Start the Cortex MCP server. Relevant only for the Poetry virtual environment.

  • update: Any new or updated components provided by Cortex are automatically downloaded into the remote_components folder.  During each update, the folder is fully replaced and all existing contents are recreated. Do not add custom tools to this directory, as it is managed entirely by Cortex and is overwritten at every update.

  • version: Display the current version of the Cortex MCP Server.

Additional information about the CLI is available in the README file located in the src directory.