Configuring the Cortex MCP

You can host the MCP server locally, or you can use a remote implementation.

Prerequisites

The following are required prior to configuring the Cortex MCP:

1. Ensure that you have a compatible MCP client installed, such as Claude Desktop, Jetbrains AI Assistant, or Visual Studio Code (VSCode). Paid subscriptions to MCP clients generally give you a larger context window, but the free versions of these clients should suffice.

2. If hosting the MCP server locally, Docker must be installed and running.

3. Create a personal access token in Cortex. See Creating personal access tokens.

Configuring the Cortex MCP

Follow the steps below to configure the Cortex MCP.

Hosting the Cortex MCP server locally

Follow the steps below if the MCP server is hosted locally.

Step 1: Installing the Cortex MCP

Open terminal and run the following command:

docker pull ghcr.io/cortexapps/cortex-mcp:latest

Step 2: Configuring your MCP client

Looking for IDE-specific setup? See the README

Update your MCP client's configuration file. Make sure to include your Cortex personal access token value for the CORTEX_API_TOKEN argument:

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--pull",
        "always",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN_HERE",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}

Alternate option: Create and configure the file in terminal

Alternatively, you could enter the following in terminal to create and configure the file:

export CORTEX_API_TOKEN=VALUE_OF_YOUR_PERSONAL_ACCESS_TOKEN
cat << EOF > ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--pull",
        "always",
        "--rm",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=${CORTEX_ACCESS_TOKEN}",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
 }
}
EOF

Step 3: Restarting your MCP client

After updating your configuration, restart your MCP client.

Hosting the Cortex MCP server remotely

The remote Cortex MCP uses the public cortex-mcp package as a dependency, installed from GitHub. This configuration of the Cortex MCP enables:

• Faster setup - No need to install or maintain local binaries.

• Updated context - Cortex automatically keeps the service aligned with the latest MCP specification.

• Secure access - Tokens and access are managed in your Cortex workspace with security best practices.

• Seamless integration - It works out of the box with popular MCP clients like VSCode, Claude Code, and Cursor.

• More tools - The remote MCP implementation includes more tools, such as the query_docs tool that allows you to query Cortex's documentation and knowledge base in natural language. Ask questions like How do I configure PagerDuty for my Cortex services?, or How can I use Cortex to drive AI maturity at my org? It also includes the ability to add private tools and integrations on top of the public functionality.

Step 1: Adding the remote MCP server to your MCP client

Follow the instructions below for Claude, VSCode, or Cursor. Make sure to replace <CORTEX_TOKEN> with the value of the personal access token you generated in Cortex.

Claude Code

Run the following command to add the Cortex remote MCP server:

claude mcp add --transport http cortex-remote https://mcp.cortex.io/mcp --header "Authorization: Bearer <CORTEX_TOKEN>"

VSCode

Add the following configuration to your .vscode/mcp.json file:

{
  "servers": {
    "cortex": {
      "url": "https://mcp.cortex.io/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <CORTEX_TOKEN>"
      }
    }
  }
}

For more information, see the official VSCode documentation.

Cursor

Add the following configuration to your Cursor settings:

{
  "mcpServers": {
    "cortex": {
      "type": "http",
      "url": "https://mcp.cortex.io/mcp",
      "headers": {
        "Authorization": "Bearer <CORTEX_TOKEN>"
      }
    }
  }
}

Step 2: Validating your remote MCP configuration

Validate that your remote Cortex MCP is working:

• VSCode - Open the Command Palette and search for "MCP: List servers." Confirm that cortex appears as a connected server.

• Claude - Run the command claude mcp list and verify that cortex-remote is in the list of servers.

• Cursor - Open Settings > MCP Servers and verify that cortex is listed and connected.

Step 3: Restarting your MCP client

After updating your configuration, restart your MCP client.

Self-managed additional configuration

If you are a self-managed Cortex customer, you must also set CORTEX_API_BASE_URL=https:// alongside the CORTEX_API_TOKEN variable.

Self-managed configuration example

Set the CORTEX_API_BASE_URL to your backend host URL:

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--pull",
        "always",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=YOUR_ACCESS_TOKEN_HERE",
        "--env",
        "CORTEX_API_BASE_URL=https://api.cortex.company.com",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}

If you are running a self-hosted instance with CA-signed certificates, you may need to mount them to the container as seen in the example below:

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--pull",
        "always",
        "-i",
        "-v",
        "/path/to/your//company_certs.ca:/etc/ssl/certs/company-ca.crt:ro",
        "--env",
        "REQUESTS_CA_BUNDLE=/etc/ssl/certs/company-ca.crt",
        "--env",
        "SSL_CERT_FILE=/etc/ssl/certs/company-ca.crt",
        "--env",
        "CURL_CA_BUNDLE=/etc/ssl/certs/company-ca.crt",
        "--env",
        "CORTEX_API_TOKEN=YOUR_ACCESS_TOKEN_HERE",
        "--env",
        "CORTEX_API_BASE_URL=https://api.cortex.company.com",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}