# 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 `` 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 " ``` **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 " } } } } ``` 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 " } } } } ``` #### 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" ] } } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cortex.io/get-started/mcp/configuring-cortex-mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.