Cortex MCP

Cortex MCP is a Model Context Protocol server that provides access to the Cortex API. It uses relevant context from your workspace, ensuring awareness of your system's structure when answering your questions.

You can query information in natural language, powering faster decisions and efficient processes. For example:

• Who is the right person to handle an incident with backend-server?

• Show me the services that belong to the platform engineering team

• Show me the currently active Scorecards and how example-entity is performing. Give me ideas on how I can improve them

• We're having an incident with backend-server, give me a summary of information to help handle the incident

• What's going on with my Git migration Scorecard?

• I want to run an initiative to migrate our company to using GitHub actions. Help me figure out how to do this in Cortex

• As someone on the security team, is there anything I should be worried about in my org?

Learn about crafting effective prompts and see Cortex's MCP Prompt Library below.

Use Cortex MCP with Devin Cortex MCP is available in the Devin marketplace. Cortex MCP identifies the work that needs to be done, and Devin autonomously performs the work — creating PRs, updating documentation, and refactoring code — to bring your services into compliance. Learn more in our blog.

Cortex MCP demonstration video

See a demonstration of how you can use Cortex MCP to get quick answers without having to switch tools:

How to configure Cortex MCP

You can host the MCP server locally, or you can use a remote implementation (available in beta).

Prerequisites

Before getting started:

• Create an access token in Cortex.

• You should have an MCP-compatible 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.

• If hosting the MCP server locally, you should also have Docker installed and running.

Configure the MCP

Host locally

Step 1: Install Cortex MCP

Run the following command:

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

Step 2: Configure your MCP client

Looking for IDE-specific setup? Our README has detailed configuration steps for Claude Desktop, Cursor, VS Code, and other MCP clients.

Update your MCP client's configuration file. Make sure to include your Cortex 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

Remote MCP server

Remote Cortex MCP is available in public beta. Please contact your Cortex Customer Success Manager for access or to report any issues.

Benefits of using the remote MCP

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 Desktop, 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: Add 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 access token you generated in Cortex.

Claude

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 VSCode MCP Servers 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: Validate 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.

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"
      ]
    }
  }
}

Using Cortex MCP

Research Preview

Not seeing the results you expect? This is an early version of the Cortex MCP. Please send feedback and bug reports to Cortex Customer Engineering.

Start a new chat

In your MCP client, ask a question about your Cortex workspace. The client will use the Cortex API to provide detailed answers based on your data.

For example:

• You might ask what's going on with a specific Scorecard. The MCP client will respond with an overview, Scorecard structure information, a progress summary, and suggestions for next steps.

  
• You could ask about the custom data that an entity has. The MCP client will respond with that entity's custom data and information about when it was created:

  
• You could ask about the dependencies an entity has. The MCP client will respond with a list of incoming and outgoing dependencies:

  

Available MCP tools

Cortex MCP can use the following Cortex REST API endpoints:

• listAllEntities

• listEntityDescriptors

• listDependenciesForEntity

• getDependency

• getEntityDetails

• getCustomDataForEntity

• getCustomDataForEntityByKey

• getCurrentOncallForEntity

• getEntityDescriptor

• listInitiatives

• getInitiative

• listRelationshipTypes

• getRelationshipTypeDetails

• listEntityRelationships

• listScorecards

• getScorecard

• getScorecardNextStepsForEntity

• listScorecardScores

Eng Intelligence metrics are also available to Cortex MCP as part of the Chief of Staff research preview feature. Learn more in Chief of Staff (Research Preview).

Enable and disable provided tools

Before submitting questions or commands, you may want to limit the number of provided tools being used by the MCP provider. For example, you might only want to use the MCP to ask about entities but you do not want to allow questions about Scorecards.

In the settings of your MCP client, it is possible to limit which Cortex tools are being used.

For example, in Claude desktop:

1. Navigate to Settings > Connectors > Cortex > 3 dots icon > Tools and Settings.

2. Under PROVIDED TOOLS, toggle off the options you don't need.

3. Restart Claude.

4. Navigate to your Claude chat and enter commands.

Crafting effective MCP prompts

Best practices

The Cortex MCP becomes more powerful when using it becomes second nature to your teams. That shift happens when you have developed prompts that fit your specific role, answer your recurring questions, and surface information in the exact moments you need it. Follow these best practices when crafting prompts:

• Be specific: Instead of "tell me about services," you could say, "Show me all critical services failing the Production Readiness Scorecard." This will give you more actionable information.

• Combine multiple questions when context helps: The MCP handles complex prompts like "Who owns orders-api, when was it last deployed, and are there any open incidents?" You get richer context in response to one question instead of piecing together three separate queries.

• Reference your organization's specific constructs: If you've defined custom Scorecards or Initiatives in Cortex, reference them by name. The MCP understands your organization's specific standards and can query against them directly.

• Use follow-up questions to drill down: Start broad, then go narrow. "Show me services with failing Scorecards" followed by "What specific checks is checkout-service failing?" moves you from landscape view to action items.

• Build a library of your most-used prompts: If you ask the same question every Monday morning, save it. Some teams maintain shared prompt libraries so everyone can benefit from patterns that work. See the Cortex MCP Prompt Library below for ideas.

MCP Prompt Library

We've collated the most effective prompt patterns we've seen across different roles and workflows to build out a library of prompts for engineers, engineering leaders, platform engineers, and SREs. See Cortex MCP Prompt Library for the full list of prompts.

Additional information

For more information, see the Cortex MCP repository in GitHub.

See the beta pages to learn more about the remote Cortex MCP (now available in public beta) and the Chief of Staff, which enables the use of Engineering Intelligence metrics in MCP (now available in research preview).

Troubleshooting and FAQ

When I ask a question in my MCP client, why do I see an error that says I hit the maximum length for this chat?

This can happen if you are on the free plan of your MCP client.

How do I resolve "unauthorized" errors in the MCP?

Ensure that the value of your Cortex API token is valid in your configuration.

How do I resolve "file not found" errors in the MCP?

Ensure that your OpenAPI spec path is correct when mounting.

How do I resolve connection issues with the MCP?

Verify that your Cortex API endpoint is accessible.

How do I resolve a 403 forbidden error in the remote MCP?

Ensure that you are opted in to the beta for the remote MCP. Contact your Cortex account team to make sure you have been granted access. Also check that you are setting up the remote MCP with a personal access token generated in Cortex. Remote MCP setup requires a PAT, not an API key.

Why might I see an SSL certificate error while using the MCP?

This is most likely caused by an issue within your network. We recommend contacting your organization's infrastructure or security team to troubleshoot.