> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/get-started/cortex-ai-assistant/mcp/configuring-cortex-mcp.md).

# 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](https://claude.ai/download), [Jetbrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html), or [Visual Studio Code (VSCode)](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). 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](https://www.docker.com/) must be installed and running.
3. Create a personal access token in Cortex. See [Creating personal access tokens](/configure/settings/api-keys/personal-tokens.md).

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

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

#### Step 2: Configuring your MCP client

{% hint style="info" %}
Looking for IDE-specific setup? See the [README](https://github.com/cortexapps/cortex-mcp?tab=readme-ov-file#installation)
{% endhint %}

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

```json
{
  "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:

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

For more information, see the [official VSCode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).

**Cursor**

Add the following configuration to your Cursor settings:

```json
{
  "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](/self-managed.md), 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:

```json
{
  "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:

```json
{
  "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"
      ]
    }
  }
}
```